Cabeçalhos comuns de solicitação REST do Azure Cosmos DB

Artigo
01/29/2025

Os cabeçalhos de solicitação a seguir são comuns a todas as tarefas que você pode fazer com a API do SQL:

Cabeçalho	Necessário	Tipo	Descrição
de Autorização	Necessário	Corda	O token de autorização para a solicitação. Para obter mais informações sobre como gerar um token de autorização válido, consulte controle de acesso em recursos do Cosmos DB
de Tipo de Conteúdo	Obrigatório (em PUT, PATCH e POST)	Corda	Para POST em operações de consulta, ele deve ser application/query+json. Para operações patch, deve ser application/json_patch+json. Para anexos, deve ser definido como o tipo Mime do anexo. Para obter mais informações sobre tipos mime, consulte Criar um anexo Para todas as outras tarefas, deve ser application/json.
if-match	Opcional (aplicável somente em PUT e DELETE)	Corda	Usado para tornar a operação condicional para simultaneidade otimista. O valor deve ser o valor da etag do recurso.
If-None-Match	Opcional (aplicável somente em GET)	Corda	Torna a operação condicional para ser executada somente se o recurso tiver sido alterado. O valor deve ser a etag do recurso.
If-Modified-Since	Opcional (aplicável somente em GET)	Data	Retorna a etag do recurso modificado após a data especificada no formato RFC 1123. Ignorado quando If-None-Match é especificado
do Agente de Usuário	Opcional	Corda	Uma cadeia de caracteres que especifica o agente do usuário cliente que está executando a solicitação. O formato recomendado é {nome do agente de usuário}/{version}. Por exemplo, o SDK oficial do .NET da API DO SQL define a cadeia de caracteres User-Agent como Microsoft.Document.Client/1.0.0.0. Um agente de usuário personalizado pode ser algo como ContosoMarketingApp/1.0.0.
x-ms-activity-id	Opcional	Corda	Um identificador fornecido pelo cliente para a operação, que é ecoado na resposta do servidor. O valor recomendado é um identificador exclusivo.
de nível de consistência x-ms	Opcional	Corda	A substituição do nível de consistência para opções de leitura em documentos e anexos. Os valores válidos são: Strong, Bounded, Session ou Eventual (em ordem de mais forte a mais fraca). A substituição deve ser a mesma ou mais fraca do que o nível de consistência configurado da conta.
de continuação x-ms	Opcional	Corda	Um token de cadeia de caracteres retornado para consultas e operações de feed de leitura se houver mais resultados a serem lidos. Os clientes podem recuperar a próxima página de resultados reenviando a solicitação com o cabeçalho de solicitação de continuação x-ms definido para esse valor.
x-ms-date	Necessário	Data	A data da solicitação por formato de data RFC 1123 expressa em Tempo Universal Coordenado, por exemplo, Sex, 08 Abr 2015 03:52:31 GMT.
x-ms-max-item-count	Opcional	Número	Um inteiro que indica o número máximo de itens a serem retornados por página. Uma contagem de itens x-ms-max de -1 pode ser especificada para permitir que o serviço determine a contagem de itens ideal. Esse é o valor de configuração recomendado para x-ms-max-item-count
x-ms-documentdb-partitionkey	Opcional	Array	O valor da chave de partição para a operação de anexo ou documento solicitado. Necessário para operações em documentos e anexos quando a definição da coleção inclui uma definição de chave de partição. Esse valor é usado para definir o escopo da consulta para documentos que correspondem aos critérios de chave de partição. Por design, é uma consulta de partição única. Com suporte nas versões de API 2015-12-16 e mais recentes. Atualmente, a API do SQL dá suporte a uma única chave de partição, portanto, essa é uma matriz que contém apenas um valor.
x-ms-documentdb-query-enablecrosspartition	Opcional	Booleano	Quando esse cabeçalho é definido como true e se a consulta não tiver uma chave de partição, o Azure Cosmos DB exibirá a consulta entre partições. O fan-out é feito emitindo consultas individuais para todas as partições. Para ler os resultados da consulta, os aplicativos cliente devem consumir os resultados do FeedResponse e verificar a propriedade ContinuationToken. Para ler todos os resultados, continue iterando nos dados até que ContinuationToken seja nulo.
x-ms-session-token	Necessário (somente para consistência de sessão)	Corda	Um token de cadeia de caracteres usado com consistência de nível de sessão. Para obter mais informações, consulte Usando níveis de consistência no Cosmos DB
x-ms-version	Necessário	Corda	A versão do serviço REST do Cosmos DB. Para obter uma lista de versões de API com suporte, consulte Referência da API REST do Azure Cosmos DB
de mensagens instantâneas	Opcional	Corda	Indica uma solicitação de de feed de alterações. Deve ser definido como "Feed incremental" ou omitido de outra forma.
x-ms-documentdb-partitionkeyrangeid	Opcional	Número	Usado em solicitações de de feed de alterações. A ID do intervalo de chaves de partição para ler dados.
x-ms-cosmos-allow-tentative-writes	Opcional	Booleano	Quando esse cabeçalho for definido como true para as contas do Azure Cosmos configuradas com vários locais de gravação, o Azure Cosmos DB permitirá gravações em todos os locais. As solicitações de gravação com o valor desse cabeçalho definido como false (ou se o cabeçalho estiver ausente) falharão com o código 403 Status da Resposta com a mensagem de erro "As gravações não são permitidas na região".

Consulte também