엔터티 쿼리

아티클
06/27/2023

Query Entities 작업은 테이블에서 요소를 쿼리하며 $filter 및 $select 옵션을 포함합니다.

요청

쿼리 옵션을 사용하는 요청의 $select 경우 버전 2011-08-18 이상을 사용해야 합니다. 또한 DataServiceVersion 및 MaxDataServiceVersion 헤더는 2.0으로 설정해야 합니다.

프로젝션을 사용하려면 버전 2013-08-15 이상을 사용하여 요청을 수행해야 합니다. DataServiceVersion 및 MaxDataServiceVersion 헤더는 로 3.0설정해야 합니다. 자세한 내용은 OData 데이터 서비스 버전 헤더 설정을 참조하세요.

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

메서드	요청 URI	HTTP 버전
`GET`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `https://myaccount.table.core.windows.net/mytable()?$filter=<query-expression>&$select=<comma-separated-property-names>`	HTTP/1.1

쿼리할 엔터티 집합의 주소는 요청 URI에서 다양한 양식을 사용할 수 있습니다. 자세한 내용은 쿼리 테이블 및 엔터티를 참조하세요.

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

에뮬레이트된 스토리지 서비스에 대해 요청할 때 에뮬레이터의 호스트 이름과 테이블 서비스의 포트를 로 127.0.0.1:10002지정합니다. 에뮬레이트된 스토리지 계정의 이름으로 해당 정보를 따릅니다.

메서드	요청 URI	HTTP 버전
`GET`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `http://127.0.0.1:10002/devstoreaccount1/mytable()?$filter=<query-expression>?$select=<comma-separated-property-names>`	HTTP/1.1

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

URI 매개 변수

이 Query Entities 작업은 OData 프로토콜 사양 에서 정의하는 쿼리 옵션을 지원합니다.

요청 헤더

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

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

요청 본문

없음

샘플 요청

Request Syntax:  
GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-12-11  
x-ms-date: Mon, 27 Jun 2016 15:25:14 GMT  
Authorization: SharedKeyLite myaccount:<some key>  
Accept: application/json;odata=nometadata  
Accept-Charset: UTF-8  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

응답

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

상태 코드

작업에 성공하면 상태 코드 200(정상)이 반환됩니다.

상태 코드에 대한 자세한 내용은 상태 및 오류 코드 및 Table Storage 오류 코드를 참조하세요.

응답 헤더

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

응답 헤더	Description
`x-ms-continuation-NextPartitionKey` `x-ms-continuation-NextRowKey`	다음을 나타냅니다. - 반환할 엔터티 수가 1,000을 초과합니다. - 서버 시간 제한 간격이 초과되었습니다. - 쿼리가 여러 서버에 분산된 데이터를 반환하는 경우 서버 경계에 도달합니다. 연속 토큰 사용에 대한 자세한 내용은 쿼리 시간 제한 및 페이지 매김을 참조하세요.
`x-ms-request-id`	만들어진 요청을 고유하게 식별합니다. 이를 사용하여 요청 문제를 해결할 수 있습니다. 자세한 내용은 API 작업 문제 해결을 참조하세요.
`x-ms-version`	요청을 실행하는 데 사용된 Table Storage의 버전을 나타냅니다. 이 헤더는 2009-09-19 버전 이상에 대해 수행된 요청에 대해 반환됩니다.
`Date`	서비스가 응답을 보낸 시간을 나타내는 UTC 날짜/시간 값입니다.
`Content-Type`	페이로드의 콘텐츠 형식을 나타냅니다. 이 헤더의 값은 `Accept` 요청 헤더의 값에 따라 달라집니다. 가능한 값은 다음과 같습니다. - `application/atom+xml` (2015-12-11 이전 버전만 해당) - `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` 요청에 없는 경우 이 헤더는 응답에 존재하지 않습니다.

샘플 응답

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Content-Type: application/json  
x-ms-request-id: 87f178c0-44fe-4123-a4c1-96c8fa6d9654  
Date: Mon, 27 Jun 2016 15:25:14 GMT  
x-ms-version: 2015-12-11  
Connection: close

응답 본문

작업은 Query Entities 테이블의 엔터티 목록을 OData 엔터티 집합으로 반환합니다. 엔터티 목록은 요청의 헤더에 Accept 따라 JSON 형식 또는 Atom 피드입니다.

참고

페이로드 형식으로 JSON을 사용하는 것이 좋습니다. 버전 2015-12-11 이상에서 유일하게 지원되는 형식입니다.

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

고객 테이블에 대한 작업에 대한 Query Entities 샘플 요청 URI는 다음과 같습니다.

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

다음은 메타데이터가 없는 JSON의 응답 페이로드입니다.

