REST API

REST API を使うと、自分のソフトウェアから Measure Map Online のアカウントの内容を読み取り、変更できます。対象は、プロジェクトとその計測値、フォルダ、製品カタログ、Enterprise では組織のメンバーです。応答は JSON で返されます。すべてのフィールドと例を含む完全なリファレンスは API ドキュメントにあり、このページはその概要です。

アプリからドキュメントを開くには、code開発者 > apiREST API に移動し、menu_bookドキュメンテーションを見る を押します。

ベース URL#

すべてのリクエストの送信先は次のとおりです。

https://api.measuremaponline.com/api/v2

認証#

すべてのリクエストの Authorization ヘッダーに、API キーをそのまま入れて送ります。キーは開発者ページで作成します。詳しくはAPI キーを参照してください。

curl https://api.measuremaponline.com/api/v2/projects/YOUR_PROJECT_ID \
  -H "Authorization: YOUR_API_KEY"

各リクエストは、キーのアクセス権（たとえば、プロジェクトの 読み取り）、サブスクリプション、そして Web ページから送られたリクエストの場合はキーのウェブサイトの制限に照らして確認されます。データを変更できるキーは、サーバーで保管してください。詳しくはキーを安全に保つを参照してください。

本番とサンドボックス#

ベース URL は両方で共通です。どちらになるかはキーで決まります。サンドボックスのキーは、本番のキーからは見えないサンドボックスのプロジェクト、フォルダ、製品を読み書きします。メンバーは両方で共通ですが、メンバーとしてサインインするには本番のキーが必要です。サンドボックスのキーで作成したゲストプロジェクトは課金されず、サンドボックスのプロジェクトはウェブサイトに埋め込めません。トークンは、自分が属する環境を示します。

API の対象#

知っておくべきことがいくつかあります。

• キーが扱えるのは、そのキーのアカウントのプロジェクトと、Enterprise では組織のメンバーのプロジェクトです。
• API でプロジェクトやフォルダを削除すると、完全に削除されます。ゴミ箱には入りません。フォルダを削除すると、その中にあるフォルダとプロジェクトのうち、自分のアカウントまたはメンバーのものも一緒に削除されます。
• プロジェクトの計測値では、図形の製品が productIds に順番どおりに並びます。productId はその最初の製品です。
• /projects/{pid}/mmp は、アプリがエクスポートするのと同じ .mmp ファイルを返します。そのスキーマは github.com/blueblinkone/mmp-validator で公開されています。新しい要素は常に任意の要素として追加されるため、古いファイル用に作られた読み込み処理も引き続き動作します。
• Open Guest では、API で Open Guest のアクセスレベルで作成したプロジェクトは、ゲストリンクから始まったプロジェクトと同じく、Open Guest の利用量と予算に数えられます。
• Open Guest では、person_pin_circleゲストリンク セクションに Open Guest API のガイドがあり、サーバーとページ用のコードが載っています。サーバーが本番のキーで POST /auth/token からトークンを取得し、訪問者を、その人の情報が入力済みの新しい専用プロジェクトに送ります。
• POST /users/new でメンバーを作成すると、招待と同じくシートを使い、組織の既定のロールが付与されます。
• POST /auth/{uid}/login のトークンではそのメンバーのアカウントが開くため、メンバーを変更できるキーが必要です。埋め込みに使うキーは決して使わないでください。管理者やマネージャーのメンバーについては発行されず、サンドボックスのキーでも発行されません。
• API で製品が削除されることはなく、アーカイブされるだけです。また、製品の原価が返されることはありません。
• 地籍区画は API の対象外です。

応答とエラー#

成功したリクエストには、ステータス 200 と JSON で応答します（.mmp のエクスポートは XML で応答します）。失敗したリクエストには、エラーのステータスと次のような本文で応答します。

{"errorCode": "insufficient_scope", "errorMessage": "This API key does not have the scope required for this endpoint"}

開発者ページから API を試す#

code開発者 > terminalAPI を試す では、キーを使って実際のリクエストを送り、返ってきた内容をそのまま表示します。

