插入實體

  • 發行項

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 值都必須是字串值。 每個索引鍵值的大小最多可達 64 KiB。 如果您使用索引鍵值的整數值，則應該將整數轉換成固定寬度字串，因為這些字串是以音調方式排序。 例如，將 值 10000001 轉換成 ，以確保進行適當的排序。

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

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

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

另請參閱

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