엔터티 삽입 또는 병합

아티클
07/13/2024

작업은 Insert Or Merge Entity 기존 엔터티를 업데이트하거나 테이블에 없는 경우 새 엔터티를 삽입합니다. 이 작업은 엔터티를 삽입하거나 업데이트할 수 있으므로 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

에뮬레이트된 스토리지 서비스

에뮬레이트된 스토리지 서비스에 대해 요청할 때 에뮬레이터 호스트 이름 및 Azure Table Storage 포트를 127.0.0.1:10002로 지정한 다음 에뮬레이트된 스토리지 계정 이름을 지정합니다.

메서드	요청 URI	HTTP 버전
`MERGE`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

스토리지 에뮬레이터의 Table Storage는 여러 가지 방법으로 Azure Table Storage와 다릅니다. 자세한 내용은 Storage 에뮬레이터와 Azure Storage 서비스 간의 차이점을 참조하세요.

URI 매개 변수

요청 URI에 다음 추가 매개 변수를 지정할 수 있습니다.

매개 변수	Description
`timeout`	선택 사항입니다. `timeout` 매개 변수는 초 단위로 표시됩니다. 자세한 내용은 Table Storage 작업에 대한 시간 제한 설정을 참조하세요.

요청 헤더

다음 표에서는 필수 요청 헤더와 선택적 요청 헤더에 대해 설명합니다.

요청 헤더	Description
`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키비바이트(KiB) 문자 제한을 사용하여 클라이언트에서 생성된 불투명 값을 제공합니다. 이 헤더를 사용하여 클라이언트 쪽 활동과 서버가 수신하는 요청의 상관 관계를 지정하는 것이 좋습니다. 자세한 내용은 Azure Table Storage 모니터링을 참조하세요.

요청 본문

작업은 Insert Or Merge Entity 엔터티 집합으로 삽입할 엔터티를 OData 보냅니다. 이 엔터티 집합은 Atom 또는 JSON 페이로드일 수 있습니다. 자세한 내용은 엔터티 삽입 및 업데이트를 참조하세요.

참고

JSON은 권장 페이로드 형식이며 버전 2015-12-11 이상에서 지원되는 유일한 형식입니다.

응답

응답에는 HTTP 상태 코드 및 응답 헤더 집합이 포함되어 있습니다.

상태 코드

작업에 성공하면 상태 코드 204(No Content)가 반환됩니다. 상태 코드에 대한 자세한 내용은 상태 및 오류 코드 및 Table Storage 오류 코드를 참조하세요.

응답 헤더

응답에는 다음과 같은 헤더가 포함됩니다. 응답에는 추가 표준 HTTP 헤더도 포함될 수 있습니다. 모든 표준 헤더는 HTTP/1.1 프로토콜 사양을 준수합니다.

응답 헤더	Description
`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

원자 피드(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자일 수 있습니다. 키 값에 정수 값을 사용하는 경우 정수 를 고정 너비 문자열로 변환해야 합니다. 이는 정식으로 정렬되기 때문입니다. 예를 들어 값을 10000001 로 변환하여 적절한 정렬을 보장합니다.

속성을 명시적으로 입력하려면 Atom 피드의 속성 정의 내에서 특성을 설정 m:type 하여 적절한 OData 형식을 지정합니다. 속성 입력에 대한 자세한 내용은 엔터티 삽입 및 업데이트를 참조하세요.

요청을 승인하고 보낼 수 있는 모든 애플리케이션은 HTTP MERGE 엔터티를 삽입하거나 업데이트할 수 있습니다.

일괄 처리 upsert 작업을 수행하는 방법에 대한 자세한 내용은 엔터티 그룹 트랜잭션 수행을 참조하세요.

추가 정보

Azure Storage에 대한 요청 권한 부여
OData 데이터 서비스 버전 헤더 설정
엔터티 삽입 및 업데이트
상태 및 오류 코드
Table Storage 오류 코드

다음을 통해 공유