엔터티 삽입

아티클
08/05/2023

Insert Entity 작업은 새 엔터티를 테이블에 삽입합니다.

요청

다음과 같이 요청을 생성할 Insert Entity 수 있습니다. HTTPS를 사용하는 것이 좋습니다. myaccount를 스토리지 계정의 이름으로 바꾸고 mytable을 테이블 이름으로 바꿉니다.

메서드	요청 URI	HTTP 버전
`POST`	`https://myaccount.table.core.windows.net/mytable`	HTTP/1.1

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

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

메서드	요청 URI	HTTP 버전
`POST`	`http://127.0.0.1:10002/devstoreaccount1/mytable`	HTTP/1.1

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

URI 매개 변수

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

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

요청 헤더

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

요청 헤더	Description
`Authorization`	필수 요소. 권한 부여 체계, 계정 이름 및 서명을 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
`Date` 또는 `x-ms-date`	필수 요소. 요청에 대한 UTC(협정 세계시)를 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
`x-ms-version`	선택 사항입니다. 이 요청에 사용할 작업의 버전을 지정합니다. 자세한 내용은 Azure Storage 서비스에 대한 버전 관리를 참조하세요.
`Content-Type`	필수 요소. 페이로드의 콘텐츠 형식을 지정합니다. 가능한 값은 (2015-12-11 이전 버전만 해당) 및 `application/json`입니다 `application/atom+xml` . 유효한 콘텐츠 형식에 대한 자세한 내용은 Table Storage 작업에 대한 페이로드 형식을 참조하세요.
`Content-Length`	필수 요소. 요청 본문의 길이입니다.
`Accept`	선택 사항입니다. 응답 페이로드의 허용되는 콘텐츠 형식을 지정합니다. 가능한 값은 다음과 같습니다. - `application/atom+xml` (2015-12-11 이전 버전만 해당) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` 자세한 내용은 Table Storage 작업에 대한 페이로드 형식을 참조하세요.
`Prefer`	선택 사항입니다. 페이로드에 삽입된 엔터티를 응답에 포함할지 여부를 지정합니다. 가능한 값은 `return-no-content` 및 `return-content`입니다. 자세한 내용은 삽입 작업에서 응답 에코를 관리하도록 선호 헤더 설정을 참조하세요.
`x-ms-client-request-id`	선택 사항입니다. 로깅이 구성될 때 로그에 기록되는 1키비바이트(KiB) 문자 제한으로 클라이언트에서 생성된 불투명 값을 제공합니다. 이 헤더를 사용하여 클라이언트 쪽 활동과 서버가 수신하는 요청의 상관 관계를 지정하는 것이 좋습니다. 자세한 내용은 Azure Table Storage 모니터링을 참조하세요.

요청 본문

작업은 Insert Entity 엔터티로 OData 삽입할 엔터티(JSON 또는 Atom 피드)를 보냅니다. 자세한 내용은 엔터티 삽입 및 업데이트를 참조하세요.

참고

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

JSON(버전 2013-08-15 이상)

작업에 대한 Insert Entity 샘플 JSON 요청 본문은 다음과 같습니다.

{  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}

Atom 피드(2015-12-11 이전 버전)

다음은 Insert Entity 작업의 예제 Atom 요청 본문입니다.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<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-09-18T23:46:19.3857256Z</updated>  
  <author>  
    <name />  
  </author>  
  <id />  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Mountain View</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:BinaryData m:type="Edm.Binary" m:null="true" />  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</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 상태 코드, 응답 헤더 집합 및 응답 본문이 포함되어 있습니다.

상태 코드

상태 코드는 Prefer 헤더의 값에 따라 달라집니다. Prefer 헤더가 return-no-content로 설정된 경우 작업에 성공할 경우 상태 코드 204(No Content)가 반환됩니다. 헤더가 Prefer 지정되지 않았거나 로 설정된 return-content경우 성공적인 작업은 상태 코드 201(Created)을 반환합니다. 자세한 내용은 삽입 작업에서 응답 에코를 관리하도록 선호 헤더 설정을 참조하세요.

상태 코드에 대한 자세한 내용은 상태 및 오류 코드 및 테이블 서비스 오류 코드를 참조하세요.

응답 헤더

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

응답 헤더	Description
`x-ms-request-id`	만들어진 요청을 고유하게 식별하며 요청 문제 해결에 사용할 수 있습니다. 자세한 내용은 API 작업 문제 해결을 참조하세요.
`x-ms-version`	요청을 실행하는 데 사용되는 Table Storage의 버전을 나타냅니다. 이 헤더는 2009-09-19 버전 이상에 대해 수행된 요청에 대해 반환됩니다.
`Date`	응답이 시작된 시간을 나타내는 UTC 날짜/시간 값입니다. 서비스에서 이 값을 생성합니다.
`ETag`	`ETag` 엔터티에 대한 입니다.
`Preference-Applied`	`Prefer` 요청 헤더가 적용되었는지 여부를 나타냅니다. 응답에 이 헤더가 포함되어 있지 않으면 헤더가 `Prefer` 적용되지 않습니다. 이 헤더가 반환되면 그 값은 `return-content` 또는 `return-no-content` 중 하나가 됩니다. 자세한 내용은 삽입 작업에서 응답 에코를 관리하도록 선호 헤더 설정을 참조하세요.
`Content-Type`	페이로드의 콘텐츠 형식을 나타냅니다. 값은 `Accept` 요청 헤더에 지정된 값에 따라 달라집니다. 가능한 값은 다음과 같습니다. - `application/atom+xml` - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` 콘텐츠 형식에 대한 자세한 내용은 Table Storage 작업에 대한 페이로드 형식을 참조하세요.
`x-ms-client-request-id`	요청 및 해당 응답 문제를 해결하는 데 사용할 수 있습니다. 이 헤더의 값은 요청에 있는 경우 헤더 값 `x-ms-client-request-id` 과 같습니다. 값은 최대 1,024자 표시 ASCII 문자입니다. 헤더가 `x-ms-client-request-id` 요청에 없으면 응답에 표시되지 않습니다.

