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

Статья
08/15/2024

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

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

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

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

Примечание.

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

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

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

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

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

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

Примечание.

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

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

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

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

Исправление одного документа. вы можете внести исправление в отдельный документ с учетом его идентификатора и ключа раздела. Можно выполнить несколько операций исправления в одном документе. Максимальное ограничение — 10 операций.
Исправление нескольких документов. Несколько документов в одном ключей раздела можно исправить в качестве части транзакции. Эта транзакция с несколькими документами фиксируется только в том порядке, в котором они описаны. Но при сбое любой отдельной операции выполняется откат всей транзакции.
Условное обновление: для указанных выше режимов также можно добавить предикат фильтра, подобный SQL (например, ), так что операция завершается ошибкой, from c where c.taskNum = 3если предварительные условия, указанные в предикате, не удовлетворены.
Вы также можете использовать массовые API поддерживаемых SDK для выполнения одной или нескольких операций исправления для нескольких документов.

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

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

Add и Set

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

Add и Replace

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

Set и Replace

Операция 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

Так как запросы на исправление были сделаны к неконфликционным путям в документе, эти запросы разрешаются автоматически и прозрачно (в отличие от last Writer Wins на уровне документа).

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

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

Примечание.

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

Канал изменений

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

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

Следующие шаги

Узнайте, как начать работу с частичным обновлением документов с помощью .NET, Java и Node
Часто задаваемые вопросы по частичному обновлению документов

Поделиться через

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

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

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

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

Add и Set

Add и Replace

Set и Replace

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

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

Канал изменений

Следующие шаги

Обратная связь

Дополнительные ресурсы