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

Операция 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 — это рекомендуемый формат полезных данных и единственный формат, поддерживаемый для версии 2015-12-11 и более поздних версий.

JSON (версия 15.08.2013 и более поздняя)

Ниже приведен пример запроса и ответа, в котором используется 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 должны быть строковыми значениями. Каждое значение ключа может иметь размер до 64 КиБ. Если для значения ключа используется целочисленное значение, следует преобразовать целое число в строку фиксированной ширины. Это связано с тем, что они канонически отсортированы. Например, преобразуйте значение 1 в , 0000001 чтобы обеспечить правильную сортировку.

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

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

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

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

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