アセットの使用ガイド

オープンクラウドの アセットAPI では、スタジオに手動でインポートするのではなく、1つの HTTP リクエストでアセットをアップロードして更新できます。この API は次をサポートします:

• 新しいアセットをアップロード中。
• バージョン管理で既存のアセットを更新する。
• 説明、ディスプレイ名、アイコン、プレビューを含むアセットメタデートを更新する
• 特定の前のバージョンに戻すなどのアセットバージョンを管理する。
• メタデータ、バージョン、および進行中の更新操作を含むアセットの既存情報をチェックしています。

サポートされるアセットタイプと制限

新しいアセットを作成したり、既存のアセットのコンテンツを更新しないエンドポイントには、制限や制限はありません。ただし、 アセットを作成する および アセットを更新する エンドポイントによって提供されるアセットコンテンツアップロード機能は、制限付きのアセットタイプのみをサポートします。各呼び出しでは、ファイルサイズが最大 20MB までの 1つのアセットのみを作成または更新でき、以下の制限があります：

セキュリティ許可

API は、API キー認証 と OAuth 2 アプリケーション でのサードパーティの使用を両方サポートします。それぞれの方向には、異なるセキュリティ許可設定が必要です。

API キー

自分のスクリプトまたはツールで API を使用するには、認証とセキュリティのために API キーを作成 する必要があります。個別に所有するアセットを管理するには、アカウントの下で API キーを作成します。グループ所有のアセットを管理するには、ターゲットグループの下で API キーを作成します。グループ所有の API キーに関する詳細情報は、グループ所有の API キーの権限 を参照してください。

API キーを作成すると、個人またはグループ間で所有権を切り替えることはできませんので、自分のアカウントで API キーを作成しても、グループアセットの管理に使用できません。

自分自身またはグループのために API キーを作成しているかどうかにかかわらず、次の権限を追加してください：

1. アセット を アクセス権 に追加。
2. 呼び出す予定のエンドポイントの必要なスコープに応じて、 読み取る および 書き込む 操作許可を選択したエクスペリエンスに追加します。

API キーを入手したら、x-api-key リクエストヘッダーにコピーします。すべてのエンドポイントには x-api-key リクエストヘッダーが必要です。

Example API Request Header
--header 'x-api-key: ${ApiKey}' \

OAuth 2.0 アプリ

サードパーティの OAuth 2.0 アプリケーションで API を使用するには、asset:read および asset:write 認可スコープを追加して、アプリを登録する 。使用する予定のエンドポイントの要件に基づいて、これらのスコープを選択します。

新しいアセットを作成

HTTP リクエストで新しいアセットをアップロードするには：

1. API キーを x-api-key クリエイトアセットエンドポイントの リクエストヘッダーにコピーします。

2. リクエストで：

   1. ターゲットの アセットタイプ を指定します。
   2. アセット名と説詳細を追加します。
   3. クリエーター情報を追加。

      • アセットを 自分の代理 で作成したい場合は、ユーザーIDを追加してください。Roblox プロフィールの URL でユーザー ID を見つけることができます。たとえば、https://www.roblox.com/users/1234567/profile の場合、ユーザーIDは1234567です。
      • アセット をグループアセットとして作成したい場合は、グループのグループ IDを追加します 。グループのページの URL でグループ ID を見つけることができます。たとえば、https://www.roblox.com/groups/7654321/example-group#!/ の場合、グループ ID は 7654321 です。
   4. アセットのファイルパスとコンテンツタイプを追加します。

   Example Request for Create Asset
   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Name\",
     \"description\": \"This is a description\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # グループアセットを作成するために groupId を使用
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

既存のアセットを更新する

HTTP リクエストで既存のアセットを更新するには：

1. API キーを x-api-key アップデートアセットエンドポイントの リクエストヘッダーにコピーします。
2. リクエストにアセットタイプとアセット ID を追加します。アセット ID をコピーするには：

   1. ナビゲート to the 作成 ページ of the クリエイターダッシュボード .
   2. Select the 開発アイテム categorカテゴリ.
   3. アセットのカテゴリを選択し、ターゲットのアセットを見つけます。
   4. ターゲットアセットのサムネイルにカーソルを置き、 ⋯ ボタンをクリックしてオプションのリストを表示し、リストから アセットIDをコピーする を選択します。

Example Request for Updating Asset Content
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \
--header 'x-api-key: {apiKey}' \
--form 'request={
    \"assetType\": \"{assetType}\",
    \"assetId\": \"{assetId}\",
    \"creationContext\": {
        \"creator\": {
            \"userId\": {userId}
        },
        \"expectedPrice\":{expectedPrice}
    },
}' \
--form 'fileContent=@"{file-path}"'

アセット操作ステータスを取得す状況

新しいアセットを作成するか、既存のアセットを更新するリクエストが成功すると、 操作ID を { "path": "operations/${operationId}" } の形式で返します。次の手順でアップロードのステータスと結果をチェックできます:

1. API キーを x-api-key 操作方法の Get Operation ヘッダーにコピーし、次のコードサンプルのようにリクエストを送信します：

   Example Request for Get Operation
   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. リクエストが成功すると、アップロードされたアセット情報を表す Operation オブジェクトまたは、アセットアップロードが失敗する理由を説明する response オブジェクトを返します。次のコードサンプルで示されるように、アセットアップロードが失敗する理由を説明する status オブジェクトも返します：

   Example Response for Get Operation
   {
     "path": "operations/{operationId}",
     "done": true,
     "response": {
       "@type": "type.googleapis.com/roblox.open_cloud.assets.v1.Asset",
       "path": "assets/2205400862",
       "revisionId": "1",
       "revisionCreateTime": "2023-03-02T22:27:04.062164400Z",
       "assetId": "2205400862",
       "displayName": "Name",
       "description": "This is a description",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (オプション) Roblox アカウントの作成されたアセットをチェックします。

   1. ナビゲート to the インベントリ ページ of your Roblox アカウント .
   2. チェックしたいアセットの カテゴリ を選択します。
   3. ターゲットのアセットを見つけて、アセットのサムネイルをクリックして表示します。

アセット API を OAuth 2.0 アプリに追加

アセット API をサポートする OAuth 2.0 アプリケーション を作成して、ユーザーが RRoblox（ロブロックス）blox にアセットをアップロードして更新できるようにすることができます。

アプリケーションでアセット API を使用し、ユーザーから許可をリクエストするには、次の設定を行います：

1. アプリケーションを登録するとき、 権限 の下で、 アセット:読み取り と アセット:書き込み スコープを選択します。

2. 認可フローを実装するとき、asset:read と asset:write を含め、ユーザーをアプリケーションに戻す認可 URLのスコープパラメータとして、次の例のようにユーザーをアプリケーションにリダイレクトする認可 URLを含めます：

   https://authorize.roblox.com?client_id=819547628404595165403873012&redirect_uri=https://my-app.com/redirect&scope=asset:read+asset:write&response_type=Code&prompts=login+consent&nonce=12345&state=6789

3. リクエストを送信するときは、アクセストークンを認可ヘッダに含め、アセットコンテンツのフォームデータをリクエスト URI に作成または更新するために含めます。次の例では、新しいアセットをアップロードするサンプルリクエストを示します：

   例のリクエスト
   curl --location --request POST 'https://apis.roblox.com/assets/v1/assets' \
   
   --header 'Authorization: Bearer <access_token>' \
   
   --header 'Content-Type: application/json' \
   
   --form 'request="{
   
     \"assetType\": \"Decal\",
   
     \"displayName\": \"DecalDemo123\",
   
     \"description\": \"This is a description\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'