Insert Entity (Вставка сущности )

Статья
06/27/2023

Операция Insert Entity вставляет новую сущность в таблице.

Запрос

Запрос можно создать Insert Entity следующим образом. Рекомендуется использовать протокол HTTPS. Замените myaccount именем вашей учетной записи хранения, а mytable — именем таблицы.

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

URI эмулированной службы хранилища

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

Ниже приведен пример текста запроса JSON для Insert Entity операции:

{  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}

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

Ниже приведен пример текста запроса Atom для Insert Entity операции.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<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-09-18T23:46:19.3857256Z</updated>  
  <author>  
    <name />  
  </author>  
  <id />  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Mountain View</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:BinaryData m:type="Edm.Binary" m:null="true" />  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</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, набор заголовков ответа и текст ответа.

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

Код состояния зависит от значения заголовка Prefer. Если заголовок Prefer имеет значение return-no-content, то успешная операция возвращает код состояния 204 (No Content). Prefer Если заголовок не указан или для него задано значение return-content, то успешная операция возвращает код состояния 201 (Created). Дополнительные сведения см. в разделе Настройка заголовка Prefer для управления эхом ответа при операциях вставки.

Сведения о кодах состояния см. в разделах Коды состояний и ошибок и Коды ошибок службы таблиц.

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

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

Заголовок ответа	Описание
`x-ms-request-id`	Уникально идентифицирует выполненный запрос и может использоваться для устранения неполадок с запросом. Дополнительные сведения см. в разделе Устранение неполадок с операциями API.
`x-ms-version`	Указывает версию хранилища таблиц, используемую для выполнения запроса. Этот заголовок возвращается для запросов к версии 2009-09-19 и более поздним версиям.
`Date`	Значение даты и времени в формате UTC, указывающее время, когда был инициирован ответ. Служба создает это значение.
`ETag`	Объект `ETag` для сущности.
`Preference-Applied`	Указывает, был ли учтен заголовок запроса `Prefer`. Если ответ не содержит этот заголовок, то заголовок `Prefer` не учитывается. Если этот заголовок возвращен, то он будет иметь значение `return-content` или `return-no-content`. Дополнительные сведения см. в разделе Настройка заголовка Prefer для управления эхом ответа при операциях вставки.
`Content-Type`	Указывает тип содержимого полезных данных. Значение зависит от значения, указанного для заголовка запроса `Accept`. Возможны следующие значения: - `application/atom+xml` - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` Дополнительные сведения о типах контента см. в разделе Формат полезных данных для операций хранилища таблиц.
`x-ms-client-request-id`	Может использоваться для устранения неполадок с запросами и соответствующими ответами. Значение этого заголовка равно значению заголовка `x-ms-client-request-id` , если он присутствует в запросе. Значение равно не более 1024 видимых символов ASCII. Если заголовок `x-ms-client-request-id` отсутствует в запросе, он не будет присутствовать в ответе.

Текст ответа

Если запрос содержит заголовок Prefer со значением return-no-content, то текст ответа возвращен не будет. В противном случае текст ответа является набором сущностей OData .

Примечание

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

Ниже приведен пример ответа JSON для каждого уровня метаданных:

Метаданные отсутствуют.

{  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":true,  
   "NumberOfOrders":"255"  
}

Минимальные метаданные:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255"  
}

Полные метаданные:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",  
   "odata.type":"myaccount.Customers",  
   "odata.id":" https://myaccount.table.core.windows.net/Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",  
   "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
   "odata.editLink":"Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp@odata.type":"Edm.DateTime",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255"  
}

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

Ниже приведен пример текста ответа Atom для операции Insert Entity.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<entry xml:base="https://myaccount.table.core.windows.net/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:etag="W/"0x5B168C7B6E589D2"" xmlns="https://www.w3.org/2005/Atom">  
  <id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')</id>  
  <title type="text"></title>  
  <updated>2008-09-18T23:46:19.3857256Z</updated>  
  <author>  
    <name />  
  </author>  
  <link rel="edit" title="mytable" href="mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')" />  
  <category term="myaccount.Tables" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
  <content type="application/xml">  
    <m:properties>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
      <d:Timestamp m:type="Edm.DateTime">2008-09-18T23:46:19.4277424Z</d:Timestamp>  
      <d:Address>Mountain View</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:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
    </m:properties>  
  </content>  
</entry>

Авторизация

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

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

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

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

Хранилище таблиц не делает null значения свойств постоянными. Указание свойства со значением null эквивалентно пропуску этого свойства в запросе.

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

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

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

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

Insert Entity (Вставка сущности )

Запрос

URI эмулированной службы хранилища

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

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

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

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

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

Ответ

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

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

Текст ответа

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

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

Авторизация

Комментарии

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

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