응답 본문

요청에 return-no-content 값의 Prefer 헤더가 포함된 경우 응답 본문이 반환되지 않습니다. 그렇지 않으면 응답 본문이 엔터티 집합입니다 OData .

참고

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

JSON(버전 2013-08-15 이상)

다음은 각 메타데이터 수준의 예제 JSON 응답입니다.

메타데이터 없음:

{  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":true,  
   "NumberOfOrders":"255"  
}

최소 메타데이터:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255"  
}

전체 메타데이터:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",  
   "odata.type":"myaccount.Customers",  
   "odata.id":" https://myaccount.table.core.windows.net/Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",  
   "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
   "odata.editLink":"Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp@odata.type":"Edm.DateTime",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255"  
}

원자 피드(2015-12-11 이전 버전)

다음은 Insert Entity 작업의 예제 Atom 응답 본문입니다.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<entry xml:base="https://myaccount.table.core.windows.net/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:etag="W/"0x5B168C7B6E589D2"" xmlns="https://www.w3.org/2005/Atom">  
  <id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')</id>  
  <title type="text"></title>  
  <updated>2008-09-18T23:46:19.3857256Z</updated>  
  <author>  
    <name />  
  </author>  
  <link rel="edit" title="mytable" href="mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')" />  
  <category term="myaccount.Tables" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
  <content type="application/xml">  
    <m:properties>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
      <d:Timestamp m:type="Edm.DateTime">2008-09-18T23:46:19.4277424Z</d:Timestamp>  
      <d:Address>Mountain View</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:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
    </m:properties>  
  </content>  
</entry>

권한 부여

계정 소유자는 이 작업을 수행할 수 있습니다. 또한 이 작업을 수행할 수 있는 권한이 있는 공유 액세스 서명이 있는 사용자는 누구나 이 작업을 수행할 수 있습니다.

설명

테이블에 엔터티를 삽입할 때 및 RowKey 시스템 속성의 PartitionKey 값을 지정해야 합니다. 이러한 속성은 기본 키를 구성하며 테이블 내에서 고유해야 합니다.

및 RowKey 값은 PartitionKey 모두 문자열 값이어야 합니다. 각 키 값의 크기는 최대 64KiB입니다. 키 값에 정수 값을 사용하는 경우 정수는 정식으로 정렬되므로 정수 를 고정 너비 문자열로 변환해야 합니다. 예를 들어 값을 1 로 변환하여 0000001적절한 정렬을 보장합니다.

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

Table Storage는 속성에 대한 값을 영구적으로 만들지 null 않습니다. 값을 사용하여 속성을 null 지정하는 것은 요청에서 해당 속성을 생략하는 것과 같습니다.

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

추가 정보

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

엔터티 삽입

요청

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

URI 매개 변수

요청 헤더

요청 본문

JSON(버전 2013-08-15 이상)

Atom 피드(2015-12-11 이전 버전)

응답

상태 코드

응답 헤더

응답 본문

JSON(버전 2013-08-15 이상)

원자 피드(2015-12-11 이전 버전)

권한 부여

설명

추가 정보

추가 리소스