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