Вставка или замена сущности

Статья
06/27/2023

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

Запрос

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

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

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

Служба эмулированного хранилища

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

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`PUT`	`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 Replace Entity отправляет сущность для вставки в виде набора сущностей OData . Этот набор сущностей может быть либо каналом JSON, либо каналом Atom. Дополнительные сведения см. в статье Вставка и обновление сущностей.

Примечание

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

Ответ

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

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

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

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

Ответ содержит следующие заголовки. Ответ также может содержать дополнительные стандартные заголовки 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 (версия 15.08.2013 и более поздняя)

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

PUT 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.

PUT 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='myrowkey1')</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 Replace Entity не использует If-Match заголовок . Эту операцию необходимо вызвать с помощью версии 2011-08-18 или более поздней. Эти атрибуты отличают эту операцию от операции Обновления сущности .

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

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

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

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

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

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

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

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

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