Garoon APIとUser APIで取得できるユーザー情報・組織情報の違いと注意点

目次

はじめに

Garoonカスタマイズをするとき、ユーザー情報や組織情報を利用する場合があります。

実は、Garoon API( Garoon JavaScript APIおよび Garoon REST API)でユーザー情報を取得する以外にも、cybozu.comの User APIを使ってユーザー情報や組織情報を取得できます。
User APIを使うと、Garoon APIで取得できるユーザー情報や組織情報よりも詳しい情報を取得できます。

この記事では、Garoon APIとUser APIで取得できるユーザー情報や組織情報の違いと、GaroonカスタマイズでUser APIを利用するときの注意点を解説します。

Garoon APIとUser APIで取得できるユーザー情報や組織情報の違い

ユーザー情報

Garoon APIとUser APIでユーザー情報を取得するAPIおよび取得内容は、次のとおりです。

Garoon JavaScript API

ログインユーザーの情報を取得する - garoon.base.user.getLoginUser()

レスポンス例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "garoonId": "508",
  "name": "山田 太郎",
  "timezone": "Asia/Tokyo",
  "language": "ja",
  "id": "520",
  "code": "yamada-taro",
  "email": "yamada-taro@example.com",
  "url": "",
  "phone": "03-4306-0804"
}

ログインしているユーザー情報のみ取得可能。

Garoon REST API

ユーザーの一覧を取得する - /g/api/v1/base/users

レスポンス例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "users": [
    {
      "id": "508",
      "name": "山田 太郎",
      "code": "yamada-taro"
    }
  ],
  "hasNext":false
}
User API

ユーザーを取得する - /v1/users.json

レスポンス例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "users": [
    {
      "id": "520",
      "code": "yamada-taro",
      "ctime": "2019-01-01T00:00:00Z",
      "mtime": "2019-05-08T05:10:44Z",
      "valid": true,
      "name": "山田 太郎",
      "surName": "山田",
      "givenName": "太郎",
      "surNameReading": "やまだ",
      "givenNameReading": "たろう",
      "localName": "",
      "localNameLocale": "ja",
      "timezone": "Asia/Tokyo",
      "locale": "",
      "description": "",
      "phone": "03-4306-0804",
      "mobilePhone": "",
      "extensionNumber": "9999",
      "email": "yamada-taro@example.com",
      "callto": "",
      "url": "",
      "employeeNumber": "001111",
      "birthDate": "2019-05-09",
      "joinDate": "2019-01-01",
      "primaryOrganization": "1",
      "sortOrder": null,
      "customItemValues": []
    }
  ]
}

プロパティの詳細については、 User型を参照してください。

Garoon APIに比べてUser APIのほうが、取得できる内容は多いです。

ユーザー情報の項目 (External link) で設定できる詳細なユーザー情報(「従業員ID」など)を取得したい場合は、User APIを利用しましょう。

組織情報

Garoon JavaScript API

なし

Garoon REST API

組織の一覧を取得する - /g/api/v1/base/organizations

レスポンス例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "organizations": [
    {
      "id": "1",
      "name": "営業部",
      "code": "sales",
      "parentOrganization": null,
      "childOrganizations": []
    }
  ],
  "hasNext": false
}
User API

組織を取得する - /v1/organizations.json

レスポンス例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "organizations": [
    {
      "id": "1",
      "code": "sales",
      "name": "営業部",
      "localName": "Sales",
      "localNameLocale": "en",
      "parentCode": null,
      "description": "営業活動を行います"
    }
  ]
}

プロパティの詳細については、 Organization型を参照してください。

ユーザー情報と同様、User APIのほうが、取得できる内容は多いです。
組織情報の項目 (External link) で設定できる組織情報(「説明」や「別言語での表示名」など)を取得したい場合は、User APIを利用しましょう

GaroonカスタマイズでUser APIを利用するときの注意点

GaroonカスタマイズでUser APIを利用するとき、注意しなければならないことがあります。

それは、Garoon REST APIで取得したユーザー情報のidと、User APIで取得したユーザー情報のidは違う意味を持っているということです。

Garoon REST APIの 1件の予定を取得する APIで取得したスケジュール情報を例に説明します。

