APIを使いレポートやテンプレートを取得する
APIの利用には少し技術者の知識が必要です。
- CURL
- JSON
このあたりの基本が理解できれば問題有りません。本ガイドはCURLを使用しています。コマンドが苦手な方はPostmanなどのGUIツールをご利用ください。
APIへリクエストを投げる基本の形をレポート取得の例から見る
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/【エンドポイント】 \
-H "Content-Type:application/json;charset=UTF-8" \
-H "Authorization: Bearer 【取得したAPIキー（200文字程度)】" \
-d "{ "【パラメータ1】": "【値1】", "【パラメータ2】": "【値2】" }"注意
Mac/Linux向けのCurl記法です。Windows版は若干形式が変わる可能性があるので注意
【】で囲まれた部分には、独自の値を指定してください。
【エンドポイント】
ここではレポートの取得に関するエンドポイントのみ紹介します。以下のいづれかの値を指定します。必須です。
- reports/admin
- 管理者のみ実行可能。全てのレポートを取得できるAPI
- reports/outbox
- 自分が送信したレポートのデータのみ取得できるAPI
- reports/inbox
- 自分が受信したレポートのデータのみ取得できるAPI
- report/:レポートのID
- IDを指定して1件のレポートを取得できるAPI
他のエンドポイントについては本ページ末尾で解説します。
【パラメータ】・【値】
レポート取得に感るうパラメータを紹介します。 パラメータをセットします。グループIDは必須です。必要に応じて複数パラメータを指定できます。
| 属性名 | 型 | 説明 |
|---|---|---|
| groupId | String(必須) | 取得するグループのID |
| size | Number | 取得するレポートの件数。1〜1000の間で指定します。未指定の場合は10が自動で適用されます |
| from | String | 期間（開始) 2022/08/01 00:00:00のような形で指定。必ずtoとセットで使用 |
| to | String | 期間（終了) 2022/09/31 23:59:59のような形で指定。必ずfromとセットで使用 |
| tags | String配列 | タグのIDを配列で指定 |
| states | String配列 | レポートの状態で絞り込み。[“承認”, “棄却”, “修正”, “新規”, “進行”]のように指定 |
| templates | String配列 | 使用したテンプレートのIDで絞り込み。テンプレートIDの配列で指定 |
| owners | String配列 | レポート作成者IDで絞り込み。スタッフのIDを配列で指定 |
【取得したAPIキー】
取得したAPIキーをCurlに含めてください。長いので必ずコピーペーストして使用してください。 APIキーの取得が済んでいないかたは先にAPIキーの取得を行ってください。
本ガイドではこれ以降も実際のAPIキーは使用せず解説します。
エンドポイントとパラメータを指定した最小限のCurl
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/reports/admin \
-H "Content-Type:application/json;charset=UTF-8" \
-H "Authorization: Bearer 【取得したAPIキー】" \
-d "{"groupId": "nipodefaultgroup" }"このコマンドはレポートを取得する命令を送っています。パラメータに期間の指定が無いため、直近10件のレポートがAPI経由で取得できます。
パラメータを色々指定した実用性のあるCurl
設定可能なパラメータを追加した例です。
# パラメータが多いためヒアドキュメントを使っています
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/reports/admin \
-H "Content-Type:application/json;charset=UTF-8" \
-H "Authorization: Bearer 【取得したAPIキー】" \
-d @- <<EOS
{
"groupId": "nipodefaultgroup",
"size": 1000,
"from": "2022/08/01 00:00:00",
"to": "2022/09/30 23:59:59",
"tags": ["oSGoygpZYCBlldTWGewA", "bo6wwrUSVrE6UbqlJjkf"]
"states": ["新規", "進行", "棄却"],
"templates": ["iELPWHa3ZjXYJS62Hn3N"],
"owners": ["mMSejOQa21d9OtXo1BtjFzrEt6J3"]
}
EOS注意
見やすさを重視してヒアドキュメント（EOSの箇所）を使っています。
この例を少し詳しく見てみます
- groupId
- グループIDを指定します。グループIDはグループ全般やURLから確認できます。
- size
- レポートを1000件リクエストしています
- from・to
- 検索期間を2022年8月1日〜2022年9月30日に指定しています
- tags
- タグによるフィルタを使う場合に指定します。タグ名ではなくタグのIDで指定します。タグのIDはタグ管理から確認できます
- states
- レポートの状態によるフィルタを使う場合に指定します。この例では新規、進行、棄却のレポートのみを取得します（承認や修正のレポートは除外）
- templates
- テンプレートによるフィルタを使う場合に指定します。テンプレートIDを指定します。複数件指定できるため配列です
- owners
- レポートを書いたスタッフによるフィルタを使う場合に指定します。スタッフIDを指定します
補足：URLからグループIDを確認する際はURLの意味を見てください。
https://nipoplus.sndbox.jp/#/room/組織ID/グループID/__/path/to/any...例えばURLが次のようなデータだった場合
https://nipoplus.sndbox.jp/#/room/BLyx3SG72rId24BnKcGC/eZu8bXFNh73YtVoR83ic/teal/home/PageNameGroupSettingAboutグループIDは「eZu8bXFNh73YtVoR83ic」となります。
その他のエンドポイント
レポートの取得以外に用意されているエンドポイントとパラメータについてまとめています。
テンプレートの取得エンドポイント
- /templtes
- パラメータで指定したグループ内の全てのテンプレートを取得します
- /template/:テンプレートのID
- IDで指定された1件のテンプレートを取得します
パラメータ:
| 名称 | 型 | 説明 | 必須 |
|---|---|---|---|
| groupId | String | 取得するグループのID | ○ |
# 記述例
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/templates \
-H "Content-Type:application/json" \
-H "Authorization: Bearer 【取得したAPIキー】" \
-d "{ "groupId": "nipodefaultgroup" }"ログデータ取得エンドポイント
- /logs
- ログデータを取得する
パラメータ:
| 名称 | 型 | 説明 | 必須 |
|---|---|---|---|
| groupId | String | 取得するグループのID | ○ |
| size | Number | 取得するレポートの件数。1〜1000の間で指定 | ○ |
| from | String | 取得するレポートの期間（開始点) 2022/08/01 00:00:00のような形で指定 | ○ |
| to | string | 取得するレポートの期間（終了点) 2022/09/31 23:59:59のような形で指定 | ○ |
# 記述例
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/logs \
-H "Content-Type:application/json" \
-H "Authorization: Bearer 【取得したAPIキー】" \
-d "{"groupId": "nipodefaultgroup", "size": 1000, "from": "2022/08/01 10:00:00", "to": "2022/08/01 10:59:59"}"スタッフ取得エンドポイント
- /staffs
- スタッフ情報を取得する
| 名称 | 型 | 説明 | 必須 |
|---|---|---|---|
| groupId | String | 取得するグループのID | ○ |
# 記述例
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/staffs \
-H "Content-Type:application/json" \
-H "Authorization: Bearer 【取得したAPIキー】" \
-d "{ "groupId": "nipodefaultgroup" }"組織全体のエンドポイント
組織全体に関する情報のためアクセスには管理者権限が必要です。
- /staffs/admin
- 組織に所属している全スタッフのデータを取得します
- /group/admin
- 組織内に作成された全てのグループを取得します
パラメータはありません。
# 記述例
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/staffs/admin \
-H "Content-Type:application/json" \
-H "Authorization: Bearer 【取得したAPIキー】" \エラーの種類と対策
WebAPIにリクエストを投げたとき、戻り値に{ error: true }がかえってきたときは何かしらのエラーが発生しています。 エラーの内容が messageプロパティにセットされていますので、メッセージを確認の上正しいパラメータを設定してください。
以下は代表的なエラーの例です
- トークンの更新に失敗
- Bearerトークンが失効しています.APIキーの管理から再度取得してください
- グループIDが不正です
- パラメータ groupIdに誤りがあります。groupIdを見直してください
- このグループに対する権限がありません
- 指定したgroupIdに所属していないと権限不足が発生します。グループに所属してください
- 権限が足りません
- エンドポイントの中にadminが含まれるものは管理者権限のBearerトークンでアクセスする必要があります
- 日付不正
- パラメータ from / toの指定が誤っています。必ず yyyy/MM/dd hh:mm:ss の形式で指定する必要があります
- データベースアクセスエラー
- 何らかの原因でデータベースへの問い合わせに失敗しました。少し時間を追いてリトライしてください
- 文法に誤りがあります
- 正しい文法に修正してください。json最後の , を消し忘れるなど初歩的なミスである場合が多いです
- Expected X, received Y
- パラメータが間違っています。Xの型を要求しているのにY型を渡されたという意味です。正しい型を指定してください
- Number must be less than or equal to X
- 指定された数値が大きすぎます。X以下になるように指定します