Вставка или слияние сущностей

Статья
06/27/2023

Операция Insert Or Merge Entity обновляет существующую сущность или вставляет новую сущность, если она не существует в таблице. Так как эта операция может вставлять или обновлять сущность, она также называется операцией upsert .

Запрос

Запрос можно создать Insert Or Merge Entity следующим образом. Рекомендуется использовать протокол HTTPS. Замените следующие значения собственными:

myaccount — именем учетной записи службы.
mytable — именем таблицы.
myPartitionKey и myRowKey с именем ключа секции и ключа строки для обновляемой сущности.

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Эмулируемая служба хранилища

При выполнении запроса к эмулированной службе хранилища укажите имя узла эмулятора и порт хранилища таблиц Azure как 127.0.0.1:10002, а затем имя эмулированной учетной записи хранения.

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

Хранилище таблиц в эмуляторе хранения отличается от хранилища таблиц Azure несколькими способами. Дополнительные сведения см. в статье Различия между эмулятором хранения и службами хранилища Azure.

Параметры универсального кода ресурса (URI)

В URI запроса можно указать следующий дополнительный параметр.

Параметр	Описание
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для операций хранилища таблиц.

Заголовки запросов

В следующей таблице перечислены обязательные и необязательные заголовки запросов.

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Обязательный. Должно быть установлено значение 18.08.2011 или более поздней версии. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`Content-Type`	Обязательный. Указывает тип содержимого для полезных данных. Возможные значения: `application/atom+xml` и `application/json`. Дополнительные сведения о допустимых типах контента см. в разделе Формат полезных данных для операций хранилища таблиц.
`Content-Length`	Обязательный. Длина текста запроса.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Мониторинг хранилища таблиц Azure.

Текст запроса

Операция Insert Or Merge Entity отправляет сущность для вставки в OData виде набора сущностей. Этот набор сущностей может быть полезными данными Atom или JSON. Дополнительные сведения см. в разделе Вставка и обновление сущностей.

Примечание

JSON — это рекомендуемый формат полезных данных, который поддерживается только для версии 2015-12-11 и более поздних версий.

Ответ

Ответ включает код состояния HTTP и набор заголовков ответа.

Код состояния

Успешная операция возвращает код состояния 204 (No Content). Сведения о кодах состояния см. в разделах Коды состояний и ошибок и Коды ошибок хранилища таблиц.

Заголовки ответов

Ответ содержит следующие заголовки. Ответ также может содержать дополнительные стандартные заголовки HTTP. Все стандартные заголовки соответствуют спецификации протокола HTTP/1.1.

Заголовок ответа	Описание
`ETag`	Объект `ETag` для сущности.
`x-ms-request-id`	Уникально идентифицирует выполненный запрос и может использоваться для устранения неполадок с запросом. Дополнительные сведения см. в разделе Устранение неполадок с операциями API.
`x-ms-version`	Указывает версию хранилища таблиц, используемую для выполнения запроса. Этот заголовок возвращается для запросов к версии 2009-09-19 и более поздним версиям.
`Date`	Значение даты и времени в формате UTC, указывающее время, когда был инициирован ответ. Служба создает это значение.
`x-ms-client-request-id`	Может использоваться для устранения неполадок с запросами и соответствующими ответами. Значение этого заголовка равно значению заголовка `x-ms-client-request-id` , если он присутствует в запросе. Значение равно не более 1024 видимых символов ASCII. Если заголовок `x-ms-client-request-id` отсутствует в запросе, он не будет присутствовать в ответе.

Текст ответа

Нет.

Авторизация

Владелец учетной записи может выполнить эту операцию. Кроме того, это может сделать любой пользователь с подписанным URL-адресом, имеющий разрешение на выполнение этой операции.

Пример запроса и ответа

В следующих примерах показаны примеры запросов, использующих веб-каналы JSON и Atom.

Примечание

JSON (версия 2013-08-15 и более поздние версии)

Ниже приведен пример запроса и ответа, в котором используется JSON.

MERGE https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

Запрос отправляется со следующими заголовками:

x-ms-version: 2013-08-15  
Content-Type: application/json  
x-ms-date: Tue, 30 Aug 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

Запрос отправляется со следующим текстом JSON:

{  
   "Address":"Santa Clara",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode@odata.type":"Edm.Guid",  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince@odata.type":"Edm.DateTime",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":false,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}

После отправки запроса возвращается следующий ответ:

  
HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 30 Aug 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Веб-канал Atom (версии до 11.12.2015)

Ниже приведен пример запроса и ответа, в котором используется Atom.

MERGE https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

Запрос отправляется со следующими заголовками:

x-ms-version: 2013-08-15  
Accept: application/atom+xml,application/xml  
Accept-Charset: UTF-8  
Content-Type: application/atom+xml  
x-ms-date: Tue, 12 Nov 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx

Запрос отправляется со следующим текстом XML:

<?xml version="1.0" encoding="utf-8"?>  
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="https://www.w3.org/2005/Atom">  
  <title />  
  <updated>2013-11-12T18:09:37.168836Z</updated>  
  <author>  
    <name />  
  </author>  
<id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey')</id>  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Santa Clara</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00Z</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">false</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
    </m:properties>  
  </content>  
</entry>

После отправки запроса возвращается следующий ответ:

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 12 Nov 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Операция Insert Or Merge Entity использует команду MERGE . Операцию необходимо вызвать с помощью версии 2011-08-18 или более поздней. Кроме того, эта операция не использует If-Match заголовок . Эти атрибуты отличают данную операцию от операции Update Entity, хотя текст запроса одинаков для обеих операций.

Если вы используете Insert Or Merge Entity операцию для слияния сущности, все свойства из предыдущей сущности сохраняются, если запрос не определяет и не включает их. Свойства со значением null также сохраняются.

При вызове Insert or Merge Entity операции необходимо указать значения для системных PartitionKey свойств и RowKey . Вместе эти свойства образуют первичный ключ и должны быть уникальными в пределах таблицы.

PartitionKey Значения и RowKey должны быть строковыми значениями. PartitionKey Значения и RowKey могут содержать до 1024 символов. Если для значения ключа используется целочисленное значение, следует преобразовать целое число в строку фиксированной ширины. Это связано с тем, что они канонически отсортированы. Например, преобразуйте значение 1 в , 0000001 чтобы обеспечить правильную сортировку.

Чтобы явно ввести свойство, укажите соответствующий OData тип, задав m:type атрибут в определении свойства в веб-канале Atom. Дополнительные сведения о вводе свойств см. в разделе Вставка и обновление сущностей.

Любое приложение, которое может авторизовать и отправить запрос, HTTP MERGE может вставлять или обновлять сущность.

Сведения о выполнении операций пакетного upsert см. в разделе Выполнение транзакций группы сущностей.

См. также раздел

Авторизация запросов к службе хранилища Azure
Настройка заголовков версии службы данных OData
Вставка и обновление сущностей
Коды состояний и ошибок
Коды ошибок хранилища таблиц

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