插入或取代實體

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

模擬儲存體服務

對模擬儲存體服務提出要求時,請將模擬器主機名稱和表格服務通訊埠指定為 127.0.0.1:10002,後面接著模擬儲存體帳戶名稱。

方法 要求 URI HTTP 版本
PUT http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey') HTTP/1.1

儲存體模擬器中的表格服務與 Azure™ 表格服務有一些不同之處。 如需詳細資訊,請參閱儲存體 Emulator 和 Azure 儲存體服務之間的差異

URI 參數

您可以在要求的 URI 中指定下列其他參數。

參數 描述
timeout 選擇性。 timeout 參數以秒為單位。 如需詳細資訊,請參閱 設定表格服務作業的超時

要求標頭

下表描述必要的和選用的要求標頭。

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊,請參閱授權 Azure 儲存體的要求
Datex-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊,請參閱授權 Azure 儲存體的要求
x-ms-version 必要項,必須設為 2011-08-18 或更新版本。 指定用於這個要求的作業版本。 如需詳細資訊,請參閱Azure 儲存體服務的版本控制
Content-Type 必要。 指定承載的內容類型。 可能的值是 application/atom+xmlapplication/json

如需有效內容類型的詳細資訊,請參閱 表格服務作業的裝載格式
Content-Length 必要。 要求本文的長度。
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值,具有1個 KiB 字元限制,當啟用儲存體分析記錄時,記錄在分析記錄中。 強烈建議使用此標頭來將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊,請參閱關於儲存體分析記錄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 標頭不存在於要求中,則回應中不會出現此標頭。

回應本文

無。

授權

帳戶擁有者及使用共用存取簽章並有權執行這項作業的任何人,都可以執行這項作業。

範例要求和回應

下列範例顯示使用 JSON 和 Atom 摘要的範例要求。

注意

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

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

以下是使用 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  

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

以下是使用 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 作業時,您必須指定 PartitionKeyRowKey 系統屬性的值。 這些值會共同形成主索引鍵,此主索引鍵在資料表中必須是唯一的。

PartitionKey和值都 RowKey 必須是字串值,每個索引鍵值的大小最多可達 64 KiB。 如果您使用整數值做為索引鍵值,由於整數值不是以標準方式排序,因此您應該將整數轉換為固定寬度的字串。 例如,您應該將值 1 轉換為 0000001,以確保適當的排序。

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

任何可以授權和傳送 HTTP PUT 要求的應用程式都可以插入或取代實體。

如需執行批次 upsert 作業的詳細資訊,請參閱 執行實體群組交易

另請參閱

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