Padrões | Documentação - Central de Criadores Roblox

Esta página abrange padrões comuns com as APIs da Nuvem Aberta, especialmente em torno de fazer solicitações e lidar com respostas.

Caminhos

Para fazer um pedido às APIs de Nuvem Aberta, você deve primeiro formar um URL.Este URL é uma combinação da URL base ( https://apis.roblox.com/cloud/v2 ), do caminho da API da Nuvem Aberta (por exemplo, /universes/{universe_id}/places/{place_id}/user-restrictions ), e de quaisquer parâmetros de consulta (por exemplo, ?maxPageSize=25 ).Um URL de solicitação completo 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 curly brackets na referência da API.Os parâmetros de caminho são apenas variáveis que você insere antes de fazer o pedido e quase sempre são IDs: IDs de usuário, IDs de grupo, IDs de local, etc.IDs muitas vezes são numericamente, mas não necessariamente; por exemplo, os IDs do armazenamento de dados e do armazenamento de memória suportam um configurarde caracteres mais amplo.

Alguns recursos têm vários padrões de caminho, visíveis sob o cabeçalho Caminhos de Recurso na referência da API.Por exemplo, o URL para Listar restrições de usuário pode ser qualquer um dos 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 caminho e ao parâmetro de caminho extra, as chamadas são idênticas.

Muitas APIs retornam um caminho como parte de sua resposta, que você pode usar para fazer mais solicitações.Se uma API precisa de mais de alguns segundos para preencher um solicitar / pedir, muitas vezes retorna uma operação em vez do recurso ou da própria resposta.

Comprimento e digitardo conteúdo

Muitas chamadas de API, especialmente aquelas que criam ou atualizam recursos, requerem um corpo de solicitação JSON.Se a 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 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 seguinte 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 páginação funcione corretamente. Alterar qualquer parâmetro de filtro resulta em um erro de 400.

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:

caminho - O caminho de endpoint para chamar a poll para a conclusão da solicitar / pedir. Adicione o caminho à URL original do método de recursos.
concluído - Um valor booleano que representa se a operação foi ou não concluída.
resposta - O Objetode resposta. Este campo está vazio até que o campo done tenha um valor de true.
metadata - Metadados personalizados específicos para a solicitação 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 Objetopara solicitar quando a recursa estiver pronta.Uma boa estratégia é usar retorno exponencial.Por exemplo, você pode pesquisar imediatamente, então 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 verificar / conferir
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Tente novamente a lógica para verificações posteriores
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Retrocesso exponencial
            retryPollingDelay *= retryPollingMultiplier
        # Verifique os 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 de reuso
        else:
           currentRetries += 1

Para um exemplo de código mais completo que usa um intervalo de tentativa fixa em vez de recuo exponencial, veja Poll for results.

Filtro

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

Listar associações de grupo

O caractere wildcard - pode ser usado em vez do ID de grupo para listar as associações em todos os grupos: groups/-/memberships .

A filtragem conforma-se com o Common Expression Language (CEL). Apenas dois operadores são suportados:

==
in [...]

Se você especificar um ID de grupo no caminho de recursos, você pode filtrar as associações por usuário ou 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 wildcard para o ID do grupo, deve filtrar as associaçõ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 de colecionável, digitarde item de inventário e ID de item de inventário.Se você não fornecer um filtro, todo o inventário do usuário é retornado.

O formato de filtro é uma lista separada por vírgula:

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

{field} pode ser qualquer um dos campos de tipo predefinidos ou campos de ID nas seguintes tabelas.
{value} pode ser uma string / cadeia / texto, booleano ou enum.Dependendo do digitarde campo, isso pode ser um único valor (campos booleanos) ou vários valores (campos de lista).

Você não pode combinar campos de tipo e ID no mesmo filtro.

Campos de tipo

| Filtro | Tipo | Descrição - | :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | badges | boolean | Inclua insígnias na resposta.O padrão é falso. | | gamePasses | boolean | Inclua passes de jogo na resposta.O padrão é falso. | | inventoryItemAssetTypes | Veja detalhes de ativos para a lista completa de tipos de ativos.| Lista separada por vírgula de tipos de recurso a incluir.O padrão é nenhum.Especifique * para todos os tipos de recurso.Deve ter escopo de leitura de inventário para filtrar por locais comprados. | | onlyCollectibles | boolean | Inclua apenas colecionáveis na resposta.O padrão é falso.Este campo deve ser usado com o campo inventoryItemAssetTypes para retornar itens e retorna apenas itens limitados não UGC.| | privateServers | booleano | Inclua servidores privados na resposta.O padrão é falso.Deve ter escopo de leitura de inventário para filtrar por este campo. |

Campos ID

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 quaisquer passes de jogo.Exclui insígnias dos resultados (o mesmo comportamento que se badges não fosse 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, insígnias, 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