Table Service 작업에 대한 페이로드 형식

테이블 서비스 REST API는 ATOM 및 JSON을 OData 페이로드 형식으로 지원합니다. ATOM 프로토콜은 모든 버전의 Azure Storage 서비스에 대해 지원되지만 JSON 프로토콜은 버전 2013-08-15 이상에서만 지원됩니다.

• JSON은 권장 페이로드 형식입니다. JSON은 버전 2013-08-15 이상에서 지원됩니다. 버전 2015-12-11 이상에서 JSON을 사용해야 합니다.

• ATOM은 2015-12-11 이전 버전에서 지원됩니다.

JSON 또는 ATOM 형식을 지정하려면 및 Accept 헤더에 Content-Type 적절한 값을 지정합니다(아래 설명). 다음 제약 조건에 유의하세요.

• Content-Type 헤더는 OData 페이로드가 포함된 모든 요청에 필요합니다.

• Accept 헤더가 제공되지 않은 경우 응답의 콘텐츠 형식은 기본적으로 application/atom+xml이 됩니다.

• OData 데이터 서비스 버전이 3.0으로 설정된 경우 $format URI 매개 변수를 지정하면 Accept 요청 헤더에 지정된 값이 재정의됩니다. OData 서비스 버전에 대한 자세한 내용은 OData 데이터 서비스 버전 헤더 설정을 참조하세요.

페이로드 형식을 지정하려면 아래의 표에 따라 Content-Type 및 Accept 요청 헤더를 설정하세요.

JSON 형식(application/json)(버전 2013-08-15 이상)

OData는 위에서 설명한 ATOM 형식과 유사한 이러한 이름-값 쌍에 대한 일반적인 규칙을 정의하여 JSON 형식을 확장합니다. OData는 ID, 형식 및 링크와 같은 제어 정보에 대한 정식 주석의 집합을 정의합니다. JSON 형식에 대한 자세한 내용은 JSON 소개를 참조하세요.

OData의 JSON 형식을 사용하는 경우의 주요 이점은 페이로드의 예측 가능한 부분을 생략하여 페이로드 크기를 줄일 수 있다는 것입니다. 수신하는 쪽에서 이 데이터를 다시 구성하기 위해 식을 사용하여 누락된 링크, 형식 정보 및 제어 데이터를 컴퓨팅합니다. 페이로드에서 생략되는 항목을 제어하기 위해 Accept 헤더의 일부로 지정할 수 있는 세 가지 수준이 있습니다.

• application/json;odata=nometadata

• application/json;odata=minimalmetadata

• application/json;odata=fullmetadata

다음과 같은 ODATA 주석이 Azure 테이블 서비스에서 지원됩니다.

• odata.metadata: 컬렉션, 엔터티, 기본 값 또는 서비스 문서에 대한 메타데이터 URL입니다.

• odata.id: 일반적으로 리소스의 URL인 엔터티 ID입니다.

• odata.editlink: 엔터티를 업데이트할 수 있고 odata.id가 엔터티를 편집하는 데 사용할 수 있는 URL을 나타내지 않는 경우 엔터티를 편집/업데이트하는 데 사용되는 링크입니다.

• odata.type: 포함하는 개체의 형식 이름입니다.

• odata.etag: 엔터티의 ETag입니다.

• PropertyName@odata.type사용자 지정 속성의 경우: 대상 속성의 형식 이름입니다.

• PropertyName@odata.type시스템 속성(예:PrimaryKey , RowKey및 Timestamp 속성)의 경우: 대상 속성의 형식 이름입니다.

각 수준에 포함된 정보는 다음 표에 요약되어 있습니다.

JSON 피드의 속성 형식

odata.type 주석은 OData JSON 형식에서 공개 속성의 형식을 확인하는 데 사용됩니다. 이 주석은 아래의 조건이 모두 충족되는 경우 존재합니다.

