Частичное обновление документа в Azure Cosmos DB

Компонент частичного обновления документов Azure Cosmos DB, также известный как API исправлений, предоставляет удобный способ изменения документа в контейнере. В настоящее время для обновления документа клиент должен прочитать его, выполнить проверки оптимистического параллелизма (при необходимости), обновить документ локально, а затем отправить его по проводу в виде вызова API замены документа в целом.

Функция частичного обновления документов значительно улучшает этот интерфейс. Клиент может отправлять только измененные свойства и поля в документе, не выполняя операции полной замены. Основные преимущества этой функции:

• Повышение производительности разработчиков. Предоставляет удобный API для удобства использования и возможности условного обновления документа.
• Улучшения производительности: исключение лишних циклов ЦП на стороне клиента, сокращение сквозной задержки и уменьшение пропускной способности сети.
• Записи в нескольких регионах: поддерживает автоматическое и прозрачное разрешение конфликтов с частичными обновлениями на дискретных путях в одном документе.

Замечание

Операция частичного обновления документа основана на RFC JSON Patch. Имена свойств в путях должны экранировать символы ~ и / как ~0 и ~1 соответственно.

Пример целевого документа JSON:

{
  "id": "eeeeeeee-4444-5555-6666-ffffffffffff",
  "name": "R-410 Road Bicycle",
  "price": 455.95,
  "inventory": {
    "quantity": 15
  },
  "used": false,
  "categoryId": "road-bikes",
  "tags": ["r-series"]
}

Документ с исправлением 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" }
]

Итоговый документ JSON:

{
  "id": "eeeeeeee-4444-5555-6666-ffffffffffff",
  "name": "R-410 Road Bicycle",
  "price": 355.45,
  "inventory": {
    "quantity": 25,
    "color": "silver"
  },
  "categoryId": "road-bikes",
  "tags": ["r-series", "featured-bikes"]
}

Поддерживаемые операции

В этой таблице перечислены операции, поддерживаемые этой функцией.

Замечание

Целевой путь относится к расположению в документе JSON.

Тип операции	Description
Прибавить	Add выполняет одно из следующих действий в зависимости от целевого пути: • Если целевой путь указывает элемент, который не существует, он добавлен. • Если целевой путь указывает элемент, который уже существует, его значение заменяется. • Если целевой путь является допустимым индексом массива, новый элемент вставляется в массив по указанному индексу. Это перемещает существующие элементы после нового элемента. • Если указанный индекс равен длине массива, он добавляет элемент в массив. Вместо того, чтобы указывать индекс, также можно использовать символ -. Он также приводит к добавлению элемента в массив. Примечание. Указание индекса, превышающего длину массива, приводит к ошибке.
Установить	Set аналогичен Add, за исключением когда речь идет о типе данных массива. Если целевой путь является допустимым индексом массива, то существующий элемент в этом индексе обновляется.
заменить	Replace аналогичен Set, за исключением использования строгой семантики только для замены. Если целевой путь указывает элемент или массив, который не существует, он приводит к ошибке.
Remove	Remove выполняет одно из следующих действий в зависимости от целевого пути: • Если целевой путь указывает элемент, который не существует, он приводит к ошибке. • Если целевой путь указывает элемент, который уже существует, он удаляется. • Если целевой путь является индексом массива, он удаляется и все элементы над указанным индексом сдвигаются обратно в одну позицию. Примечание. Указание индекса, равного или больше длины массива, приведет к ошибке.
Increment	Этот оператор увеличивает поле на указанное значение. Он может принимать как положительные, так и отрицательные значения. Если поле не существует, оно создает поле и задает его указанному значению.
Move	Этот оператор удаляет значение в указанном расположении и добавляет его в целевое расположение. Объект операции должен содержать поле "from", которое является строкой, содержащей значение указателя JSON, ссылающегося на расположение в целевом документе, откуда нужно переместить значение. Расположение исходное должно существовать для успешного выполнения операции. Если расположение path предлагает объект, который не существует, он создает объект и задает значение, равное значению в расположении from. •Если путь указывает на объект, который уже существует, то значение в местоположении "path" заменяется значением из местоположения "from" •Атрибут "path" не может быть дочерним элементом JSON-объекта "from".

Поддерживаемые режимы

