ドキュメント

サポート

Cloud Code

Open Unity Dashboard

Cloud Code

スクリプトの構造

Understand the structure of a Cloud Code script and how the main function acts as the entry point.
読み終わるまでの所要時間 3 分最終更新 23日前
ランタイムのエントリーポイントとして機能する Cloud Code スクリプトのメイン関数は、CommonJS ラッパーの形式をとります。 以下のコードスニペットは、可能なかぎり最も単純なスクリプトを示します。 JavaScript 
module.exports = async ({ params, context, logger }) => {  // this script does nothing};
このスクリプトは実際には何も行いませんが、スクリプト関数のコンテキストオブジェクトと非同期の性質を示します。

コンテキストオブジェクト

コンテキストオブジェクトには、以下の有用なオブジェクトが含まれます。 
  • Params
    : これは、スクリプトが呼び出されるときに使用される入力パラメーターの名前と値のペアの配列です。     
  • Context
    : このオブジェクトは、スクリプト内で役立つ追加のコンテキストを提供します。     
    • projectId
      : 呼び出し元が認証されたプロジェクト ID。
    • playerId
      : 認証されたプレイヤー ID。
    • accessToken
      : 他の Unity ゲームサービス SDK を認証されたプレイヤーとして呼び出すために使用できる JWT。
    • environmentName
      : 現在使用されている Unity 環境 の名前。
    • environmentId
      : 現在使用されている Unity 環境の ID。
    • serviceToken
      : 他の Unity ゲームサービス SDK を認証された Cloud Code ユーザーとして呼び出すために使用される JWT。
    • unityInstallationId
      : クライアントのデバイス上のインストールを識別する一意の識別子。異なるデバイスにゲームをインストールしている場合は、同じプレイヤーが異なる 
      installationId
      を持つ可能性があります。Services SDK Core パッケージと統合されるすべての Unity パッケージで使用可能です。
    • analyticsUserId
      : プレイヤーを識別する一意の文字列で、分析を目的として後続のプレイセッションで一貫して使用されます。これはプライマリユーザー識別子であり、Core パッケージから取得されます。
    • correlationId
      : リクエストを関連付けるために使用される一意の識別子。
  • Logger
    : スクリプトが情報、警告、エラーをログに記録できるようにするオブジェクト。

JavaScript

module.exports = async ({logger}) => {  logger.info('This message confirms that the logging client is functional!');  logger.warning('This is a serious warning that the cheese is about to run out.');  logger.error('Out of cheese :(');}
詳細については、ロギング のドキュメントを参照してください。

トークン認証

accessToken
と 
serviceToken
は、
context
オブジェクトのプロパティとして提供される JWT です。 これらのトークンは、Cloud Code から他の Unity Gaming Services の呼び出しを認証します。

トークンタイプ

発生元

データアクセス

使用方法

accessToken
Authentication サービス によって生成されます認証されたプレイヤーに限定されます
accessToken
は、Cloud Code 呼び出しの認証に使用される JWT です。これを他の UGS サービスに渡して、認証されたプレイヤーのデータにアクセスできます
serviceToken
Cloud Code によって生成されますクロスプレイヤーデータアクセスを可能にします
serviceToken
は Cloud Code によって生成されるトークンであり、他の UGS サービスを呼び出し、クロスプレイヤーデータを操作するために使用できます。
設定した アクセス制御 ルールは 
accessToken
に影響します。 以下は、
accessToken
を使用して Economy SDK を呼び出し、プレイヤーのインベントリを取得する方法の例です。

JavaScript

// Player inventoryconst { InventoryApi } = require("@unity-services/economy-2.4");module.exports = async ({params, context, logger}) => { const { projectId, playerId, accessToken } = context; const inventory = new InventoryApi({accessToken}); const result = await inventory.getPlayerInventory({projectId, playerId}); return result.data;}
serviceToken
を使用する場合、同じスクリプトは以下のようになります。

JavaScript

// Player inventoryconst { InventoryApi } = require("@unity-services/economy-2.4");module.exports = async ({params, context, logger}) => {const { projectId, playerId } = context;const inventory = new InventoryApi(context);const result = await inventory.getPlayerInventory({projectId, playerId});return result.data;}
2 つのトークンの違いの詳細な説明は、サービスとアクセストークン を参照してください。

スクリプトパラメーター

スクリプトパラメーターは、スクリプト本文の外部または内部で定義できます。

スクリプト内パラメーター

スクリプト内パラメーターは、各パラメーター名をキーとして、型を値として含む 
params
オブジェクトをエクスポートすることで追加できます。 例を次に示します。

JavaScript

module.exports.params = { "echo" : "Boolean" }
または、パラメーターが必須であることを指定したい場合は、
type
と 
required
の両方のプロパティを含むオブジェクトを指定できます。

JavaScript

module.exports = async ({ params, context, logger }) => {    return {        "value": params["aParam"]    };};module.exports.params = { "aParam" : { "type": "String", "required": true } }
デフォルトでは、パラメーターは必須ではありません。 どちらの形式も希望に応じて組み合わせることができます。

JavaScript

module.exports = async ({ params, context, logger }) => {    var value = params["echo"] ? params["aParam"] : "default";    return {        "value": value    };};module.exports.params = {  "echo" : "Boolean",  "aParam" : { "type": "String", "required": true } }

async/await

メインスクリプト関数は、非同期関数にすることができます。これは、関数が await promise を実行できることを意味します。これにより、スクリプト内で他の Unity ゲームサービス SDK を使用できるようになります。promise について説明している Mozilla ドキュメントを確認してください。 簡単な例は以下のようになります。

JavaScript

// Player inventoryconst { InventoryApi } = require("@unity-services/economy-2.4");module.exports = async ({params, context, logger}) => { const { projectId, playerId } = context; const inventory = new InventoryApi(context); const result = await inventory.getPlayerInventory({projectId, playerId}); return result.data;}

その他のパッケージ

スクリプトは、
import
または 
require
キーワードを使用してローカルスクリプトまたは外部パッケージをインポートできます。 インポートできるものの完全なリストについては、利用可能なパッケージ を参照してください。

JavaScript

const _ = require("lodash-4.17");module.exports = async () => {  return _.random(1, 6);};

バンドル

スクリプトバンドルは、Unity エディター内で Deployment パッケージを使用して有効化される機能であり、ローカルでのスクリプトの管理、追加のワークフローのロック解除、複数のスクリプト間で共有する一般的な機能の有効化に役立ちます。バンドルされたスクリプトの生成方法について詳しくは、JS バンドル のドキュメントを参照してください。

JavaScript

const lib = require("./lib");module.exports = async () => {  return lib.helloWorld();};module.exports.bundled = true;

出力

スクリプトの出力は、以下の型から構成できます。

JavaScript

  • string
    module.exports = async () => {  return "hello world";};
  • boolean
    module.exports = async () => {  return true;};
  • number
    module.exports = async () => {  return 3.14;};
  • object
    module.exports = async () => {  return {    message: "hello world",    success: true  };};
正常なレスポンスは、API から以下の構造を持つ JSON として返されます。 
{  "output": <SCRIPT OUTPUT>}

エラー出力

エラーは、何かが呼び出しの失敗の原因となった場合に (例えば、失敗したサービスリクエスト)、スクリプトによってスローされることがあります。 スクリプト内でエラーを捕捉すると、失敗を処理する方法を決定できます。

JavaScript

module.exports = async ({logger}) => {  try {    let result = service.call("example");    return result;  } catch (err) {    logger.error("Something went wrong!", {"error.message": err.message});    throw err;  }};
エラーレスポンスは、エラータイプ、エラーメッセージ、およびエラーの原因を特定するのに役立つスタックトレースとともに、API から JSON として返されます。 
{  "type": "problems/invocation",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Invocation Error",  "instance": null,  "code": 9009,  "details": [      {          "name": "ReferenceError",          "message": "service is not defined",          "stackTrace": [              "at module.exports (example-test.js:1:26)"          ]      }  ]}