Guia de Uso para Ativos

A API de ativos do Open Cloud permite que você faça upload e atualize ativos com uma única solicitação HTTP, em vez de importá-los manualmente para o Studio. Essa API suporta:

• Carregando novos ativos.
• Atualizando ativos existentes com controle de versão.
• Atualizando metadados de ativos, incluindo descrições, nomes de exibição, ícones e visualizações.
• Gerenciar versões de ativos, como reverter para uma versão anterior especificada.
• Verificando informações existentes de um ativo, incluindo metadados, versões e quaisquer operações de atualização no processo.

Tipos de ativos suportados e limites

Para endpoints que não criam novos ativos ou atualizam o conteúdo de ativos existentes, não há restrições e limites. No entanto, a funcionalidade de upload de conteúdo de ativos alimentada pelos endpoints Criar Ativo e Atualizar Ativo suporta apenas tipos limitados de ativos com restrições. Por chamada, você só pode criar ou atualizar um ativo com o tamanho do arquivo até 20 MB com os seguintes limites:

Permissões de Segurança

A API suporta o uso de primeira parte com autorização de chave API e uso de terceiros em aplicativos OAuth 2. Cada caminho requer configurações de permissão de segurança diferentes.

Chaves de API

Para usar a API em seus próprios scripts ou ferramentas, você precisa Criar uma chave API para autorização e segurança. Para gerenciar ativos que você possui individualmente, crie a chave API em sua conta. Para gerenciar ativos de propriedade do grupo, crie a chave API no grupo de destino. Para mais informações sobre chaves API de propriedade do grupo, consulte Permissões de chave API de propriedade do grupo.

Depois de criar uma chave de API, você não pode trocar sua propriedade entre indivíduos ou grupos, portanto, se você criar uma chave de API em sua própria conta, você não poderá usá-la para gerenciar ativos de grupo.

Independentemente de você estar criando a chave de API para si mesmo ou para o seu grupo, certifique-se de adicionar as seguintes permissões:

1. Adicione API de ativos a Permissões de acesso .
2. Adicione Read e Write permissões de operação à sua experiência selecionada, dependendo dos escopos necessários dos endpoints que você planeja chamar.

Depois de ter a chave API, copie-a para o x-api-key cabeçalho de solicitação. Todos os endpoints requerem o x-api-key cabeçalho de solicitação.

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

Aplicações OAuth 2.0

Para usar a API para um aplicativo OAuth 2.0 de terceiros, adicione os asset:read e asset:write escopos de permissão quando registrar seu aplicativo. Escolha esses escopos com base nos requisitos dos endpoints que você planeja usar.

Criando um Novo Ativo

Para carregar um novo ativo por uma solicitar / pedirHTTP:

1. Copie a chave API para o cabeçalho de solicitação x-api-key do ponto de extremidade Create Asset.

2. Em sua solicitar / pedir:

   1. Especifique o alvo tipo de ativo .
   2. Adicione o nome e a descrição do seu item.
   3. Adicione as informações do criador.

      • Se você quiser criar o ativo em seu próprio nome , adicione seu ID de usuário. Você pode encontrar seu ID de usuário no URL do seu perfil do Roblox. Por exemplo, para .
      • Se você quiser criar o recurso como um recurso de grupo , adicione o ID do grupo do seu grupo. Você pode encontrar o ID do grupo no URL da página do seu grupo. Por exemplo, para https://www.roblox.com/groups/7654321/example-group#!/ , o ID do grupo é 7654321.
   4. Adicione o caminho do arquivo e o tipo de conteúdo do seu ativo.

   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}\" # Use o groupId para criar um ativo de grupo
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Atualizando um ativo existente

Para atualizar um ativo existente por uma solicitar / pedirHTTP:

1. Copie a chave API para o cabeçalho de solicitação x-api-key do ponto de extremidade Update Asset.
2. Adicione o tipo de ativo e o ID do ativo em sua solicitar / pedir. Para copiar seu ID de ativo:

   1. Navegue até a página Criação do Painel do Criador **** .
   2. Selecione a categoriade Itens de Desenvolvimento .
   3. Selecione a categoria do seu ativo e encontre o ativo de destino.
   4. Passe o mouse sobre a miniatura do ativo alvo e clique no botão **** para exibir uma lista de opções e, em seguida, selecione Copiar ID do ativo da lista.

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}"'

Recuperando o Status da Operação de Ativos

Se sua solicitação para criar um novo ativo ou atualizar um ativo existente for bem-sucedida, ela retornará um Operation ID no formato { "path": "operations/${operationId}" }. Você pode usá-lo para verificar o status e o resultado do seu upload com as seguintes etapas:

1. Copie a chave API para o x-api-key cabeçalho de solicitação do Get Operation método e envie a solicitar / pedir, como o seguinte exemplo de código:

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

2. Se sua solicitação for bem-sucedida, ela retornará um Operation Objeto, incluindo um response que representa as informações do ativo carregado ou um status explicando por que o upload do ativo falha, como mostrado na seguinte amostra de código:

   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. (Opcional) Verifique o ativo criado na sua conta do Roblox.

   1. Navegue até a página Inventário da sua conta Roblox.
   2. Selecione a Categoria do ativo que você deseja verificar / conferir.
   3. Encontre o ativo de destino e clique em sua miniatura para visualizá-lo.

Adicionando API de ativos aos aplicativos OAuth 2.0

Você pode criar aplicativos OAuth 2.0 suportando API de ativos para permitir que seus usuários carreguem e atualizem ativos no Roblox.

Para usar a API de ativos para seu aplicativo e solicitar permissões de seus usuários, realize as seguintes configurações:

1. Ao registrar seu aplicativo , em Permissões , selecione asset:read e asset:write scopes.

2. Ao implementar o fluxo de autorização , inclua asset:read e asset:write como parâmetros de escopo do URL de autorização que redireciona os usuários de volta ao seu aplicativo, como no exemplo a seguir:

   https://www.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. Ao enviar a solicitar / pedir, inclua o token de acesso no cabeçalho de autorização e os dados de formulário do conteúdo do ativo para criar ou atualizar no URI da solicitação. O exemplo a seguir mostra uma solicitação de exemplo para o upload de um novo ativo:

   Exemplo de Pedido
   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"'