• JSON 제어 수준이 JSON 형식 섹션에 설명된 대로 odata=minimalmetadata 또는 odata=fullmetadata로 설정되어 있습니다.

• 속성이 사용자 지정 속성입니다. Azure 테이블의 경우 PartitionKey, RowKey 및 Timestamp 속성만 시스템 속성이고 이러한 속성의 형식 정보는 $metadata에서 선언됩니다. 이러한 속성의 형식 주석은 제어 수준이 odata=fullmetadata로 설정된 경우에만 존재합니다. 자세한 내용은 Table Service 데이터 모델 이해를 참조하세요.

• 속성의 형식은 아래의 표에 요약되어 있는 형식 검색 추론을 통해 확인할 수 없습니다.

Table Service는 속성에 대한 값을 유지 null 하지 않습니다. 엔터티 null 를 작성할 때 odata.type 주석을 사용하거나 사용하지 않고 값을 지정할 수 있으며, 값이 있는 null 모든 속성은 요청에 해당 속성이 포함되지 않은 것처럼 처리됩니다. Null 속성 값은 엔터티를 쿼리할 때 반환되지 않습니다.

Edm.Double의 경우 및 -Infinity 값 NaNInfinity 은 형식String을 사용하여 JSON에 표시되며 odata.type 주석이 필요합니다. Table Service는 음수 버전의 NaN를 지원하지 않으며 JSON 형식에서는 양수 및 음수 0을 구분하지 않습니다(로 0.0처리됨-0.0).

다음 JSON 엔터티는 8가지 속성 형식의 예를 각각 제공합니다.

{  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey",  
  "DateTimeProperty@odata.type":"Edm.DateTime",  
  "DateTimeProperty":"2013-08-02T17:37:43.9004348Z",  
  "BoolProperty":false,  
  "BinaryProperty@odata.type":"Edm.Binary",  
  "BinaryProperty":"AQIDBA==",  
  "DoubleProperty":1234.1234,  
  "GuidProperty@odata.type":"Edm.Guid",  
  "GuidProperty":"4185404a-5818-48c3-b9be-f217df0dba6f",  
  "Int32Property":1234,  
  "Int64Property@odata.type":"Edm.Int64",  
  "Int64Property":"123456789012",  
  "StringProperty":"test"  
}  

PartitionKey 및 RowKey는 모든 테이블 행이 정의해야 하는 시스템 속성이므로 이러한 속성의 형식 주석은 엔터티에 나타나지 않습니다. 이러한 속성은 Edm.String 형식으로 미리 정의됩니다. 그러나 다른 속성은 사용자 지정 속성이므로 위의 표에서 지원되는 기본 형식 중 하나에 해당하는 형식 정보를 포함합니다.

예제:

다음 샘플 OData 항목은 Azure Table Storage에 엔터티를 삽입하기 위한 요청으로 전송된 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,  
  "NumOfOrders@odata.type":"Edm.Int64",  
  "NumOfOrders":"255",  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey1",  
}  

클라이언트가 Azure Table Storage에서 엔터티 집합을 쿼리하면 서비스는 JSON 페이로드로 응답합니다(쿼리 작업에 대한 자세한 내용은 엔터티 쿼리 참조). 피드에는 메타데이터 없음, 최소 메타데이터 또는 전체 메타데이터의 세 가지 정보 수준 중 하나가 포함될 수 있습니다. 다음 예에서는 각 수준의 정보를 보여 줍니다.

메타데이터 없음:

{  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}  

최소 메타데이터:

