Atualização parcial de documento no Azure Cosmos DB

Artigo
08/15/2024

APLICA-SE A: NoSQL

O recurso de atualização parcial de documento do Azure Cosmos DB (também conhecido como API de Patch) fornece uma maneira conveniente de modificar um documento em um contêiner. Para atualizar um documento hoje, o cliente precisa lê-lo, executar verificações de Controle de Simultaneidade Otimista (se necessário), atualizar o documento localmente e, em seguida, envia-o pela rede como uma chamada de API de substituição completa de documento.

O recurso de atualização parcial de documento melhora significativamente essa experiência. O cliente pode simplesmente enviar as propriedades/campos modificados em um documento sem fazer uma operação de substituição completa de documento. Os principais benefícios desse recurso incluem:

Produtividade do desenvolvedor aprimorada: fornece uma API conveniente para facilitar o uso e a capacidade de atualizar o documento condicionalmente.
Melhorias de desempenho: evita ciclos de CPU extras no lado do cliente, reduz a latência de ponta a ponta e diminui a largura de banda da rede.
Gravações em várias regiões: dá suporte a uma resolução de conflitos automática e transparente com atualizações parciais em caminhos discretos no mesmo documento.

Observação

A operação de Atualização parcial do documento é baseada no JSON Patch RFC. Os nomes de propriedades em caminhos precisam escapar dos caracteres ~ e / para ~0 e ~1, respectivamente.

Um exemplo de documento JSON de destino:

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 455.95,
  "inventory": {
    "quantity": 15
  },
  "used": false,
  "categoryId": "road-bikes",
  "tags": ["r-series"]
}

Um documento de JSON Patch:

[
  { "op": "add", "path": "/color", "value": "silver" },
  { "op": "remove", "path": "/used" },
  { "op": "set", "path": "/price", "value": 355.45 }
  { "op": "incr", "path": "/inventory/quantity", "value": 10 },
  { "op": "add", "path": "/tags/-", "value": "featured-bikes" },
  { "op": "move", "from": "/color", "path": "/inventory/color" }
]

O documento JSON resultante:

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 355.45,
  "inventory": {
    "quantity": 25,
    "color": "silver"
  },
  "categoryId": "road-bikes",
  "tags": ["r-series", "featured-bikes"]
}

Operações com suporte

Esta tabela resume as operações com suporte neste recurso.

Observação

Caminho de destino refere-se a um local no documento JSON

Tipo de operação	Descrição
Add	Dependendo do caminho de destino, o `Add` executará um dos seguintes: • Se o caminho de destino especificar um elemento que não existe, ele será adicionado. • Se o caminho de destino especificar um elemento que já existe, o valor dele será substituído. • Se o caminho de destino for um índice de matriz válido, um novo elemento será inserido na matriz no índice especificado. Isso desloca os elementos existentes após o novo elemento. • Se o índice especificado for igual ao comprimento da matriz, ele acrescentará um elemento a ela. Em vez de especificar um índice, também é possível usar o caractere `-`. Isso também anexará o elemento à matriz. Observação: a especificação de um índice maior que o comprimento da matriz resulta em erro.
Configurar	A operação `Set` é semelhante a `Add`, exceto com o tipo de dados Array. Se o caminho de destino for um índice de matriz válido, o elemento existente nesse índice será atualizado.
Substituir	A operação `Replace` é semelhante à `Set`, exceto que segue a semântica somente de substituição rigorosa. Se o caminho de destino especificar um elemento ou uma matriz que não existe, isso resultará em um erro.
Remover	Dependendo do caminho de destino, o `Remove` executará um dos seguintes: • Se o caminho de destino especificar um elemento que não existe, isso resultará em um erro. • Se o caminho de destino especificar um elemento que já existe, ele será removido. • Se o caminho de destino for um índice de matriz, ele será excluído e todos os elementos acima do índice especificado serão deslocados para uma posição anterior. Observação: a especificação de um índice igual ou maior que o comprimento da matriz resultará em erro.
Incremento	Esse operador incrementa um campo de acordo com o valor especificado. Ele pode aceitar valores positivos e negativos. Se o campo não existir, ele o criará e definirá com o valor especificado.
Mover	Esse operador remove o valor em um local especificado e o adiciona ao local de destino. O objeto de operação DEVE conter um membro "from", que é uma cadeia de caracteres que contém um valor de ponteiro JSON que faz referência ao local no documento de destino do qual mover o valor. O local "from" DEVE existir para que a operação seja bem-sucedida. Se o local "caminho" sugerir um objeto que não existe, ele criará o objeto e definirá o valor igual ao valor no local "from" •Se o local "path" sugerir um objeto que já existe, ele substituirá o valor no local "path" pelo valor no local "from" •O atributo "Path" não pode ser um filho JSON do local JSON "from"

Modos com suporte

O recurso de atualização parcial de documento fornece suporte aos modos de operação a seguir. Consulte o documento Introdução para obter exemplos de código.

