Compartir a través de

Actualización parcial de documentos en Azure Cosmos DB

  • Artículo

SE APLICA A: NoSQL

La característica de actualización parcial de documentos de Azure Cosmos DB (también conocida como Patch API) proporciona una manera cómoda de modificar un documento en un contenedor. Actualmente, para actualizar un documento, el cliente debe leerlo, ejecutar comprobaciones de control de simultaneidad optimista (si es necesario), actualizar el documento localmente y, a continuación, enviarlo a través de la conexión como una llamada API de reemplazo del documento completo.

La característica de actualización parcial de documentos mejora considerablemente esta experiencia. El cliente puede enviar solo las propiedades o campos modificados de un documento sin realizar una operación de reemplazo completa del documento. Entre las principales ventajas de esta característica están las siguientes:

  • Mejora de la productividad de los desarrolladores: proporciona una cómoda API para facilitar el uso y la capacidad de actualizar condicionalmente el documento.
  • Mejoras de rendimiento: evita ciclos de CPU adicionales en el lado del cliente y reduce la latencia de un extremo a otro y el ancho de banda de la red.
  • Escrituras en varias regiones: admite la resolución automática y transparente de conflictos con actualizaciones parciales en rutas de acceso discretas dentro del mismo documento.

Nota

La operación de actualización parcial del documento se basa en el RFC de revisión JSON. Los nombres de propiedad de las rutas de acceso deben escapar los caracteres ~ y / como ~0 y ~1, respectivamente.

Un documento JSON de destino de ejemplo:

{
  "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"]
}

Un documento de revisión 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" }
]

El 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"]
}

Operaciones compatibles

En esta tabla se resumen las operaciones admitidas por esta característica.

Nota

Ruta de acceso de destino hace referencia a una ubicación dentro del documento JSON.

Tipo de operación Descripción
Add (Agregar) Add realiza una de las siguientes acciones, en función de la ruta de acceso de destino:
• Si la ruta de acceso de destino especifica un elemento que no existe, se agrega.
• Si la ruta de acceso de destino especifica un elemento que ya existe, su valor se reemplaza.
• Si la ruta de acceso de destino es un índice de matriz válido, se inserta un nuevo elemento en la matriz en el índice especificado. Esto desplaza los elementos existentes después del elemento nuevo.
• Si el índice especificado es igual a la longitud de la matriz, anexa un elemento a la matriz. En lugar de especificar un índice, también puede usar el carácter -. También hace que el elemento se anexe a la matriz.
Nota: Si se especifica un índice mayor que la longitud de la matriz, se produce un error.
Establecimiento La operación Set es similar a Add excepto con el tipo de datos de la matriz. Si la ruta de acceso de destino es un índice de matriz válido, se actualiza el elemento existente en dicho índice.
Sustituya La operación Replace es similar a Set excepto que sigue la semántica estricta de solo sustitución. Si la ruta de acceso de destino especifica un elemento o una matriz que no existe, se produce un error.
Remove Remove realiza una de las siguientes acciones, en función de la ruta de acceso de destino:
• Si la ruta de acceso de destino especifica un elemento que no existe, se produce un error.
• Si la ruta de acceso de destino especifica un elemento que ya existe, se quita.
• Si la ruta de acceso de destino es un índice de matriz, se elimina y los elementos situados por encima del índice especificado se desplazan una posición hacia atrás.
Nota: Si se especifica un índice igual o mayor que la longitud de la matriz, se producirá un error.
Incremento Este operador incrementa un campo por el valor especificado. Puede aceptar valores positivos y negativos. Si el campo no existe, lo crea y lo establece en el valor especificado.
Mover Este operador quita el valor en una ubicación especificada y lo agrega a la ubicación de destino. El objeto de operación DEBE contener un miembro "from", que es una cadena que contiene un valor de puntero JSON que hace referencia a la ubicación del documento de destino desde la que mover el valor. La ubicación "from" DEBE existir para que la operación se realice correctamente. Si la ubicación "path" sugiere un objeto que no existe, creará el objeto y establecerá el valor igual al valor en la ubicación "from"
•Si la ubicación "path" sugiere un objeto que ya existe, reemplazará el valor en la ubicación "path" por el valor en la ubicación "from"
•El atributo "path" no puede ser un elemento secundario JSON de la ubicación JSON "from"

Modos admitidos

