插入或合併實體

作業 Insert Or Merge Entity 會更新現有的實體,如果資料表中不存在,則插入新的實體。 因為此作業可以插入或更新實體,所以也稱為 upsert 作業。

要求

您可以建構 Insert Or Merge Entity 要求,如下所示。 建議使用 HTTPS。 請以您自己的值取代下列值:

  • myaccount以您的儲存體帳戶名稱取代

  • mytable以您的資料表名稱取代

  • myPartitionKeymyRowKey 具有要更新之實體的資料分割索引鍵和資料列索引鍵名稱

方法 要求 URI HTTP 版本
MERGE https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey') HTTP/1.1

模擬的儲存體服務

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

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

儲存體模擬器中的資料表儲存體與 Azure 資料表儲存體有數種方式不同。 如需詳細資訊,請參閱 儲存體模擬器和 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 kibibyte (KiB) 字元限制。 強烈建議您使用此標頭,將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊,請參閱 監視 Azure 資料表儲存體

要求本文

作業 Insert Or Merge Entity 會傳送要插入為實體集的 OData 實體。 此實體集可以是 Atom 或 JSON 承載。 如需詳細資訊,請參閱 插入和更新實體

注意

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

回應

回應包括 HTTP 狀態碼和一組回應標頭。

狀態碼

成功的作業會傳回狀態碼 204 (No Content)。 如需狀態碼的相關資訊,請參閱 狀態和錯誤碼,以及 資料表儲存體錯誤碼

回應標頭

回應包含下列標頭。 回應也可以包含額外的標準 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 。 此值最多為 1,024 個可見的 ASCII 字元。 x-ms-client-request-id如果要求中沒有標頭,它就不會出現在回應中。

回應本文

無。

授權

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

範例要求與回應

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

注意

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

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

以下是使用 JSON 的範例要求和回應。

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

以下是使用 Atom 的範例要求和回應:

MERGE 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='myrowkey')</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 Merge EntityMERGE 使用動詞命令。 您必須使用 2011-08-18 版本或更新版本來呼叫作業。 此外,此作業不會使用 If-Match 標頭。 這些屬性可區分這項作業與 Update Entity 作業 (雖然這兩項作業的要求主體皆相同)。

如果您使用 Insert Or Merge Entity 作業來合併實體,如果要求未定義或包含這些屬性,則會保留來自先前實體的任何屬性。 也會保留具有 null 值的屬性。

當您呼叫作業時 Insert or Merge Entity ,必須指定 和 RowKey 系統屬性的值 PartitionKey 。 這些屬性會形成主鍵,而且在資料表內必須是唯一的。

PartitionKeyRowKey 值都必須是字串值。 每個索引鍵值的大小上限為 64 KiB。 如果您使用索引鍵值的整數值,則應該將整數轉換成固定寬度字串。 這是因為它們會以音調方式排序。 例如,將 值 10000001 轉換成 ,以確保正確排序。

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

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

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

另請參閱

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