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で動作を確認しています。