{  
  "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers,  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}  

전체 메타데이터:

{  
  "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
  "value":[  
    {  
      "odata.type":"myaccount.Customers",  
      "odata.id":"https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer03',RowKey='Name')",  
      "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
      "odata.editLink":"Customers(PartitionKey='Customer03',RowKey='Name')",  
      "PartitionKey":"Customer03,  
      "RowKey":"Name",  
      "Timestamp@odata.type":"Edm.DateTime",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}  

OData JSON 형식에 대한 자세한 내용은 [MS-ODATAJSON]: OData 프로토콜 JSON 형식 표준 지원 문서와 함께 OData JSON 형식버전 4.0 사양을 참조하세요.

Atom 형식(application/atom+xml)(2015-12-11 이전 버전만 해당)

Atom 은 피드라고 하는 관련 정보의 컬렉션을 설명하는 XML 기반 문서 형식 입니다. 피드는 많은 항목으로 구성되어 있습니다. AtomPub 는 항목을 나타내는 리소스를 쉽게 분류, 그룹화, 편집 및 검색할 수 있도록 항목 및 피드에 대한 추가 형식 구문을 정의합니다. 그러나 Atom은 구조화된 데이터를 피드로 인코딩하는 방법을 정의하지 않으므로 OData는 OData 를 기반으로 하는 서비스별로 구조화된 콘텐츠를 전송할 수 있도록 Atom 피드에서 구조적 데이터를 나타내는 규칙 집합을 정의합니다.

예를 들어 다음 샘플 OData 항목은 REST API를 사용하여 Azure Table Storage에 엔터티를 삽입하는 요청을 통해 전송된 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 />  
  <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>  

클라이언트가 Table Storage에서 엔터티 집합을 쿼리하면 서비스는 Atom 항목의 컬렉션인 Atom 피드로 응답합니다(쿼리 작업에 대한 자세한 내용은 엔터티 쿼리 참조).

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<feed 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" xmlns="https://www.w3.org/2005/Atom">  
  <title type="text">Customers</title>  
  <id>https://myaccount.table.core.windows.net/Customers</id>  
  <link rel="self" title="Customers" href="Customers" />  
  <entry m:etag="W/"0x5B168C7B6E589D2"">  
  <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer03',RowKey='Name')</id>  
    <title type="text"></title>  
    <updated>2008-10-01T15:26:13Z</updated>  
    <author>  
      <name />  
    </author>  
    <link rel="edit" title="Customers" href="Customers (PartitionKey='Customer03',RowKey='Name')" />  
    <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
    <content type="application/xml">  
      <m:properties>  
        <d:PartitionKey>Customer03</d:PartitionKey>  
        <d:RowKey>Name</d:RowKey>        <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
      </m:properties>  
    </content>  
  </entry>  
</feed>  

Atom 피드의 속성 형식

속성 데이터 형식은 OData 프로토콜 사양에 의해 정의됩니다. 이 사양으로 정의된 일부 데이터 형식은 테이블 서비스에서 지원되지 않습니다. 지원되는 데이터 형식 및 CLR(공용 언어 런타임) 형식에 매핑하는 방법에 대한 자세한 내용은 Table Service 데이터 모델 이해를 참조하세요.

속성은 명시적인 데이터 형식을 사용하거나 사용하지 않고 지정될 수 있습니다. 형식을 생략하면 속성이 데이터 형식 Edm.String으로 자동으로 만들어집니다.

명시적 형식을 사용해서 속성이 생성된 경우 엔터티를 반환하는 쿼리에 ATOM 피드 내의 형식이 포함되므로 필요에 따라 기존 속성의 형식을 확인할 수 있습니다. 속성에 따라 필터링되는 쿼리를 생성할 때는 해당 속성의 형식을 아는 것이 중요합니다. 자세한 내용은 테이블 및 엔터티 쿼리를 참조하세요.

속성의 경우 Double , INF및 -INF 값NaN은 각각 숫자, 양수 무한대 및 음의 무한대를 나타내기 위해 Atom에서 사용됩니다. 및 양식 Infinity-Infinity 도 허용됩니다. Table Service는 음수 NaN버전의 을 지원하지 않습니다. Atom 형식에서는 양수와 음수 0을 구분합니다.

참고 항목

OData 데이터 서비스 버전 헤더 설정
Azure Storage 서비스에 대한 버전 관리
테이블 서비스 개념