Padrões

Esta página cobre padrões comuns com as APIs do Open Cloud, particularmente em relação à realização de solicitações e ao manuseio de respostas.

Caminhos

Para fazer uma solicitação às APIs do Open Cloud, você deve primeiro formar uma URL. Esta URL é uma combinação da URL base (por exemplo, https://apis.roblox.com), o caminho da API do Open Cloud (por exemplo, /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions), e quaisquer parâmetros de consulta (por exemplo, ?maxPageSize=25). Uma URL de solicitação completa pode parecer com isso:

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 chaves no documento da API. Parâmetros de caminho são apenas variáveis que você insere antes de fazer a solicitação e são quase sempre IDs: IDs de usuário, IDs de grupo, IDs de lugar, etc. Os IDs são frequentemente numéricos, mas não necessariamente; por exemplo, IDs de loja de dados e de loja de memória suportam um conjunto de caracteres mais amplo.

Comprimento e tipo de conteúdo

Muitas chamadas de API, particularmente aquelas que criam ou atualizam, requerem um corpo de solicitação em JSON. Se sua solicitação tiver um corpo, não se esqueça 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 solicitação, alguns métodos retornam resultados paginados — essencialmente respostas parciais:

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

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": "aaaBBB"
}

GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25

{
  "dataStores": [
    ...
  ],
  "nextPageToken": "datastore1"
}

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

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

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": ""
}

GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25&pageToken=datastore1

{
  "dataStores": [
    ...
  ]
}

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

Open Cloud v2

Múltiplos caminhos

Alguns recursos têm múltiplos padrões de caminho, visíveis sob o cabeçalho Caminhos de Recursos no documento da API. Por exemplo, a URL para Listar Restrições de Usuário pode ser qualquer um dos seguintes:

• 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 todo um universo (jogo), enquanto outras se aplicam a locais específicos dentro de um universo. Além da pequena adição ao caminho e um parâmetro de caminho extra, as chamadas são idênticas.

Muitos pontos finais retornam um caminho como parte de sua resposta, que você pode usar para fazer solicitações adicionais. Se uma API precisar de mais do que alguns segundos para atender a uma solicitação, ela frequentemente retorna uma operação em vez do recurso ou da resposta propriamente dita.

Operações de longa duração

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

• path - O caminho do ponto final a ser chamado para verificar a conclusão da solicitação. Anexe o caminho à URL base original do método de recurso.
• done - Um valor booleano que representa se a operação foi concluída ou não.
• response - O objeto de resposta. Este campo está vazio até que o campo done tenha um valor de true.
• metadata - 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 objeto Operation para verificar quando o recurso está pronto. Uma boa estratégia é usar backoff exponencial. Por exemplo, você pode fazer a verificação imediatamente, depois após 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 verificação
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Lógica de repetição para verificações subsequentes
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Backoff exponencial
            retryPollingDelay *= retryPollingMultiplier
        # Verifique os resultados e retorne se existirem
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Caso contrário, incremente a contagem de tentativas
        else:
           currentRetries += 1

Para um exemplo de código mais completo que usa um intervalo de repetição fixo em vez de backoff exponencial, consulte Verificar resultados.

Filtragem

Alguns métodos permitem que você filtre a resposta incluindo um parâmetro filter na solicitação. As seções a seguir descrevem a sintaxe e as diretrizes de filtro para os pontos finais especificados.

Listar membros de grupo

O caractere curinga - pode ser usado no lugar do ID do grupo para listar as adesões em todos os grupos: groups/-/memberships.

A filtragem está em conformidade com a Linguagem de Expressão Comum (CEL). Apenas dois operadores são suportados:

• ==
• in [...]

Se você especificar um ID de grupo no caminho do recurso, pode filtrar as adesões por usuário ou por função nos seguintes formatos:

• Filtro de usuário: filter=user == 'users/9876543210'
• Filtro de função: filter=role == 'groups/123/roles/7920705'

Se você especificar o caractere curinga para o ID do grupo, deve filtrar as adesões por usuário (até 50) no seguinte formato:

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

Listar itens de inventário

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

O formato do filtro é uma lista separada por ponto e vírgula:

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

• {field} pode ser qualquer um dos campos de tipo predefinidos ou campos de ID nas tabelas a seguir.
• {value} pode ser uma string, booleano ou enumeração. Dependendo do tipo de campo, isso pode ser um único valor (campos booleanos) ou múltiplos valores (campos de lista).

Campos de tipo

Campos de ID

Exemplos

• Retorna todos os itens colecioná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 quaisquer passes de jogo. Exclui distinções dos resultados (o mesmo comportamento como se badges não estivesse incluído no filtro):

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

• Retorna ativos que correspondem aos IDs especificados:

  filter=assetIds=1,2,3,4

• Retorna ativos, distinções, passes de jogo e servidores privados que correspondem aos IDs especificados:

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