Guia de uso para ativos

A API de Ativos da 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. Esta API suporta:

• Upload de novos ativos.
• Atualização de ativos existentes com controle de versão.
• Atualização de metadados de ativos, incluindo descrições, nomes de exibição, ícones e pré-visualizações.
• Gerenciamento de versões de ativos, como reverter para uma versão anterior específica.
• Verificação de informações existentes de um ativo, incluindo metadados, versões e quaisquer operações de atualização em andamento.

Tipos de ativos suportados e limites

Para endpoints que não criam um novo ativo 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. Para cada chamada, você só pode criar ou atualizar um ativo com o tamanho do arquivo de até 20 MB, com os seguintes limites:

Permissões de segurança

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

Chaves de API

Para usar a API em seus próprios scripts ou ferramentas, você precisa criar uma chave de API para autorização e segurança.

Ao criar uma chave de API, certifique-se de adicionar as seguintes permissões:

1. Adicione ativos às Permissões de Acesso.
2. Adicione permissões de operação Ler e Escrever ao seu jogo selecionado, dependendo dos escopos necessários dos endpoints que você planeja chamar.

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

Exemplo de Cabeçalho de Solicitação da API
--header 'x-api-key: ${ApiKey}' \

Aplicativos OAuth 2.0

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

Criar um novo ativo

Para fazer upload de um novo ativo por meio de uma solicitação HTTP:

1. Copie a chave de API para o cabeçalho de solicitação x-api-key do endpoint Criar Ativo.

2. Em sua solicitação:

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

      • Se você deseja criar o ativo em seu próprio nome, adicione seu ID de usuário. Você pode encontrar seu ID de usuário na URL do seu perfil Roblox. Por exemplo, para https://www.roblox.com/users/1234567/profile, seu ID de usuário é 1234567.
      • Se você deseja criar o ativo como um ativo de grupo, adicione o ID do grupo do seu grupo. Você pode encontrar o ID do grupo na 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.

   Exemplo de Solicitação para Criar Ativo
   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Nome\",
     \"description\": \"Esta é uma descrição\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Use groupId para criar um ativo de grupo
       }
     }
   }"' \
   --form 'fileContent=@"/caminho/do/arquivo/model.fbx";type=model/fbx'

Atualizar um ativo existente

Para atualizar um ativo existente por meio de uma solicitação HTTP:

1. Copie a chave de API para o cabeçalho de solicitação x-api-key do endpoint Atualizar Ativo.
2. Adicione o tipo de ativo e o ID do ativo em sua solicitação. Para copiar seu ID de ativo:

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

Exemplo de Solicitação para Atualização do Conteúdo do Ativo
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}"'

Recuperar status da operação de ativo

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

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

   Exemplo de Solicitação para Obter Operação
   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 objeto Operation, incluindo um response representando as informações do ativo carregado ou um status explicando por que o upload do ativo falhou, como o seguinte exemplo de código mostra:

   Exemplo de Resposta para Obter Operação
   {
     "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": "Nome",
       "description": "Esta é uma descrição",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (Opcional) Verifique o ativo criado na sua conta Roblox.

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

Adicionar a API de ativos aos aplicativos OAuth 2.0

Você pode criar aplicações OAuth 2.0 que suportam a API de Ativos para permitir que seus usuários façam upload e atualizem ativos para Roblox.

Para usar a API de Ativos para sua aplicação e solicitar permissões dos seus usuários, execute as seguintes configurações:

1. Ao registrar seu aplicativo, na seção Permissões, selecione os escopos asset:read e asset:write.

2. Ao implementar o fluxo de autorização, inclua asset:read e asset:write como parâmetros de escopo da URL de autorização que redireciona os usuários de volta para sua aplicação, como no seguinte exemplo:

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

   Exemplo de Solicitação
   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\": \"Esta é uma descrição\", 
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
   
     }
   
   }"' \
   
   --form 'fileContent=@"/caminho/do/arquivo/p1.png"'