アセットの使用ガイド

Open CloudのAssets APIを使用すると、Studioに手動でインポートするのではなく、単一のHTTPリクエストでアセットをアップロードおよび更新できます。このAPIは以下をサポートしています：

• 新しいアセットのアップロード。
• バージョン管理を用いた既存アセットの更新。
• 説明、表示名、アイコン、プレビューを含むアセットメタデータの更新。
• 特定の以前のバージョンにロールバックするなどのアセットのバージョン管理。
• メタデータ、バージョン、進行中の更新操作を含む、アセットの既存情報の確認。

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

新しいアセットを作成したり、既存のアセットの内容を更新しないエンドポイントには、制限や制約はありません。ただし、Create AssetおよびUpdate Assetエンドポイントによって駆動されるアセットコンテンツのアップロード機能は、制限のある限られたタイプのアセットのみをサポートしています。各呼び出しで、ファイルサイズが20MBまでの1つのアセットを作成または更新することができます。次の制限があります：

セキュリティ権限

このAPIは、APIキー認証を用いたファーストパーティの使用と、OAuth 2アプリケーションでのサードパーティの使用の両方をサポートしています。それぞれ異なるセキュリティ権限設定が必要です。

APIキー

スクリプトやツール内でAPIを使用するには、認証とセキュリティのためにAPIキーを作成する必要があります。

APIキーを作成する際には、次の権限を追加してください：

1. アクセス権限にassetsを追加します。
2. 呼び出そうとしているエンドポイントの必要なスコープに応じて、選択したゲームに読み取りおよび書き込み操作権限を追加します。

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

APIリクエストヘッダーの例
--header 'x-api-key: ${ApiKey}' \

OAuth 2.0アプリ

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

新しいアセットを作成

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

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

2. リクエスト内で：

   1. 対象のアセットタイプを指定します。
   2. アセットの名前と説明を追加します。
   3. 作成者情報を追加します。

      • 自分の名義でアセットを作成したい場合は、自分のユーザーIDを追加します。ユーザーIDは、RobloxプロファイルのURLにあります。例えば、https://www.roblox.com/users/1234567/profile,の場合、ユーザーIDは1234567`です。
      • グループアセットとしてアセットを作成したい場合は、グループのグループIDを追加します。グループIDは、グループページのURLにあります。例えば、https://www.roblox.com/groups/7654321/example-group#!/,の場合、グループIDは7654321`です。
   4. アセットのファイルパスとコンテンツタイプを追加します。

   アセット作成リクエストの例
   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. Update Assetエンドポイントのx-api-keyリクエストヘッダーにAPIキーをコピーします。
2. リクエスト内にアセットタイプとアセットIDを追加します。アセットIDをコピーするには：

   1. クリエイターダッシュボードの作成ページに移動します。
   2. 開発アイテムカテゴリーを選択します。
   3. アセットのカテゴリーを選択し、対象アセットを見つけます。
   4. 対象アセットのサムネイルにカーソルを合わせ、オプションのリストを表示するために**＆ctdot;ボタンをクリックし、リストからアセットIDをコピー**を選択します。

アセットコンテンツ更新リクエストの例
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}"'

アセット操作状況を取得

新しいアセットを作成するリクエストまたは既存のアセットを更新するリクエストが成功すると、Operation IDが{ "path": "operations/${operationId}" }の形式で返されます。これを使用して、次の手順でアップロードの状態と結果を確認できます：

1. Get Operationメソッドのx-api-keyリクエストヘッダーにAPIキーをコピーし、リクエストを送信します。以下のコードサンプルのように：

   操作取得リクエストの例
   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. リクエストが成功すると、Operationオブジェクトが返され、アップロードされた資産情報を表すresponseを含むか、アップロードが失敗した理由を説明するstatusを含みます。以下のコードサンプルのように：

   操作取得に対する例の応答
   {
     "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. Robloxアカウントのインベントリページに移動します。
   2. 確認したいアセットのカテゴリーを選択します。
   3. 対象アセットを見つけ、そのサムネイルをクリックしてアセットを表示します。

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

アセットAPIをサポートするOAuth 2.0アプリケーションを作成し、ユーザーがアセットをRobloxにアップロードおよび更新できるようにすることができます。

アプリケーション用にアセットAPIを使用し、ユーザーから権限をリクエストするには、次の設定を行ってください：

1. アプリケーション登録時に、権限の下でasset:readおよびasset:writeスコープを選択します。

2. 認証フローを実装する際に、ユーザーをアプリケーションにリダイレクトする認証URLのスコープパラメータにasset:readおよびasset:writeを含めます。以下の例のように：

   https://apis.roblox.com/oauth/v1/authorize?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"'