Patch de documento único: é possível aplicar o patch em um só documento com base na ID e na chave de partição. É possível executar diversas operações de patch em um só documento. O limite máximo é de 10 operações.
Aplicação de patch em diversos documentos: diversos documentos na mesma chave de partição podem ter patchs aplicados como parte de uma transação. Essa transação de vários documentos é confirmada somente se todas as operações são bem-sucedidas na ordem descrita. Se qualquer operação falhar, toda a transação será revertida.
Atualização condicional: Para os modos acima mencionados, também é possível adicionar um predicado de filtro do tipo SQL (por exemplo, from c where c.taskNum = 3), de modo que a operação falhe se a condição prévia especificada no predicado não for atendida.
Também é possível usar as APIs em massa de SDKs com suporte para executar uma ou mais operações de patch em diversos documentos.

Semelhanças e diferenças

Vamos comparar as semelhanças e as diferenças entre os modos com suporte.

Adicionar ou Configurar

A operação Set é semelhante à Add para todos os tipos de dados, exceto Array. Uma operação Add em qualquer índice (válido) resulta na adição de um elemento no índice especificado e no deslocamento dos elementos existentes na matriz após o elemento existente. Esse comportamento é diferente do que ocorre com a operação Set, que atualiza o elemento existente no índice especificado.

Adicionar ou Substituir

A operação Add adicionará uma propriedade se ela ainda não existir (incluindo o tipo de dados Array). Ocorrerá uma falha na operação Replace se a propriedade não existir (aplica-se também ao tipo de dados Array).

Configurar ou Substituir

A operação Set adicionará uma propriedade se ela ainda não existir (exceto se houver um Array). Ocorrerá uma falha na operação Replace se a propriedade não existir (aplica-se também ao tipo de dados Array).

Observação

A operação Replace é adequada para que o usuário tenha algumas das propriedades sempre presentes e você possa fazer as aplicações relativas.

Referência de API REST para atualização parcial de documento

A API REST do Azure Cosmos DB fornece acesso programático aos recursos do Azure Cosmos DB para criar, consultar e excluir bancos de dados, coleções de documentos e documentos. Além de executar operações de inserção, substituição, exclusão, leitura, enumeração e consulta em documentos JSON em uma coleção, você pode usar o método HTTP PATCH para a operação de atualização parcial de documentos. Veja a Referência de API REST do Azure Cosmos DB para obter detalhes.

Por exemplo, veja a aparência da solicitação para uma operação set que usa a atualização parcial de documentos.

PATCH https://querydemo.documents.azure.com/dbs/FamilyDatabase/colls/FamilyContainer/docs/Andersen.1 HTTP/1.1
x-ms-documentdb-partitionkey: ["Andersen"]
x-ms-date: Tue, 29 Mar 2016 02:28:29 GMT
Authorization: type%3dmaster%26ver%3d1.0%26sig%3d92WMAkQv0Zu35zpKZD%2bcGSH%2b2SXd8HGxHIvJgxhO6%2fs%3d
Content-Type:application/json_patch+json
Cache-Control: no-cache
User-Agent: Microsoft.Azure.DocumentDB/2.16.12
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=602; x-ms-session-token=602
Content-Length: calculated when request is sent
Connection: keep-alive

{
  "operations": [
    {
      "op": "set",
      "path": "/Parents/0/FamilyName",
      "value": "Bob"
    }
  ]
}

Resolução de conflito de nível de documento ou nível de caminho

Se sua conta do Azure Cosmos DB estiver configurada com diversas regiões de gravação, conflitos e políticas de resolução de conflitos serão aplicáveis no nível de documento, com a política de resolução de conflitos padrão sendo "A última gravação vence" (LWW). Para atualizações parciais de documentos, as operações de patch em diversas regiões detectam e resolvem conflitos em um nível de caminho mais granular.

A resolução de conflitos pode ser mais bem compreendida com um exemplo.

Suponha que você tenha o seguinte documento no Azure Cosmos DB:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345", "67890"],
  "level": "gold"
}

Clientes diferentes emitem operações de patch simultaneamente em regiões diferentes:

atributo /level de Set para platinum
Remove 67890 de /phone

Como as solicitações de Patch foram feitas para caminhos não conflitantes dentro do documento, estas solicitações são resolvidas automaticamente e de forma transparente (ao contrário da estratégia Last Writer Wins a nível de documento).

O cliente verá o seguinte documento após a resolução do conflito:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345"],
  "level": "platinum"
}

Observação

Se a mesma propriedade de um documento estiver passando por correções simultaneamente em várias regiões, serão aplicadas as políticas de resolução de conflitos regulares.

Feed de alteração

O feed de alterações no Azure Cosmos DB escuta um contêiner quanto às alterações e, em seguida, gera os documentos alterados. Usando o feed de alterações, você verá todas as atualizações nos documentos, incluindo as atualizações de documentos parciais e completas. Quando você processa os itens do feed de alterações, o documento completo é retornado, mesmo que a atualização seja o resultado de uma operação de patch.

Para obter mais informações sobre o feed de alterações no Azure Cosmos DB, confira Feed de alterações no Azure Cosmos DB.

Próximas etapas

Saiba como começar a usar a atualização parcial de documento com .NET, Java e Node
Perguntas frequentes sobre a atualização parcial de documento

Compartilhar via

Atualização parcial de documento no Azure Cosmos DB

Operações com suporte

Modos com suporte

Semelhanças e diferenças

Adicionar ou Configurar

Adicionar ou Substituir

Configurar ou Substituir

Referência de API REST para atualização parcial de documento

Resolução de conflito de nível de documento ou nível de caminho

Feed de alteração

Próximas etapas

Comentários

Recursos adicionais