REST API
認証
REST APIにはhttps経由でのみアクセスできます。REST APIにアクセスするには、アクセストークンを使用する必要があります。アクセストークンは、アカウントページに移動して生成できます。
APIトークンのセクションで、トークンを生成するをクリックします。
トークンに名前を付け、新しいトークンを作成するボタンをクリックします。新しいアクセストークンが表示されます。
このウィンドウを閉じると、トークンを見ることはできなくなるので、必ず控えてください。このトークンは秘密に保つ必要があるため、チーム以外の第三者に共有しないでください（たとえば、フォーラムに投稿しないでください）。
また、アカウントページから、生成したトークンをすべて取り消すことも、特定のトークンの名前を編集することもできます。
APIを呼び出すときは、HTTPリクエストの 'Authorization' ヘッダに次の値を設定する必要があります。
Bearer [access_token]
[access_token]をaccountページで生成したアクセストークンに置き換えてください。
たとえば:
curl -H "Authorization: Bearer nesgdxhiqe7hylfilr6ss1rds0gq1uj8" https://playcanvas.com/api/...
パラメーター
さまざまなルートは、いくつかのパラメータを受け入れます。GETリクエストの場合、パラメータがURLの一部でない場合、HTTPクエリ文字列パラメータとして渡すことができます。POST、PUT、DELETEリクエストに含まれない場合は、Content-Typeが 'application/json' のJSONとしてエンコードする必要があります。
各エンドポイントで使用される共通のパラメータがいくつかあります:
project_id
プロジェクト概要ページのURLから見つけることができます。
scenes
エディタでシーンを開く場合、シーンIDはURLにあります。
branch_id
これはバージョン管理パネルで見つかり、選択してコピーできます。
レスポンスフォーマット
私たちのREST APIは、各API呼び出しの応答形式について、一般的なガイドラインに従っています。
単一リソースの取得
単一のリソースを取得しようとしている場合、応答はあなたが要求したリソースを持つJSONオブジェクトになります。
複数のリソースを取得
たとえば、プロジェクトのアプリをリストアップするような複数のリソースを取得しようとしている場合は、次の形式のJSONオブジェクトを取得します。
{
"result": [
resource_1,
resource_2,
...,
resource_N
],
"pagination": {
"limit": number,
"skip": number,
"total": number
}
}
レスポンスにはページネーションデータも含まれています。レスポンスのページネーションを制御するには、次のURLパラメータを渡すことができます。
応答に含めるアイテムの最大数。
元の結果セットからスキップする項目の数
結果セットをソートするために使用するフィールドの名前。
昇順で結果を取得したい場合は1を渡し、降順にするには-1を渡します。
たとえば、最初の16件のアイテムをスキップして、32件のアイテムを取得するには、次のリクエストを送信します。
https://playcanvas.com/api/items?limit=32&skip=16
エラー
エラーが発生した場合は、次の形式のJSONオブジェクトが表示されます。
{
"error": "エラーメッセージです。"
}
また、レスポンスのステータスコードも適切なHTTPエラーコードになります。
レート制限
REST APIへの呼び出しにはレート制限があります。リクエストに応じてさまざまなレート制限があります。
- 通常: 通常のレート制限では、1分あたり120リクエストが許可されます。
- strict: strictのレート制限では、1分あたり5リクエストが許可されます。
APIの呼び出し回数を調整するために、次のヘッダがレスポンスに含まれます。
The number of requests allowed in a minute.
The remaining number of requests that you are allowed to make this minute.
The time at which the current rate limit window resets in UTC epoch seconds.
レート制限を超過すると、 429 Too Many Requestsステータスコードを受け取ります。制限が解除されるまで、新しいリクエストを続けることはできません。