スケジュールがもつユーザー情報はいくつかありますが、そのうちのひとつ、参加者を表すattendeesに注目してください。
attendeesプロパティを見ると、「山田太郎」さんのidは「508」で、codeは「yamada-taro」です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  // 略
  "subject": "打ち合わせ",
  "attendees": [
    {
      "id": "508", // ここに注目
      "name": "山田 太郎",
      "type": "USER",
      "code": "yamada-taro"
    }
  ],
  // 略
}

次に、「山田太郎」さんのユーザー情報をUser APIを使って取得します。
レスポンス結果を見ると、「山田太郎」さんのidは「520」になっていて、Garoon REST APIで取得したときのユーザー情報のidと異なっています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "users": [
    {
      "id": "520", // ここに注目
      "name": "山田 太郎",
      "code": "yamada-taro",
      // 略
    }
  ]
}

さらに、「山田太郎」さんでログインしたときの、Garoon JavaScript ログインユーザーの情報を取得する APIで取得したユーザー情報は次のようになります。
レスポンス結果からプロパティ名を確認すると、Garoon REST APIで取得したときのid「508」はGaroond、User APIを使って取得したときのid「520」は、idとなっています。

1
2
3
4
5
6
7
{
  "id": "520", // User APIで取得したユーザー情報のidと同じ
  "garoonId": "508", // Garoon REST APIで取得したユーザー情報のidと同じ
  "name": "山田 太郎",
  "code": "yamada-taro",
  // 略
}

解説

Garoon REST APIで取得したときのユーザー情報のidとUser APIで取得したユーザー情報のidは、それぞれ、次に示す異なる内容を指しています。

  • Garoon REST APIで取得したユーザー情報のid:GaroonユーザーID
  • User APIで取得したユーザー情報のid:cybozu.comユーザーID

そのため、Garoon REST APIで取得したスケジュール参加者のユーザー情報をUser APIで取得するとき、idを使うとまったく違うユーザーの情報を引き当ててしまいます

では、Garoon REST APIのユーザー情報からUser APIのユーザー情報を紐付けるときはどうすればよいでしょうか?

下図に、Garoon REST API、User API、Garoon JavaScript API(ログインユーザー情報の取得)の関係を示します。
図より、code(ログイン名)がGaroon REST APIとUser APIで共通しています。

このことから、Garoon REST APIで取得したユーザー情報とUser APIを紐付ける場合、code(ログイン名)を利用すればよいことがわかります。

また、Garoon REST APIの中には、 複数の予定を取得する APIのように、ユーザーで絞って検索するときにGaroonユーザーIDのみ指定可能なAPIもあります。
このときにユーザーの詳細情報も利用する場合には、APIを呼ぶ順序が重要です。
まず、GaroonユーザーIDを使ってGaroon REST APIを呼んで情報を取得したのち、取得した情報に含まれているログイン名を使ってUser APIを呼ぶ必要があります。

おまけ:Garoonとkintoneのユーザー情報を紐付ける

Garoonとkintoneを連携するとき、ユーザー情報を紐付けるにはどのプロパティを使えばよいでしょうか?
さきほどの図にkintoneの関係も加えてみましょう。

kintone JavaScript APIの ログインユーザーの情報を取得する APIのユーザー情報のidは、User APIのユーザー情報のidと同じ、cybozu.comユーザーIDを指していますね。
code(ログイン名)は、Garoon REST APIやGaroon JavaScript APIで取得したユーザー情報のcodeと共通しています。

このことから、Garoonのユーザー情報とkintoneのユーザー情報を紐づけたい場合はcode(ログイン名)を利用すればいいですね。

おわりに

Garoonカスタマイズで、 ユーザーの設定 (External link) 組織の設定 (External link) で設定した詳細な情報がほしい。
そんなときはUser APIを使うと取得できることを紹介しました。
ただし、Garoon REST APIのユーザー情報のidとUser APIのユーザー情報のidは違う意味をもつため、両者を紐付けるときはcodeを使う必要があります。

次回の記事 User APIのユーザー情報を使ってGaroonワークフローをカスタマイズするでは、実際にUser APIを利用したGaroonカスタマイズを紹介します。

information

このTipsは、2019年5月版Garoonで動作を確認しています。