Lidar com solicitações de armazenamento de dados Open Cloud

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

Há uma série de considerações sobre o envio de solicitações e o manuseio de respostas das APIs de armazenamento de dados Open Cloud.

Cabeçalhos HTTP

Como todos os pontos de extremidade do Open Cloud, as solicitações de armazenamento de dados que utilizam autenticação por chave de API devem incluir o cabeçalho x-api-key. Para mais informações, veja Gerenciar chaves de API.

Uma chave de API incorreta ou ausente resulta em um erro 401.
Uma chave de API válida que não possui as permissões corretas resulta em um erro 403.

Se uma solicitação incluir um corpo, como uma solicitação de criação ou atualização, inclua os cabeçalhos Content-Type: application/json e Content-Length. A maioria dos clientes inclui esses cabeçalhos automaticamente.

Paginação

Os armazenamentos de dados frequentemente contêm muitas entradas, o que significa que seu código, especialmente ao chamar Listar Entradas de Armazenamento de Dados, deve lidar com um número máximo de resultados e páginas. Para saber mais, veja Paginação.

Filtros

Se você usar prefixos nos nomes das suas entradas de armazenamento de dados, provavelmente deseja filtrar suas chamadas GET, assim:


def list_entries(universe, data_store, filter):
    list_path = f'universes/{universe}/data-stores/{data_store}/entries'
    url = base_url + list_path
    return requests.get(url, params={'filter': f'id.startsWith("global/{filter}")'}, headers={apiHeaderKey: apiKey})

A sintaxe de filtro é extremamente limitada. Consulte a documentação de referência para filtros disponíveis para armazenamentos de dados padrão e ordenados.

Permitir flags ausentes

Os métodos PATCH (atualização) para armazenamentos de dados padrão e ordenados têm um parâmetro allow_missing. Se definido como verdadeiro, este parâmetro permite que você crie entradas que não existem, em vez de lançar um erro. Mantenha este parâmetro em seu valor padrão de falso, a menos que você tenha um bom motivo para não fazê-lo; atualizar uma entrada que nunca foi criada geralmente representa um erro na lógica de programação.

Escopos

Muitas solicitações exigem que você especifique um escopo, mesmo que seja o valor padrão de global. Esses escopos são distintos dos escopos de permissão e permitem que você subdivida e organize as entradas em um armazenamento de dados.

No entanto, em vez de criar escopos não padrão, recomendamos fortemente o uso de prefixos. Para saber mais, veja Listagem e prefixos.

Content-MD5

Esta seção se aplica apenas à API v1 do Open Cloud.

A API v1 do Open Cloud suporta um checksum MD5 codificado em base64 opcional em algumas solicitações, que pode detectar questões de integridade de dados. Muitas linguagens possuem funções integradas para calcular o valor do cabeçalho content-md5. O seguinte exemplo usa Python:


$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

Se você encontrar problemas ao gerar um valor content-md5 válido, pode ser necessário codificar o corpo da sua solicitação em UTF-8 antes de calcular o checksum.

Português (Brasil)