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 でユーザー情報を取得する 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 のほうが、取得できる内容は多いです。

ユーザー情報の項目 で設定できる詳細なユーザー情報（「従業員 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 のほうが、取得できる内容は多いです。
組織情報の項目 で設定できる組織情報（「説明」や「別言語での表示名」など）を取得したい場合は、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 を連携するとき、ユーザー情報を紐付けるにはどのプロパティを使えばよいでしょうか？
さきほどの図に kintone の関係も加えてみましょう。

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

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

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

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

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