La característica de actualización parcial de documentos admite los siguientes modos de funcionamiento. Consulte el documento Introducción para obtener ejemplos de código.

  • Revisión de un documento único: puede aplicar revisiones a un único documento en función de su identificador y la clave de partición. Es posible ejecutar varias operaciones de revisión en un único documento. El límite máximo es de 10 operaciones.

  • Revisión de varios documentos: se pueden aplicar revisiones a varios documentos dentro de la misma clave de partición como parte de una transacción. Esta transacción de varios documentos solo se confirma si todas las operaciones se realizan correctamente en el orden en que se describen. Si se produce un error en alguna de las operaciones, se revierte toda la transacción.

  • Actualización condicional: para los modos mencionados anteriormente, también es posible agregar un predicado de filtro similar a SQL (por ejemplo, from c where c.taskNum = 3) de modo que se produzca un error en la operación si no se cumple la condición previa especificada en el predicado.

  • También puede usar las API masivas de los SDK admitidos para ejecutar una o varias operaciones de revisión en varios documentos.

Similitudes y diferencias

Comparemos las similitudes y diferencias entre los modos admitidos.

Comparación entre Add y Set

La operación Set es similar a Add para todos los tipos de datos excepto Array. Una operación Add en cualquier índice (válido) da como resultado la adición de un elemento en el índice especificado y los elementos existentes en la matriz terminan ubicándose tras el elemento existente. Este comportamiento contrasta con la operación Set, que actualiza el elemento existente en el índice especificado.

Comparación entre Add y Replace

La operación Add agrega una propiedad si aún no existe (incluido el tipo de datos Array). Se produce un error en la operación Replace si la propiedad no existe (también se aplica al tipo de datos Array).

Comparación entre Set y Replace

La operación Set agrega una propiedad si aún no existe (excepto si había un valor de Array). Se produce un error en la operación Replace si la propiedad no existe (también se aplica al tipo de datos Array).

Nota

Replace es un buen candidato cuando el usuario espera que algunas de las propiedades estén siempre presentes, y le permite su aserción o aplicación.

Referencia de la API de REST para actualización parcial de documentos

La API de REST de Azure Cosmos DB proporciona acceso mediante programación a recursos de Azure Cosmos DB para crear, consultar y eliminar bases de datos, colecciones de documentos y documentos. Además de ejecutar operaciones de inserción, reemplazo, eliminación, lectura, enumeración y consulta en documentos JSON de una colección, puede usar el método HTTP PATCH para la operación de actualización parcial de documentos. Para más información, consulte Azure Cosmos DB: referencia de la API REST para obtener detalles.

Por ejemplo, esta es la apariencia de la solicitud para una operación set con actualización 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"
    }
  ]
}

Resolución de conflictos de nivel de documento frente a nivel de ruta de acceso

Si la cuenta de Azure Cosmos DB está configurada con varias regiones de escritura, los conflictos y las directivas de resolución de conflictos son aplicables a nivel de documento, siendo la directiva donde la última escritura prevalece (LWW) la que se establece de manera predeterminada para la resolución de conflictos. En el caso de las actualizaciones parciales de documentos, las operaciones de revisión en varias regiones detectan y resuelven conflictos en un nivel de ruta de acceso más granular.

La resolución de conflictos se puede entender mejor con un ejemplo.

Supongamos que tiene el siguiente documento en Azure Cosmos DB:

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

Distintos clientes emiten operaciones de revisión simultáneamente en distintas regiones:

  • atributo Set/level a platinum
  • Remove 67890 desde /phone

Imagen que muestra la resolución de conflictos en operaciones simultáneas de actualización parcial de varias regiones.

Puesto que las solicitudes de revisión se realizaron en rutas de acceso que no entran en conflicto dentro del documento, estas solicitudes se resuelven de forma automática y transparente (a diferencia de la directiva donde la última escritura prevalece a nivel de documento).

El cliente verá el siguiente documento después de la resolución de conflictos:

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

Nota

En caso de que se aplique una revisión simultánea a la misma propiedad de un documento en varias regiones, se aplican las directivas de resolución de conflictos normales.

Fuente de cambios

La fuente de cambios en Azure Cosmos DB escucha un contenedor para ver los cambios y, a continuación, genera los documentos que se cambiaron. Con la fuente de cambios, se ven todas las actualizaciones de documentos, tanto las parciales como las completas. Al procesar elementos de la fuente de cambios, se devuelve el documento completo aunque la actualización fuera resultado de la operación de revisión.

Para más información sobre la fuente de cambios en Azure Cosmos DB, consulte Fuente de cambios en Azure Cosmos DB.

Pasos siguientes