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】" }"

上記基本形のうち、【】で囲われたエリアは独自に値を指定します。

【エンドポイント】 #

ここではレポートの取得に関するエンドポイントのみ紹介します。以下のいづれかの値を指定します。必須です。

reports/admin

管理者のみ実行可能。全てのレポートを取得できるAPI

reports/outbox

自分が送信したレポートのデータのみ取得できるAPI

reports/inbox

自分が受信したレポートのデータのみ取得できるAPI

report/:レポートのID

IDを指定して1件のレポートを取得できるAPI

他のエンドポイントについては本ページ末尾で解説します。

【パラメータ】・【値】 #

レポート取得に感るうパラメータを紹介します。 パラメータをセットします。グループ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

この例を少し詳しく見てみます

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件のテンプレートを取得します

パラメータ:

# 記述例
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

ログデータを取得する

パラメータ:

# 記述例
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

スタッフ情報を取得する

# 記述例
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以下になるように指定します