Insert Or Replace Entity

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

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

要求

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

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

Method	要求 URI	HTTP バージョン
`PUT`	`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 バージョン
`PUT`	`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 Replace Entity 、エンティティセットとして挿入されるエンティティが OData 送信されます。このエンティティセットには、JSON または Atom フィードを指定できます。詳細については、「エンティティの挿入と更新」を参照してください。

注意

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

[応答]

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

状態コード

操作が正常に終了すると、ステータスコード 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 を使用する要求と応答の例を次に示します。

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必要があります。これらのプロパティは共に主キーを形成し、テーブル内で一意である必要があります。

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

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

要求を承認して送信できるアプリケーションは、エンティティを HTTP PUT 挿入または置換できます。

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

Insert Or Replace Entity

要求

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

URI パラメーター

要求ヘッダー

要求本文

[応答]

状態コード

応答ヘッダー

応答本文

承認

要求と応答の例

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

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

注釈

関連項目

その他のリソース

Insert Or Replace Entity

要求

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

URI パラメーター

要求ヘッダー

要求本文

[応答]

状態コード

応答ヘッダー

応答本文

承認

要求と応答の例

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

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

注釈

関連項目

その他のリソース

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