Insert Or Merge Entity

[アーティクル]
06/27/2023

操作は Insert Or Merge Entity 、既存のエンティティを更新するか、テーブルに存在しない場合は新しいエンティティを挿入します。この操作はエンティティを挿入または更新できるため、 アップサート 操作とも呼ばれます。

要求

要求は Insert Or Merge Entity 次のように構築できます。 HTTPS が推奨されます。次の値は固有の値に置き換えてください。

myaccount は使用するストレージアカウントの名前で置き換えます。
mytable は使用するテーブルの名前で置き換えます。
myPartitionKey および myRowKey は、更新するエンティティのパーティションキーと行キーの名前を使用します

Method	要求 URI	HTTP バージョン
`MERGE`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

エミュレートされたストレージサービス

エミュレートされたストレージサービスに対して要求を行う場合は、エミュレーターのホスト名と Azure Table Storage ポートを 127.0.0.1:10002 として指定し、その後にエミュレートされたストレージアカウント名を指定します。

Method	要求 URI	HTTP バージョン
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

ストレージエミュレーターの Table Storage は、いくつかの点で Azure Table Storage とは異なります。詳細については、「ストレージエミュレーターと Azure Storage サービスの違い」を参照してください。

URI パラメーター

要求 URI には、次の追加パラメーターを指定できます。

パラメーター	説明
`timeout`	省略可能。 `timeout` パラメーターは、秒単位で表されます。詳細については、「 Table Storage 操作のタイムアウトの設定」を参照してください。

要求ヘッダー

必須要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。

要求ヘッダー	説明
`Authorization`	必須。承認スキーム、アカウント名、署名を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`Date` または `x-ms-date`	必須。要求に対して協定世界時 (UTC) を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`x-ms-version`	必須。 2011-08-18 以降に設定する必要があります。この要求に使用する操作のバージョンを指定します。詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
`Content-Type`	必須。ペイロードのコンテンツタイプを指定します。設定可能な値は `application/atom+xml` および `application/json` です。有効なコンテンツタイプの詳細については、「 Table Storage 操作のペイロード形式」を参照してください。
`Content-Length`	必須。要求本文の長さです。
`x-ms-client-request-id`	省略可能。ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。詳細については、「 Azure Table Storage の監視」を参照してください。

要求本文

操作により Insert Or Merge Entity 、エンティティセットとして挿入されるエンティティが OData 送信されます。このエンティティセットには、Atom または JSON ペイロードを指定できます。詳細については、「エンティティの挿入と更新」を参照してください。

注意

JSON は推奨されるペイロード形式であり、バージョン 2015-12-11 以降でサポートされている唯一の形式です。

Response

応答には、HTTP 状態コードおよび一連の応答ヘッダーが含まれています。

status code

操作が正常に実行されると、状態コード 204 (No Content) が返されます。状態コードの詳細については、「状態とエラーコード」および「Table Storage のエラーコード」を参照してください。

応答ヘッダー

応答には次のヘッダーが含まれます。応答には、追加の標準 HTTP ヘッダーを含めることもできます。すべての標準ヘッダーは、HTTP/1.1 プロトコル仕様に準拠しています。

応答ヘッダー	説明
`ETag`	`ETag`エンティティの。
`x-ms-request-id`	行われた要求を一意に識別し、要求のトラブルシューティングに使用できます。詳細については、「 API 操作のトラブルシューティング」を参照してください。
`x-ms-version`	要求の実行に使用される Table Storage のバージョンを示します。このヘッダーはバージョン 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 Entity 動詞を使用します MERGE 。 2011-08-18 バージョン以降を使用して操作を呼び出す必要があります。さらに、この操作ではヘッダーは If-Match 使用されません。以上の点で、この操作は Update Entity 操作とは区別されます。ただし、要求本文はどちらの操作も同じです。

操作を Insert Or Merge Entity 使用してエンティティをマージする場合、要求でエンティティが定義または含まれていない場合、前のエンティティのすべてのプロパティが保持されます。値を null 持つプロパティも保持されます。

操作を呼び出すときはInsert or Merge Entity、および RowKey システムプロパティの値を指定するPartitionKey必要があります。これらのプロパティは一緒に主キーを形成し、テーブル内で一意である必要があります。

と RowKey の両方の値はPartitionKey文字列値である必要があります。 PartitionKey および RowKey の値のサイズは最大 1024 文字です。キー値に整数値を使用している場合は、整数を固定幅の文字列に変換する必要があります。これは、それらが正規に並べ替えられているためです。たとえば、適切な並べ替えを行うために、値 1 をに 0000001 変換します。

プロパティを明示的に入力するには、Atom フィードのプロパティ定義内で属性をm:type設定して、適切なOData型を指定します。プロパティの入力の詳細については、「エンティティの挿入と更新」を参照してください。

要求を承認および送信できるアプリケーションは、エンティティを HTTP MERGE 挿入または更新できます。

バッチアップサート操作の実行については、「エンティティグループトランザクションの実行」を参照してください。

こちらもご覧ください

Azure Storage への要求を承認する
 OData データサービスのバージョンヘッダーの設定
 エンティティの挿入と更新
 状態コードとエラーコード
 Table Storage のエラーコード

次の方法で共有

Insert Or Merge Entity

要求

エミュレートされたストレージサービス

URI パラメーター

要求ヘッダー

要求本文

Response

status code

応答ヘッダー

応答本文

承認

要求と応答の例

JSON (バージョン 2013-08-15 以降)

Atom フィード (2015-12-11 より前のバージョン)

注釈

こちらもご覧ください

その他のリソース

次の方法で共有

Insert Or Merge Entity

要求

エミュレートされたストレージ サービス

URI パラメーター

要求ヘッダー

要求本文

Response

status code

応答ヘッダー

応答本文

承認

要求と応答の例

JSON (バージョン 2013-08-15 以降)

Atom フィード (2015-12-11 より前のバージョン)

注釈

こちらもご覧ください

その他のリソース

エミュレートされたストレージサービス