插入或取代實體

發行項
05/04/2024

作業 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

仿真的記憶體服務

當您對模擬記憶體服務提出要求時，請將模擬器主機名和 Azure 數據表記憶體埠指定為 127.0.0.0.1：10002，後面接著模擬記憶體帳戶名稱。

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

記憶體模擬器中的數據表記憶體與 Azure 資料表記憶體有數種方式不同。如需詳細資訊，請參閱記憶體模擬器和 Azure 記憶體服務之間的差異。

URI 參數

您可以在要求 URI 上指定下列額外參數。

參數	描述
`timeout`	選擇性。 `timeout` 參數以秒為單位。如需詳細資訊，請參閱設定數據表記憶體作業的逾時。

要求標頭

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

要求標頭	描述
`Authorization`	必要。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`Date` 或 `x-ms-date`	必要。指定要求的「國際標準時間」(UTC)。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`x-ms-version`	必要。必須設定為 2011-08-18 或更新版本。指定用於這個要求的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`Content-Type`	必要。指定承載的內容類型。可能的值是 `application/atom+xml` 和 `application/json`。如需有效內容類型的詳細資訊，請參閱數據表記憶體作業的承載格式。
`Content-Length`	必要。要求本文的長度。
`x-ms-client-request-id`	選擇性。提供客戶端產生的不透明值，其中包含設定記錄時記錄的 1 kibibyte (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` 。此值最多為 1,024 個可見的 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

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

以下是使用 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，必須指定和 RowKey 系統屬性的值PartitionKey。這些屬性會形成主鍵，而且在數據表內必須是唯一的。

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

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

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

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

另請參閱

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