{  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

다음은 최소한의 메타데이터를 사용하는 JSON의 응답 페이로드입니다.

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

전체 메타데이터가 포함된 JSON의 응답 페이로드는 다음과 같습니다.

{  
   "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=Customer',RowKey='Name')",  
         "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
         "odata.editLink":"Customers(PartitionKey=Customer',RowKey='Name')",  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp@odata.type":"Edm.DateTime",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

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

고객 테이블에 대한 작업에 대한 Query Entities 샘플 요청 URI는 다음과 같습니다.

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

작업에 대한 샘플 Atom 응답은 Query Entities 다음과 같습니다.

<?xml version="1.0" encoding="UTF-8"?>  
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://myaccount.table.core.windows.net">  
   <id>https://myaccount.table.core.windows.net/Customers</id>  
   <title type="text">Customers</title>  
   <updated>2013-08-22T00:50:32Z</updated>  
   <link rel="self" title="Customers" href="Customers" />  
   <entry m:etag="W/"0x5B168C7B6E589D2"">  
      <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer',RowKey='Name')</id>  
      <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
      <link rel="edit" title="Customers" href="Customers(PartitionKey='Customer',RowKey='Name')" />  
      <title />  
      <updated>2013-08-22T00:50:32Z</updated>  
      <author>  
         <name />  
      </author>  
      <content type="application/xml">  
         <m:properties>  
            <d:PartitionKey>Customer</d:PartitionKey>  
            <d:RowKey>Name</d:RowKey>  
            <d:Timestamp m:type="Edm.DateTime">2013-08-22T00:20:16.3134645Z</d:Timestamp>  
            <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
         </m:properties>  
      </content>  
   </entry>  
</feed>

권한 부여

이 작업은 계정 소유자 및 이 작업을 수행할 수 있는 권한이 있는 공유 액세스 서명을 갖는 모든 사용자가 수행할 수 있습니다.

설명

Table Storage에 대한 쿼리는 한 번에 최대 1,000개의 엔터티를 반환할 수 있으며 최대 5초 동안 실행할 수 있습니다. 응답에는 다음 경우 연속 토큰 집합이 포함된 사용자 지정 헤더가 포함됩니다.

결과 세트에 포함된 엔터티가 1,000개를 초과합니다.
쿼리가 5초 이내에 완료되지 않았습니다.
쿼리가 파티션 경계를 교차 합니다.

연속 토큰을 사용하여 다음 데이터 페이지에 대한 후속 요청을 생성할 수 있습니다. 연속 토큰에 대한 자세한 내용은 쿼리 시간 제한 및 페이지 매김을 참조하세요.

참고

연속 토큰을 포함하는 후속 요청을 수행할 때는 요청에 원래 URI를 전달해야 합니다. 예를 들어 원래 요청의 일부로 , $select또는 $top 쿼리 옵션을 지정$filter한 경우 후속 요청에 해당 옵션을 포함합니다. 그렇지 않으면 후속 요청이 예기치 않은 결과를 반환할 수 있습니다.

$top 이 경우 쿼리 옵션은 페이지당 최대 결과 수를 지정합니다. 전체 응답 집합의 최대 결과 수를 지정하지 않습니다.

자세한 내용은 쿼리 테이블 및 엔터티를 참조하세요.

쿼리 옵션을 사용하는 프로젝션 요청의 $select 경우 버전은 2011-08-18 이상이어야 합니다. 반환된 속성의 최대 수는 255개입니다. 응답 본문에는 속성이 반환된 엔터티의 일부가 아니더라도 모든 프로젝트된 속성이 포함됩니다.

예를 들어 프로젝션된 엔터티에 포함되지 않는 속성이 요청에 포함된 경우 누락된 속성에 Null 특성이 표시됩니다. 앞의 샘플 응답 본문에는 프로젝팅된 엔터티의 일부가 아닌 속성이 포함 Address 됩니다. 따라서 속성 값은 null <d:Address m:null="true" />입니다.

쿼리 예약 및 처리 요청에 할당된 총 시간은 30초입니다. 이 합계에는 쿼리 실행에 대한 5초가 포함됩니다.

쿼리 식의 오른쪽은 상수여야 합니다. 식의 오른쪽에 있는 속성을 참조할 수 없습니다. 쿼리 식 생성에 대한 자세한 내용은 쿼리 테이블 및 엔터티를 참조하세요.

쿼리 식에는 값을 포함 null 할 수 없습니다. 쿼리 문자열에서 사용하는 경우 다음 문자를 인코딩해야 합니다.

슬래시(/)
물음표(?)
콜론(:)
At 기호(@)
앰퍼샌드 (&)
등호(=)
더하기 기호(+)
쉼표(,)
달러 기호($)

HTTP GET 요청을 승인하고 보낼 수 있는 모든 애플리케이션은 테이블의 엔터티를 쿼리할 수 있습니다.

LINQ를 통해 Table Storage에 대해 지원되는 쿼리 작업에 대한 자세한 내용은 Table Storage에 대해 지원되는 쿼리 연산자 및 Table Storage에 대한 LINQ 쿼리 작성을 참조하세요.

추가 정보

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