Функция частичного обновления документа поддерживает перечисленные ниже режимы работы. Ознакомьтесь с документом "Начало работы " для примеров кода.

• Исправление одного документа. вы можете внести исправление в отдельный документ с учетом его идентификатора и ключа раздела. Можно выполнить несколько операций исправления в одном документе. Максимальное ограничение — 10 операций.

• Исправление для нескольких документов: несколько документов в одном ключе секции могут быть исправлены как часть транзакции. Эта транзакция с несколькими документами фиксируется только в случае успеха всех операций в порядке, в котором они описаны. Но при сбое любой отдельной операции выполняется откат всей транзакции.

• Условное обновление. Для упомянутых ранее режимов также можно добавить предикат фильтра, подобный SQL (например, ), чтобы операция завершилась ошибкой, from c where c.taskNum = 3если предварительные условия, указанные в предикате, не удовлетворены.

• Вы также можете использовать массовые API поддерживаемых SDK для выполнения одной или нескольких операций исправления для нескольких документов.

Сходства и различия

Давайте сравним сходства и различия между поддерживаемыми режимами.

Add и Set

Операция Set аналогична Add всем типам данных, кроме Array. Операция Add с любым (допустимым) индексом приводит к добавлению элемента по указанному индексу и все существующие элементы массива в конечном итоге сдвигаются после существующего элемента. Это поведение отличается от Set операции, которая обновляет существующий элемент по указанному индексу.

Добавить или Заменить

Операция Add добавляет свойство, если оно еще не существует (включая Array тип данных). Replace операция завершается ошибкой, если свойство не существует (это также применимо к типу данных Array).

Установить и Заменить

Операция Set добавляет свойство, если оно еще не существует (за исключением случаев, когда был объект Array). Replace операция завершается ошибкой, если свойство не существует (это также применимо к типу данных Array).

Замечание

Replace является хорошим кандидатом в тех случаях, когда пользователь ожидает, что некоторые свойства всегда будут присутствовать, и это позволяет гарантировать их наличие.

Руководство по API REST для частичного обновления документа

REST API Azure Cosmos DB обеспечивает программный доступ к ресурсам Azure Cosmos DB для создания, запроса и удаления баз данных, коллекций документов и документов. В дополнение к выполнению операций вставки, замены, удаления, чтения, нумерации и запроса в документах JSON в коллекции можно использовать метод HTTP PATCH для частичного обновления документа. Дополнительные сведения см. в справке по REST API Azure Cosmos DB.

Например, вот как выглядит запрос для set операции с частичным обновлением документа.

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

Разрешение конфликтов на уровне документа и конфликтов на уровне пути

Если учетная запись Azure Cosmos DB настроена с несколькими регионами записи, политики разрешения конфликтов применяются на уровне документа, при этом политика "Последняя запись выигрывает" (LWW) является политикой разрешения конфликтов по умолчанию. При частичном обновлении документа патч-операции в нескольких регионах выявляют и устраняют конфликты на более детализированном уровне путей.

Разрешение конфликтов можно лучше понять с помощью примера.

Предположим, что в Azure Cosmos DB имеется следующий документ:

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

Разные клиенты выполняют операции исправления одновременно в разных регионах:

• Задать (Set) для атрибута /level значение "platinum"
• Remove 67890 из /phone

Так как запросы на исправления были сделаны к неконфликтным путям в документе, эти запросы разрешаются автоматически и прозрачно (в отличие от стратегии «Последний записавший победил» на уровне документа).

Клиент видит следующий документ после разрешения конфликтов:

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

Замечание

Если одно и то же свойство документа одновременно исправляется в нескольких регионах, применяются обычные политики разрешения конфликтов.

Лента изменений

Поток изменений в Azure Cosmos DB отслеживает изменения в контейнере и затем выводит документы, которые были изменены. С помощью канала изменений можно просмотреть все обновления документов, включая частичные и полные. При обработке элементов из канала изменений возвращается полный документ, даже если обновление было результатом операции исправления.

Дополнительные сведения о канале изменений в Azure Cosmos DB см. в разделе Канал изменений в Azure Cosmos DB.

Дальнейшие действия

• Начало работы с Azure Cosmos DB: частичное обновление документа
• Часто задаваемые вопросы о частичном обновлении документов