共用方式為


插入或取代實體

作業 Insert Or Replace Entity 會取代現有的實體,或在數據表中不存在時插入新的實體。 因為此作業可以插入或更新實體,所以也稱為 upsert 作業。

要求

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

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

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

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

方法 要求 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 儲存體提出要求
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 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。 這些屬性會形成主鍵,而且在數據表內必須是唯一的。

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

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

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

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

另請參閱

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