外部通信

外部通信は、cluster外に用意したサーバーと空間インスタンス内からデータをやりとりする機能です。 ItemScriptで使うことができます。

サーバーは基本的にクリエイター自身もしくは信頼している第三者が管理している必要があります。 クリエイターが作成したワールドやアイテムは、クリエイターが登録したサーバーと通信します。 クラフトアイテムから外部通信を行った場合、クラフトアイテムの作者のサーバーにアクセスします。

プレイヤーのプライバシー

外部通信は空間インスタンス内のデータを外部と送受信できる強力な機能です。 プレイヤーのプライバシーを保護するため、外部通信はclusterのサーバーを経由して行われます。

プレイヤーの個人情報に該当する情報を送信する場合、プレイヤーの同意が必要です。

サーバーの準備

外部通信サーバーはHTTP/HTTPS POSTを受け付けるエンドポイントを提供する必要があります。

外部通信APIの呼び出しのたびに、エンドポイントに対してHTTP/HTTPS POSTが一回行われます。 POSTに対するresponseに含まれるデータがonExternalCallEndに渡されます。 エンドポイントが5秒のタイムアウトを超えても応答しない場合、またエラーを返した場合、失敗と判定されます。clusterからエンドポイントに対するリトライは行いません。

リクエスト

{
  "request": "...100kB以下の文字列..."
}

レスポンス

{
  "verify": "...verify_token...",
  "response": "...100kB以下の文字列..."
}

Verify Token

verifyにはVerify Tokenを文字列で指定する必要があります。 Verify Tokenは、 サーバーが自身の管理下にあることを、clusterが確認するために利用します。 Verify TokenはCreatorKitの「Cluster > 外部通信(callExternal)接続先URL」を選択して表示されるウィンドウから作成できます。

Verify Tokenは作成のたびに一度しか表示されないためコピーして別の場所に保存するようにしてください。

Verify Tokenはアカウントごとに最大2個登録できます。 新しいVerify Tokenを作成し、サーバーが利用するVerify Tokenを更新してから古いVerify Tokenを削除することで、Verify Tokenを更新できます。

Endpoint登録

Creator Kitの「Cluster > 外部通信(callExternal)接続先URL」を選択して表示されるウィンドウから外部通信サーバーのURLを登録できます。

URLを登録するとウィンドウにEndpoint IDが表示されます。 ClusterScriptでEndpoint IDを元にExternalEndpointIdオブジェクトを作成した上でcallExternalAPIに渡すことで通信先のサーバーを指定できます。

Endpointはアカウントごとに最大100個登録できます。

callExternal APIの利用

外部通信を行うには以下のAPIを利用します。

• ClusterScript.callExternal
• ClusterScript.onExternalCallEnd
• ExternalEndpointId