插入實體

發行項
05/04/2024

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` (2015-12-11 之前的版本僅) - `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 kibibyte (KiB) 字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。如需詳細資訊，請參閱監視 Azure 資料表記憶體。

要求本文

作業 Insert Entity 會傳送要插入為 OData 實體的實體，也就是 JSON 或 Atom 摘要。如需詳細資訊，請參閱插入和更新實體。

注意

JSON 是建議的承載格式，也是 2015-12-11 版和更新版本唯一支援的格式。

JSON (2013-08-15 版和更新版本)

以下是作業的 Insert Entity 範例 JSON 要求本文：

{  
   "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 摘要 (2015-12-11 之前的版本)

以下是作業的 Insert Entity 範例 Atom 要求本文。

<?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` 。此值最多為 1,024 個可見的 ASCII 字元。 `x-ms-client-request-id`如果要求中沒有標頭，則不會出現在回應中。

回應本文

如果要求包含值為 return-no-content 的 Prefer 標頭，則不會傳回回應主體。否則，回應主體是 OData 實體集。

注意

JSON 是建議的承載格式，而且是 2015-12-11 版和更新版本唯一支援的格式。

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 摘要 (2015-12-11 之前的版本)

以下是 Insert Entity 作業的範例 Atom 回應主體。

<?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>

授權

帳戶擁有者可以執行這項作業。此外，具有共用存取簽章且有權執行這項作業的任何人都可以這麼做。

備註

當您將實體插入資料表時，您必須指定和 RowKey 系統屬性的值PartitionKey。這些屬性一起形成主鍵，而且在數據表中必須是唯一的。

PartitionKey和 RowKey 值都必須是字串值。 PartitionKey 和 RowKey 值的大小最多可達 1024 個字元。如果您使用索引鍵值的整數值，則應該將整數轉換成固定寬度字串，因為它們是以音調方式排序。例如，將值10000001轉換成，以確保進行適當的排序。

若要明確輸入屬性，請在 Atom 摘要中的屬性定義內設定m:type屬性，以指定適當的OData數據類型。如需輸入屬性的詳細資訊，請參閱插入和更新實體。

數據表記憶體不會讓屬性的值持續存在 null 。使用值指定屬性 null 相當於省略要求中的該屬性。

如需執行批次插入作業的相關信息，請參閱執行實體群組交易。

另請參閱

授權對 Azure 記憶體的要求
 設定 OData 資料服務版本標頭
 插入和更新實體
 狀態和錯誤碼
 數據表記憶體錯誤碼

插入實體

要求

模擬記憶體服務 URI

URI 參數

要求標頭

要求本文

JSON (2013-08-15 版和更新版本)

Atom 摘要 (2015-12-11 之前的版本)

回應

狀態碼

回應標頭

回應本文

JSON (2013-08-15 版和更新版本)

Atom 摘要 (2015-12-11 之前的版本)

授權

備註

另請參閱

其他資源