カテゴリー内の他の記事

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

フォローする

Index

はじめに

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 と User API で取得したユーザー情報の 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で確認したものになります。

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

ログインしてコメントを残してください。