Padrões

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

Esta página abrange padrões comuns com as APIs Open Cloud, particularmente ao redor de fazer solicitações e lidar com respostas.

Caminhos

Para fazer uma solicitação às APIs da Nuvem Aberta, você deve primeiro formar uma URL. Essa URL é uma combinação da URL base ( https://apis.roblox.com/cloud/v2 ) e do caminho da API da Nuvem Aberta (por exemplo, /universes/universe-id/places/place-id/user-

https://apis.roblox.com/cloud/v2/users/4687549151/inventory-items?maxPageSize=100

Muitos caminhos, incluindo o exemplo acima, têm parâmetros de caminho , designados por aspas curvas na referência da API. Os parâmetros de caminho são apenas variáveis que você inseriu antes de fazer a solicitação e geralmente são IDs: IDs do usuário, IDs de grupo, armazenamento de dados, etc. IDs geralmente são númericos, mas não necessariamente; por exemplo, armazenamento de dados e armazenamento de memória ID

Alguns recursos têm múltiplos padrões de caminho, visíveis sob o cabeçalho Caminhos de Recursos na referência da API. Por exemplo, a URL para Listar Restrições de Usuário pode ser uma das seguindo:

  • https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/user-restrictions
  • https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/places/{place-id}/user-restrictions

Você provavelmente pode inferir a diferença entre os dois: algumas restrições de usuário se aplicam a um universo inteiro (experiência), enquanto outras se aplicam a locais específicos dentro de um universo. Além da pequena adição ao parâmetro de caminho e extra caminho, as chamadas são idênticas.

Muitas APIs retornam um caminho como parte de sua resposta, que você pode usar para fazer solicitações futuras. Se uma API precisar de mais de alguns segundos para concluir uma solicitar / pedir, ela geralmente retorna um operação em vez do recurso ou resposta em si.

Comprimento e Tipo de Conteúdo

Muitas chamadas de API, especialmente aquelas que criam ou atualizam recursos, requerem um corpo de solicitação JSON. Se sua solicitação tiver um corpo, certifique-se de incluir os cabeçalhos Content-Length e Content-Type. A maioria dos clientes HTTP adiciona esses cabeçalhos automaticamente.

Paginação

Se você especificar maxPageSize em sua solicitar / pedir, alguns métodos retornam resultados pagados: essencialmente respostas parciais:

GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25



{

  "inventoryItems": [

    ...

  ],

  "nextPageToken": "aaaBBB"

}

Se uma resposta incluir um valor para nextPageToken , use esse valor no parâmetro pageToken da solicitação seguinte para recuperar a próxima página. Quando nextPageToken estiver vazio, você chegou ao fim de seus resultados:

GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=aaaBBB



{

  "inventoryItems": [

    ...

  ],

  "nextPageToken": ""

}

Além do pageToken, você deve usar a mesma consulta para que a paginação funcione adequadamente. Alterar qualquer parâmetro de filtro resulta em um erro de 400.

Operações de Longo Percurso

Alguns métodos retornam um objeto Operation que representa uma solicitação em andamento que retorna uma resposta assíncrona mais tarde. O objeto contém os seguintes campos:

  • caminho - O caminho do ponto de terminação para chamar para a conclusão da solicitar / pedir. Aponte o caminho para a URL original do método de recursos.
  • feito - Um valor deBooleano que representa se a operação está ou não completa.
  • resposta - O Objetode resposta. Este campo está vazio até que o campo done tenha um valor de true.
  • metadados - Metadados personalizados específicos para a solicitação sendo feita.
Exemplo de Objeto de Operação
{

  "path": "v1/assets/12345/operation/xyz",

  "done": true,

  "response": {

    "value1": "myValue",

    "value2": 1234

  },

  "metadata": {

    "metadata1": "string",

    "metadata2": 5678

  }

}

Use o caminho do ObjetoOperation para pesquisar quando o recurso estiver pronto. Uma boa estratégia é usar o backoff exponencial. Por exemplo, você pode pesquisar imediatamente, depois de um segundo, dois segundos, quatro segundos, etc.

def PollForResults(operationPath):

    currentRetries = 0

    maxRetries = 10

    retryPollingDelay = 1

    retryPollingMultiplier = 2

    while (currentRetries < maxRetries):

        # Sem atraso na primeira verificar / conferir

        if (currentRetries == 0):

            results = GetOperation(operationPath)

        # Tente novamente a lógica para verificações posteriores

        else:

            time.sleep(retryPollingDelay)

            results = GetOperation(operationPath)

            # Desvanecimento exponencial

            retryPollingDelay *= retryPollingMultiplier

        # Verifique se houver resultados e retorne se eles existirem

        if (results.status_code != 200 or results.json()[doneJSONKey]):

            return results

        # Caso contrário, aumente o número de tentativas

        else:

           currentRetries += 1

Para um exemplo de código mais completo que usa umIntervalo de Tentativa Fixo em vez de Backoff Exponencial, see Poling for Results.

Filtrando

Alguns métodos permitem filtrar a resposta incluindo um parâmetro filter na solicitar / pedir. As seções a seguir descrevem a sintaxe de filtro e diretrizes para os endpoints especificados.

Listar Assinaturas de Grupo

O personagem wildcard - pode ser usado em vez do ID de grupo para listar membros em todos os grupos: groups/-/memberships.

A filtragem segue a Língua de Expressão Comum (CEL). Apenas dois operadores são suportados:

  • ==
  • in [...]

Se você especificar um ID de grupo no caminho de recursos, você pode filtrar membros por usuário ou papel no seguinte formato:

  • Filtro de usuário : filter="user == 'users/9876543210'"
  • Filtro de papel : filter="role == 'groups/123/roles/7920705'"

Se você especificar o personagem de Wildcard para o ID do grupo, você deve filtrar membros por usuário (até 50) no seguinte formato:

  • Filtro de usuário : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"

Exibir itens do inventário

Você pode filtrar por status de colecionável, digitarde item de inventário e ID de item de inventário. Se você não fornecer um filtro, o inventário inteiro do usuário é retornado.

O formato do filtro é uma lista separada por ponto:

filter={field}={value};{field}={value},{value},...;{field}=...

  • {field} pode ser qualquer um dos campos de tipo ou campo de ID pré-definidos nas tabelas a seguir.
  • {value} pode ser uma string / cadeia / texto,Boolean, ou lista de valores. Dependendo do digitarde campo, isso pode ser um único valor (campos de lista) ou múltiplos valores (campos de lista).

Tipos de Campo

| Filter | Type | Description | | : | Include private servers in the response. Default is false. Este campo deve ser usado com o campo badges3> para retornar itens e apenas retornar itens que não sejam UGC limitados. | | 6> in

Campos de ID

| Filter | Type | Type | Description | | | : - | : | |

Exemplos

  • Retorna todos os itens coletíveis que o usuário possui:

    filter=onlyCollectibles=true;inventoryItemAssetTypes=*

  • Retorna todos os itens dos tipos especificados:

    filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

  • Retorna todos os itens dos tipos listados ou qualquer passe de jogo. Exclui os emblemas dos resultados (mesmo comportamento como se badges não estivesse incluído no filtro):

    filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false>

  • Retorna recursos que correspondem aos IDs especificados:

    filter=assetIds=1,2,3,4

  • Retorna recursos, emblemas, passes de jogo e servidores privados que correspondam aos IDs especificados:

    filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4