Guia de uso para recursos

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

• Carregando novos recursos.
• Atualizando recursos existentes com controle de versão.
• Atualizando metadados de recursos, incluindo descrições, nomes de exibição, ícones e previews.
• Gerenciar versões de recursos, como voltar a uma versão anterior especificada.
• Verificando informações existentes de um ativo, incluindo metadados, versões e quaisquer operações de atualização em andamento.

Tipos de recurso e limites suportados

Para pontos finais que não criam um novo recurso ou atualizam o conteúdo de recursos existentes, não há restrições ou limites.No entanto, a funcionalidade de carregamento de conteúdo de recursos alimentada pelos endpoints Criar Recurso e Atualizar Recurso apenas suporta tipos limitados de recursos com restrições.Para cada chamada, você só pode criar ou atualizar um recurso 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 da API e o uso de terceiros em aplicações do OAuth 2.Cada maneira requer diferentes configurações de permissão de segurança.

Chaves da 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.Para gerenciar recursos que você possui individualmente, crie a chave da API sob sua conta.Para gerenciar recursos de propriedade do grupo, crie a chave da API sob o grupo alvo.Para mais informações sobre chaves de API de propriedade do grupo, veja Permissões de chave de API de propriedade do grupo.

Uma vez que você cria uma chave de API, não pode mudar sua propriedade entre indivíduos ou grupos, então, se você criar uma chave de API sob sua própria conta, não poderá usá-la para gerenciar recursos de grupo.

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

1. Adicione recursos a Permissões de Acesso .
2. Adicione Leitura e Escrita permissões de operação à experiência selecionada, dependendo dos escopos necessários dos endpoints que você pretende chamar.

Uma vez que você tenha a chave da API, copie-a para o cabeçalho de solicitação x-api-key. Todos os pontos finais requerem o cabeçalho de solicitação x-api-key.

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

Aplicativos do OAuth 2.0

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

Crie um novo ativo

Para carregar um novo recurso por meio de um solicitar / pedirHTTP:

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

2. Na sua solicitar / pedir:

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

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

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

Atualize um ativoexistente

Para atualizar um recurso existente por um solicitar / pedirHTTP:

1. Copie a chave da API para o cabeçalho de solicitação da API de atualização de recurso.
2. Adicione o tipo de recurso e o ID do recurso na sua solicitar / pedir. Para copiar o ID do seu recurso:

   1. Navegue até a página Criação do Painel do Criador .
   2. Selecione a categoria Itens de Desenvolvimento .
   3. Selecione a categoria do seu recurso e encontre o recurso ativo.
   4. Passe o mouse sobre a miniatura do recurso alvo e clique no botão ⋯ para exibir uma lista de opções, então selecione Copiar ID do recurso 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}"'

Recuperar o status da operação de recursos

Se a solicitação para criar um novo recurso ou atualizar um recurso existente for bem-sucedida, ela retorna 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 da API para o cabeçalho de solicitação x-api-key da solicitação do método Obter Operação 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 retorna um Objetoque inclui um representando as informações de upload do recurso ou um explicando por que o upload do recurso falha como mostra o seguinte exemplo 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 recurso criado na sua conta Roblox.

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

Adicionar API de recursos ao aplicativo OAuth 2.0

Você pode criar aplicativos OAuth 2.0 que suportam a API de Recursos para permitir que seus usuários carreguem e atualizem recursos no Roblox.

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

1. Ao registrar seu aplicativo , sob Permissões , selecione recurso:leitura e recurso:escrita escopos.

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

   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. 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 recurso para criar ou atualizar na URI de solicitação.O seguinte exemplo mostra uma solicitação de amostra para carregar um novo recurso:

   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\": \"This is a description\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'