Atualização parcial de documentos no Azure Cosmos DB
APLICA-SE A: 
NoSQL
O recurso Atualização Parcial de Documentos do Azure Cosmos DB (também conhecido como API de Patch) fornece uma maneira conveniente de modificar um documento em um contêiner. Atualmente, para atualizar um documento, o cliente precisa lê-lo, execute verificações de controle de simultaneidade otimista (se necessário), atualize o documento localmente e, em seguida, envie-o por fio como um documento inteiro Substituir chamada de API.
O recurso de atualização parcial de documentos melhora significativamente essa experiência. O cliente só pode enviar as propriedades/campos modificados em um documento sem fazer uma operação de substituição completa do documento. Os principais benefícios desse recurso incluem:
- Maior produtividade do desenvolvedor: fornece uma API conveniente para facilidade de uso e a capacidade de atualizar condicionalmente o documento.
- Melhorias de desempenho: Evita ciclos extras de CPU no lado do cliente, reduz a latência de ponta a ponta e a largura de banda da rede.
- Gravações em várias regiões: Suporta resolução automática e transparente de conflitos com atualizações parciais em caminhos discretos dentro do mesmo documento.
Nota
A operação de atualização parcial de documentos é baseada na RFC do patch JSON. Os nomes de propriedade em caminhos precisam escapar dos ~ e / caracteres como ~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 patch JSON:
[
{ "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 suportadas
Esta tabela resume as operações suportadas por este recurso.
Nota
caminho de destino refere-se a um local dentro do documento JSON
| Tipo de operação | Description |
|---|---|
| Adicionar | Add Executa um dos seguintes procedimentos, dependendo do caminho de destino: • 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, seu valor 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 à matriz. Em vez de especificar um índice, você também pode usar o - caractere. Isso também resulta no elemento sendo anexado à matriz.Nota: Especificar um índice maior do que o comprimento da matriz resulta em um erro. |
| Definir | 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. |
| Replace | Replace operação é semelhante a Set exceto que segue estrita substituir apenas semântica. Caso o caminho de destino especifique um elemento ou uma matriz que não existe, isso resulta em um erro. |
| Remover | Remove Executa um dos seguintes procedimentos, dependendo do caminho de destino: • 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 de volta uma posição. Nota: Especificar um índice igual ou maior que o comprimento da matriz resultaria em um erro. |
| Incremento | Este operador incrementa um campo pelo valor especificado. Pode aceitar valores positivos e negativos. Se o campo não existir, ele o criará e o definirá com o valor especificado. |
| Moverr | 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 "de", 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 "de" 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 "de" •Se o local "caminho" sugerir um objeto que já existe, ele substituirá o valor no local "caminho" pelo valor no local "de" •O atributo "Path" não pode ser um filho JSON do local JSON "from" |
Modos suportados
O recurso de atualização parcial de documentos suporta os seguintes modos de operação. Consulte o documento Introdução para obter exemplos de código.
Patch de documento único: Você pode corrigir um único documento com base em sua ID e na chave de partição. É possível executar várias operações de patch em um único documento. O limite máximo é de 10 operações.
Patch de vários documentos: vários documentos dentro da mesma chave de partição podem ser corrigidos como parte de uma transação. Essa transação multidocumento só é confirmada se todas as operações forem bem-sucedidas na ordem em que foram descritas. Se alguma 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 semelhante ao SQL (por exemplo,
from c where c.taskNum = 3) de modo que a operação falhe se a pré-condição especificada no predicado não for satisfeita.Você também pode usar as APIs em massa de SDKs suportados para executar uma ou mais operações de patch em vários documentos.
Semelhanças e diferenças
Vamos comparar as semelhanças e diferenças entre os modos suportados.
Adicionar vs Definir
Set é semelhante para Add todos os tipos de dados, exceto Array. Uma Add operação em qualquer índice (válido) resulta na adição de um elemento no índice especificado e quaisquer elementos existentes na matriz acabam mudando após o elemento existente. Esse comportamento contrasta com a Set operação que atualiza o elemento existente no índice especificado.
Adicionar vs Substituir
Add adiciona uma propriedade se ela ainda não existir (incluindo Array o tipo de dados). Replace A operação falhará se a propriedade não existir (aplica-se também ao Array tipo de dados).
Definir vs Substituir
Set A operação adiciona uma propriedade se ela ainda não existir (exceto se houver um Array). Replace A operação falhará se a propriedade não existir (aplica-se também ao Array tipo de dados).
Nota
Replace é um bom candidato onde o usuário espera que algumas das propriedades estejam sempre presentes e permite que você afirme / imponha isso.
Referência da API REST para atualização parcial de documentos
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 PATCH método HTTP para a operação de atualização parcial de documentos. Consulte a Referência da API REST do Azure Cosmos DB para obter detalhes.
Por exemplo, aqui está a aparência da solicitação para uma set operação usando a atualização parcial do documento.
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 conflitos ao nível do documento vs nível do caminho
Se sua conta do Azure Cosmos DB estiver configurada com várias regiões de gravação, os conflitos e as políticas de resolução de conflitos serão aplicáveis no nível do documento, com Last Write Wins (LWW) sendo a política de resolução de conflitos padrão. Para atualizações parciais de documentos, as operações de patch em várias regiões detetam e resolvem conflitos em um nível de caminho mais granular.
A resolução de conflitos pode ser melhor 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 diferentes regiões:
Setatributo/levelà platinaRemove67890 a partir de/phone
Como as solicitações de patch foram feitas para caminhos não conflitantes dentro do documento, essas solicitações são resolvidas automaticamente e de forma transparente (ao contrário de Last Writer Wins em um nível de documento).
O cliente verá o seguinte documento após a resolução de conflitos:
{
"id": 1,
"name": "John Doe",
"email": "jdoe@contoso.com",
"phone": ["12345"],
"level": "platinum"
}
Nota
Caso a mesma propriedade de um documento esteja sendo corrigida simultaneamente em várias regiões, as políticas regulares de resolução de conflitos serão aplicadas.
Feed de alterações
O feed de alterações no Azure Cosmos DB escuta um contêiner para quaisquer alterações e, em seguida, produz documentos que foram alterados. Usando o feed de alterações, você vê todas as atualizações de documentos, incluindo atualizações parciais e completas de documentos. Quando você processa itens do feed de alterações, o documento completo é retornado mesmo que a atualização tenha sido o resultado de uma operação de patch.
Para obter mais informações sobre o feed de alterações no Azure Cosmos DB, consulte Alterar feed no Azure Cosmos DB.