はじめに
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 REST API | User API |
| ログインユーザー情報の取得 garoon.base.user.getLoginUser() |
ユーザーの取得 /g/api/v1/base/users |
ユーザーエクスポート API /v1/users.json |
| レスポンス例 ※ ログインしているユーザー情報のみ取得可能 |
レスポンス例 |
レスポンス例 プロパティの詳細については、 User 型をご参照ください。 |
Garoon API にくらべて User API のほうが、取得できる内容が多いですね。
ユーザー情報の設定画面で設定できる詳細なユーザー情報（「従業員 ID」など）を取得したい場合は、User API を利用しましょう。
組織情報
| Garoon JavaScript API | Garoon REST API | User API |
| なし | 組織の取得 /g/api/v1/base/organizations |
組織エクスポート API /v1/organizations.json |
| - | レスポンス例 |
レスポンス例 プロパティの詳細については、Organization 型をご参照ください。 |
ユーザー情報と同様、User API のほうが、取得できる内容が若干多いです。
組織の設定画面で設定できる組織情報（「説明」や「別言語での表示名」など）を取得したい場合は、User API を利用しましょう。
Garoon カスタマイズで User API を利用するときの注意点
Garoon カスタマイズで User API を利用するとき、注意しなければならないことがあります。
それは、Garoon REST API で取得したユーザー情報の id と、User API で取得したユーザー情報の id は違う意味を持っているということです。
例
Garoon REST API の予定の取得 API で取得したスケジュール情報を例に説明します。
スケジュールが持つユーザー情報はいくつかありますが、そのうちのひとつ、参加者を表す attendees に注目してください。
attendees プロパティを見ると、参加者である「山田 太郎」さんの id は「508」で、code は「yamada-taro」です。
次に、「山田 太郎」さんのユーザー情報を User API を使って取得します。
レスポンス結果を見ると、「山田 太郎」さんの id は「520」になっていて、Garoon REST API で取得したときのユーザー情報の id と異なっています。
さらに、「山田 太郎」さんでログインしたときの、Garoon JavaScript ログインユーザー情報の取得 API で取得したユーザー情報は次のようになります。
レスポンス結果からプロパティ名を確認すると、Garoon REST API で取得したときの id 「508」は garoonId、User API を使って取得したときの id「520」は、id となっています。
解説
- Garoon REST API で取得したユーザー情報の id：Garoon ユーザーID
- User API で取得したユーザー情報の id：.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 のなかには、予定の一覧取得（クエリで条件を指定）のように、ユーザーで絞って検索するときにGaroon ユーザーID のみ指定可能な API もあります。
このときにユーザーの詳細情報も利用する場合には、API を呼ぶ順序が重要です。
まず、Garoon ユーザーIDを使って Garoon REST API を呼んで情報を取得したのち、取得した情報に含まれているログイン名を使って User API を呼ぶ必要があります。
おまけ：Garoon と kintone のユーザー情報を紐付ける
Garoon と kintone を連携するとき、ユーザー情報を紐付けるにはどのプロパティを使えばよいでしょうか？
さきほどの図に kintone の関係も加えてみましょう。
kintone JavaScript API のログインユーザー情報の取得 API のユーザー情報の id は、User API のユーザー情報の id と同じ、.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で確認したものになります。
記事に関するフィードバック
記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。