エクスポート (0) 印刷
すべて展開

Insert Or Merge Entity (REST API)

更新日: 2014年11月

Insert Or Merge Entity 操作は、既存のエンティティを更新し、テーブルにエンティティがない場合は新しいエンティティを挿入します。この操作は、エンティティを挿入 (insert) または更新 (update) できるため、"upsert" 操作とも呼ばれます。

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

  • myaccount は使用するストレージ アカウントの名前で置き換えます。

  • mytable は使用するテーブルの名前で置き換えます。

  • myPartitionKey および myRowKey は、更新するエンティティのパーティション キーおよび行キーで置き換えます。

 

メソッド 要求 URI HTTP バージョン

MERGE

https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey'

HTTP/1.1

エミューレートされたストレージ サービスに対する要求では、エミュレーターのホスト名とテーブル サービス ポートを 127.0.0.1:10002 と指定し、その後にエミューレートされたストレージ アカウント名を指定します。

 

メソッド 要求 URI HTTP バージョン

MERGE

http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')

HTTP/1.1

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

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

 

要求ヘッダー 説明

Authorization

必須。認証スキーム、アカウント名、および署名を指定します。詳細については、「Azure ストレージ サービスの認証」を参照してください。

Date またはx-ms-date

必須。要求の世界協定時刻 (UTC) を指定します。詳細については、「Azure ストレージ サービスの認証」を参照してください。

x-ms-version

必須。2011-08-18 以降に設定する必要があります。この要求に使用する操作のバージョンを指定します。詳細については、「Windows Azure の BLOB サービス、キュー サービス、およびテーブル サービスのバージョン管理」を参照してください。

Content-Type

必須。ペイロードのコンテンツの種類を指定します。指定できる値は application/atom+xml および application/json です。

有効なコンテンツの種類の詳細については、「テーブル サービス操作のペイロード形式」を参照してください。

Content-Length

必須。要求本文の長さ。

x-ms-client-request-id

省略可能。Storage Analytics Logging が有効な場合に解析ログに記録される、クライアントで生成された非透過の値を 1 KB の文字制限付きで提供します。クライアント側のアクティビティとサーバーが受け取る要求を相互に関連付けるには、このヘッダーを使用することを強くお勧めします。詳細については、「Storage Analytics Logging について」および「Windows Azure のログ: ログを使用した、ストレージ要求の追跡」を参照してください。

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

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

操作が正常に実行されると、状態コード 204 (No Content) が返されます。

ステータス コードの詳細については、「ステータス コードとエラー コード」および「テーブル サービスのエラー コード」を参照してください。

応答には次のヘッダーが含まれます。応答に追加の標準 HTTP ヘッダーが含まれる場合もあります。標準ヘッダーはすべて、HTTP/1.1 プロトコル仕様に準拠しています。

 

応答ヘッダー 説明

ETag

エンティティの ETag。

x-ms-request-id

このヘッダーは要求を一意に識別するので、要求のトラブルシューティングに使用できます。詳細については、「API 操作のトラブルシューティング」を参照してください。

x-ms-version

要求の実行に使用するテーブル サービスのバージョンを示します。このヘッダーはバージョン 2009-09-19 以降で行った要求に対して返されます。

Date

サービスによって生成される、応答の開始時刻を示す UTC 日付/時刻値。

なし。

この操作を実行できるのは、アカウント所有者と、この操作を実行するアクセス許可を持つ共有アクセス署名を使用する任意のユーザーです。

Atom: 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="http://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>
      <d:Timestamp m:type="Edm.DateTime">2013-11-12T18:09:37.9557508Z</d:Timestamp>
    </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

JSON: 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

Insert Or Merge Entity 操作は MERGE 動詞を使用します。また、2011-08-18 バージョン以降を使用して呼び出す必要があります。加えて、If-Match ヘッダーは使用されません。以上の点で、この操作は Update Entity 操作とは区別されます。ただし、要求本文はどちらの操作も同じです。

Insert Or Merge Entity 操作を使用してエンティティがマージされた場合、以前のエンティティからのプロパティは、その要求でプロパティを定義または追加していなければ維持されます。null 値に設定されているプロパティも維持されます。

Insert or Merge Entity 操作を呼び出す場合、PartitionKey および RowKey システム プロパティの値を指定する必要があります。これらのプロパティがプライマリ キーを構成します。これらのプロパティはテーブル内で一意である必要があります。

PartitionKey 値と RowKey 値の両方が文字列値である必要があります。各キー値のサイズは最大 64 KB です。キー値は正規の順序で並べ替えられるため、キー値に整数値を使用している場合は、整数から固定幅文字列に変換する必要があります。たとえば、値 10000001 に変換して、正しく並べ替えられるようにする必要があります。

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

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

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

関連項目

表示:
© 2014 Microsoft