1. 本番 または サンドボックス を選びます。
2. 「すべてのプロジェクトを一覧」や「計測値を取得」などの エンドポイント を選びます。
3. パラメーターを入力します。プロジェクトや製品は、キーで読み取れるものの中から名前で選びます。人を指定するパラメーターには、自分のアカウントが入力されます。
4. play_arrowリクエスト送信 を押します。ステータスと応答が下に表示されます。

表示されるのは読み取りのリクエストだけなので、試しても何も変更されず、これらのリクエストは利用状況にも数えられません。キーにエンドポイントに必要なアクセス権がない場合は、403 が返されることが警告として表示されます。

Webhook#

Webhook は、通知メールが自分に知らせるのと同じように、何かが起きたことをサーバーに知らせます。Webhook は Enterprise プランと Open Guest プランの機能です。

Webhook を設定する#

code開発者 > webhookWebhook で次のようにします。

1. エンドポイント URL を入力します。インターネット上の https:// のアドレスである必要があります。プライベートネットワーク上のアドレスは拒否され、この確認は配信のたびに改めて行われます。
2. 受け取る イベント にチェックを入れます（イベントを参照）。新しいエンドポイントでは、プランが送るイベントにチェックが入った状態で始まります。少なくとも 1 つはチェックが必要です。
3. save保存 を押します。初回は、署名シークレット がすべて表示されます。そのときにコピーしてください。その後は末尾の数文字だけが表示されます。
4. sendテストイベントを送信 を押し、イベントを選びます。

テストでは、そのイベントのサンプルが、架空の値と data 内の "test": true 付きで、保存したエンドポイントに送られます。そのイベントにチェックが入っていない場合や、エンドポイントがオフになっている場合でも送られます。すべての配信を止めるには、delete_outline削除 を押します。エンドポイントとそのシークレットが削除されます。

設定の下にある Webhook リファレンス には、受信側を作るのに必要なものがそろっています。ヘッダーと本文、Node.js、Python、PHP で署名を確認するコード、すべてのイベントのデータの例です。

サーバーが受け取るもの#

各イベントは、エンドポイントへの 1 回の POST で、本文は JSON です。

{"id": "evt_3f9a1c2b7d4e5f60718293a4", "type": "project.created", "created": 1790000000000, "data": { ... }}

id はイベントごとに一意で、created はイベントが起きた時刻（1970 年 1 月 1 日（UTC）からのミリ秒）です。data の内容はイベントによって異なります。リクエストには、次のヘッダーも含まれます。

• 時間のかかる処理をする前に、8 秒以内に 2xx のステータスで応答してください。それ以外のステータス、リダイレクト、タイムアウトは失敗として扱われます。
• 各イベントは 1 回だけ送られ、再送はされません。このセクションには、最後の配信 と 連続失敗回数 が表示されます。
• 10 回連続で失敗すると、エンドポイントはオフになり、オーナーにメールが届きます。サーバーを修正し、save保存 を押して再びオンにしてください。
• まれに、同じイベントが 2 回届いたり、順序が入れ替わって届いたりします。id で重複を無視し、created でイベントを並べ替えてください。

署名を確認する#

アドレスを知っている人なら誰でもそこに送信できるため、配信を信頼する前に毎回確認してください。

1. X-MMO-Signature ヘッダーをカンマで分けて、t と v1 を取り出します。
2. t、ピリオド、受け取ったままのリクエスト本文をつないだものについて、署名シークレットをキーとして HMAC-SHA256 を計算し、16 進数で表します。
3. その結果を、一定時間で比較する方法で v1 と比較します。
4. t が現在時刻から 5 分以上ずれている場合は、その配信を拒否します。t の単位はミリ秒です。

本文は届いたままの形で使ってください。JSON を解析して書き出し直すと本文が変わり、署名が一致しなくなります。

autorenewシークレットを再生成 を押すと、シークレットがすぐに置き換えられ、新しいシークレットが 1 回だけすべて表示されます。ローテーションしたら、すぐにサーバーを更新してください。

イベント#