Blob 콘텐츠 쿼리

Query Blob Contents 작업은 Blob의 내용에 간단한 SQL(구조적 쿼리 언어) 문을 적용하고 쿼리된 데이터의 하위 집합만 반환합니다. 를 호출 Query Blob Contents 하여 버전 또는 스냅샷 내용을 쿼리할 수도 있습니다.

요청

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

POST 메서드 요청 URI HTTP 버전
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query&snapshot=<DateTime>

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query&versionid=<DateTime>
HTTP/1.0

HTTP/1.1

URI 매개 변수

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

매개 변수 Description
snapshot 선택 사항입니다. 스냅샷 매개 변수는 불투명 DateTime 값입니다. 있는 경우 쿼리할 Blob 스냅샷 지정합니다. Blob 스냅샷 작업에 대한 자세한 내용은 Blob의 스냅샷 만들기를 참조하세요.
versionid 선택 사항, 버전 2019-12-12 이상. versionid 매개 변수는 불투명 DateTime 값입니다. 있는 경우 검색할 Blob의 버전을 지정합니다.
timeout 선택 사항입니다. timeout 매개 변수는 초 단위로 표시됩니다. 자세한 내용은 Blob Storage 작업에 대한 시간 제한 설정을 참조하세요.

요청 헤더

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

요청 헤더 Description
Authorization 필수 사항입니다. 인증 체계, 계정 이름 및 서명을 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
Date 또는 x-ms-date 필수 사항입니다. 요청에 대한 UTC(협정 세계시)를 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
x-ms-version 인증된 모든 요청의 경우 필수이고, 익명 요청의 경우에는 선택 사항입니다. 이 요청에 사용할 작업의 버전을 지정합니다. 자세한 내용은 Azure Storage 서비스에 대한 버전 관리를 참조하세요.
Content-Type 필수 사항입니다. 이 헤더의 값은 이어야 application/xml; charset=UTF-8합니다.
x-ms-lease-id:<ID> 선택 사항입니다. 이 헤더가 지정되었으면 다음 조건이 모두 충족될 경우에만 작업이 수행됩니다.

- Blob의 임대가 현재 활성화되어 있습니다.
- 요청에 지정된 임대 ID가 Blob의 임대 ID와 일치합니다.

이 헤더가 지정되었고 이들 조건이 모두 충족되지 않으면 요청이 실패하고 Query Blob Contents 작업이 실패하며 상태 코드 412(전제 조건 실패)가 표시됩니다.
Origin 선택 사항입니다. 요청을 실행한 원본을 지정합니다. 이 헤더가 있으면 응답에 CORS(원본 간 리소스 공유) 헤더가 생성됩니다.
x-ms-client-request-id 선택 사항입니다. 로깅이 구성될 때 로그에 기록되는 1키비바이트(KiB) 문자 제한으로 클라이언트에서 생성된 불투명 값을 제공합니다. 이 헤더를 사용하여 클라이언트 쪽 활동과 서버가 수신하는 요청의 상관 관계를 지정하는 것이 좋습니다.

또한 이 작업은 지정된 조건이 충족되는 경우에만 조건부 헤더를 사용하여 Blob 콘텐츠를 쿼리하도록 지원합니다. 자세한 내용은 Blob Storage 작업에 대한 조건부 헤더 지정을 참조하세요.

요청 본문

이 버전의 Query Blob Contents 요청 본문은 다음 XML 형식을 사용합니다.

<?xml version="1.0" encoding="utf-8"?>  
<QueryRequest>
  <QueryType>String</QueryType>
  <Expression>String</Expression>
  <InputSerialization>
    <Format>
      <Type>String</Type>
          <DelimitedTextConfiguration>
            <ColumnSeparator>String</ColumnSeparator>
            <FieldQuote>String</FieldQuote>
            <RecordSeparator>String</RecordSeparator>
            <EscapeChar>String</EscapeChar>
            <HasHeaders>Boolean</HasHeaders>
          </DelimitedTextConfiguration>
          <JsonTextConfiguration>
            <RecordSeparator>String</RecordSeparator>
          </JsonTextConfiguration>
    </Format>
  </InputSerialization>
  <OutputSerialization>
    <Format>
      <Type>String</Type>
      <DelimitedTextConfiguration>
        <ColumnSeparator>String</ColumnSeparator >
        <FieldQuote>String</FieldQuote >
        <RecordSeparator>String</RecordSeparator>
        <EscapeChar>String</EscapeChar>
        <HasHeaders>Boolean</HasHeaders>
      </DelimitedTextConfiguration>
      <JsonTextConfiguration>
        <RecordSeparator>String</RecordSeparator>
      </JsonTextConfiguration>
      <ArrowConfiguration>
        <Schema>
            <Field>
                <Type>String</Type>
                <Name>String</Name>
            </Field>
            <Field>
                <Type>String</Type>
            </Field>
                .
                .
                .
            <Field>
                <Type>String</Type>
                <Precision>Integer</Precision>
                <Scale>Integer</Scale>
            </Field>
        </Schema>
      </ArrowConfiguration>
    </Format>
  </OutputSerialization>
</QueryRequest>

다음 표에서는 요청 본문의 요소에 대해 설명합니다.

요소 이름 Description
QueryRequest 필수 사항입니다. 쿼리 요청 설정 집합을 그룹화합니다.
QueryType 필수 사항입니다. 제공된 쿼리 식의 형식을 나타냅니다. 현재 버전에 유효한 값은 뿐입니다 SQL.
Expression 필수 사항입니다. SQL의 쿼리 식을 나타냅니다. 쿼리 식의 최대 크기는 256KiB입니다. 식 구문에 대한 자세한 내용은 쿼리 가속: SQL 언어 참조를 참조하세요.
InputSerialization 선택 사항입니다. Blob 콘텐츠의 입력 serialization과 관련된 설정을 그룹화합니다. 지정하지 않으면 구분된 텍스트 구성이 사용됩니다.
Format InputSerialization를 지정하는 경우 필요합니다. Blob 데이터 형식과 관련된 설정을 그룹화합니다.
Type InputSerialization를 지정하는 경우 필요합니다. 형식 형식을 나타냅니다. 유효한 값은 delimited, csvjson입니다.
DelimitedTextConfiguration 선택 사항입니다. Blob이 구분된 텍스트로 서식이 지정된 경우 Blob 데이터를 해석하는 데 사용되는 설정을 그룹화합니다.
ColumnSeparator 선택 사항입니다. 열을 구분하는 데 사용되는 문자열을 나타냅니다.
FieldQuote 선택 사항입니다. 특정 필드를 인용하는 데 사용되는 문자열을 나타냅니다.
RecordSeparator 선택 사항입니다. 레코드를 구분하는 데 사용되는 문자열을 나타냅니다.
EscapeChar 선택 사항입니다. 이스케이프 문자로 사용되는 문자열을 나타냅니다.
HasHeaders 선택 사항입니다. 데이터에 헤더가 있는지 여부를 나타내는 부울을 지정합니다.
JsonTextConfiguration 선택 사항입니다. Blob이 JSON 형식인 경우 Blob 데이터를 해석하는 데 사용되는 설정을 그룹화합니다.
RecordSeparator 선택 사항입니다. 레코드를 구분하는 데 사용되는 문자열을 나타냅니다.
OutputSerialization 선택 사항입니다. 응답에서 반환된 Blob의 필터링된 콘텐츠의 serialization 형식을 나타냅니다. 지정하지 않으면 구분된 텍스트 구성이 사용됩니다.
Format OutputSerialization를 지정하는 경우 필요합니다. 반환된 응답의 형식과 관련된 설정을 그룹화합니다.
Type OutputSerialization를 지정하는 경우 필요합니다. 형식 형식을 나타냅니다. 유효한 값은 delimited, csv, jsonarrow입니다.
DelimitedTextConfiguration 선택 사항입니다. 응답의 서식을 구분된 텍스트로 포맷해야 하는 경우 응답의 서식을 지정하는 데 사용되는 설정을 그룹화합니다.
ColumnSeparator 선택 사항입니다. 열을 구분하는 데 사용되는 문자열을 나타냅니다.
FieldQuote 선택 사항입니다. 특정 필드를 인용하는 데 사용되는 문자열을 나타냅니다.
RecordSeparator 선택 사항입니다. 레코드를 구분하는 데 사용되는 문자열을 나타냅니다.
EscapeChar 선택 사항입니다. 이스케이프 문자로 사용되는 문자열을 나타냅니다.
HasHeaders 선택 사항입니다. 데이터에 헤더가 있는지 여부를 나타내는 부울을 지정합니다.
JsonTextConfiguration 선택 사항입니다. 응답의 형식을 JSON으로 지정해야 하는 경우 응답의 서식을 지정하는 데 사용되는 설정을 그룹화합니다.
RecordSeparator 선택 사항입니다. 레코드를 구분하는 데 사용되는 문자열을 나타냅니다.
ArrowConfiguration 선택 사항입니다. 응답이 화살표 형식이어야 하는 경우 응답의 서식을 지정하는 데 사용되는 설정을 그룹화합니다.
Schema ArrowConfiguration를 지정하는 경우 필요합니다. 반환된 화살표 응답의 스키마와 관련된 설정을 그룹화합니다.
Field 선택 사항입니다. 특정 필드에 대한 설정을 그룹화합니다.
Type Field를 지정하는 경우 필요합니다. 필드 형식을 나타냅니다. 유효한 값은 Int, Float, DecimalBool입니다.
Precision 선택 사항입니다. 필드의 전체 자릿수를 나타냅니다.
Scale 선택 사항입니다. 필드의 배율을 나타냅니다.

응답

응답에는 HTTP 상태 코드, 응답 헤더 집합 및 응답 본문이 포함되어 있습니다. 응답 본문은 Avro 이진 형식입니다. 응답 콘텐츠 길이를 알 수 되므로 응답은 청크 인코딩으로 스트리밍됩니다.

상태 코드

쿼리 요청이 잘 구성되고 권한이 부여되면 작업은 상태 코드 202(수락됨)를 반환합니다. 응답 스트리밍 중에 발생한 오류 또는 진행률 메시지는 응답 본문의 일부로 반환됩니다.

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

응답 헤더

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

구문 Description
Last-Modified Blob이 마지막으로 수정된 날짜/시간을 나타냅니다. 날짜 형식은 RFC 1123을 따릅니다.

blob의 메타데이터 또는 속성에 대한 업데이트를 포함하여 Blob을 수정하는 모든 작업은 수행할 경우 blob의 마지막 수정 시간이 변경됩니다.
Content-Type 결과가 반환될 형식을 지정합니다. 현재 이 값은 입니다 avro/binary.
ETag 조건부로 작업을 수행하는 데 사용할 수 있는 값을 포함합니다. 자세한 내용은 Blob Storage 작업에 대한 조건부 헤더 지정을 참조하세요. 요청 버전이 2011-08-18 이상인 ETag 경우 값은 따옴표로 표시됩니다.
Content-Encoding 요청 헤더에 대해 지정된 Content-Encoding 값을 반환합니다.
Content-Language 요청 헤더에 대해 지정된 Content-Language 값을 반환합니다.
Cache-Control 이 헤더가 이전에 Blob에 대해 지정된 경우 반환됩니다.
Content-Disposition 버전 2013-08-15 이상에 대한 요청에 대해 반환됩니다. 이 헤더는 x-ms-blob-content-disposition 헤더에 대해 지정된 값을 반환합니다.

Content-Disposition 응답 헤더 필드는 응답 페이로드를 처리하는 방법에 대한 추가 정보를 전달합니다. 응답 헤더 필드를 사용하여 추가 메타데이터를 연결할 수도 있습니다. 예를 들어 응답 헤더 필드가 로 attachment설정된 경우 사용자 에이전트는 응답을 표시해서는 안 됩니다. 대신 지정된 Blob 이름이 아닌 파일 이름을 사용하여 다른 이름으로 저장 대화 상자를 표시해야 합니다.
x-ms-blob-type: <BlockBlob> blob의 유형을 반환합니다.
x-ms-request-id 만들어진 요청을 고유하게 식별합니다. 이를 사용하여 요청 문제를 해결할 수 있습니다. 자세한 내용은 API 작업 문제 해결을 참조하세요.
x-ms-version 요청을 실행하는 데 사용되는 Azure Blob Storage 버전을 나타냅니다. 버전 2009-09-19 이상을 사용하여 수행한 요청에 포함됩니다.

컨테이너가 2009-09-19 버전의 Blob Storage를 사용하여 공용 액세스로 표시된 경우 지정된 버전이 없는 익명 요청에 대해서도 이 헤더가 반환됩니다.
Date 서비스가 응답을 보낸 시간을 나타내는 UTC 날짜/시간 값입니다.
Access-Control-Allow-Origin 요청에 Origin 헤더가 포함되고 CORS가 일치 규칙과 함께 설정된 경우 반환됩니다. 일치할 경우 이 헤더는 원본 요청 헤더의 값을 반환합니다.
Access-Control-Expose-Headers 요청에 Origin 헤더가 포함되고 CORS가 일치 규칙과 함께 설정된 경우 반환됩니다. 이 헤더는 요청의 클라이언트 또는 발급자에게 노출될 응답 헤더 목록을 반환합니다.
Vary CORS 규칙이 지정된 경우 Origin 헤더의 값과 함께 반환됩니다. 자세한 내용은 Azure Storage에 대한 CORS 지원을 참조하세요.
Access-Control-Allow-Credentials 요청에 헤더가 Origin 포함되고 CORS가 모든 원본을 허용하지 않는 일치 규칙으로 사용하도록 설정된 경우 반환됩니다. 이 헤더는 로 설정됩니다 true.
x-ms-blob-committed-block-count Blob에 있는 커밋된 블록의 수를 나타냅니다. 이 헤더는 추가 Blob에 대해서만 반환됩니다.
x-ms-server-encrypted: true/false 버전 2015-12-11 이상. 이 헤더의 값은 Blob 데이터 및 애플리케이션 메타데이터가 지정된 알고리즘을 통해 완전히 암호화되는 경우 로 설정 true 됩니다. Blob이 암호화되지 않거나 Blob/애플리케이션 메타데이터의 일부만 암호화된 경우 값은 로 false설정됩니다.

응답 본문

응답 본문에는 Avro 이진 형식의 일련의 메시지로 전송된 Blob의 필터링된 내용이 포함됩니다. 다음 스키마를 사용합니다.

{
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.resultData",
    "doc": "Holds result data in the format specified for this query (CSV, JSON, etc.).",
    "fields": [
      {
        "name": "data",
        "type": "bytes"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.error",
    "doc": "An error that occurred while processing the query.",
    "fields": [
      {
        "name": "fatal",
        "type": "boolean",
        "doc": "If true, this error prevents further query processing.  More result data may be returned, but there is no guarantee that all of the original data will be processed.  If false, this error does not prevent further query processing."
      },
      {
        "name": "name",
        "type": "string",
        "doc": "The name of the error"
      },
      {
        "name": "description",
        "type": "string",
        "doc": "A description of the error"
      },
      {
        "name": "position",
        "type": "long",
        "doc": "The blob offset at which the error occurred"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.progress",
    "doc": "Information about the progress of the query",
    "fields": [
      {
        "name": "bytesScanned",
        "type": "long",
        "doc": "The number of bytes that have been scanned"
      },
      {
        "name": "totalBytes",
        "type": "long",
        "doc": "The total number of bytes to be scanned in this query"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.end",
    "doc": "Sent as the final message of the response, indicating that all results have been sent.",
    "fields": [
      {
        "name": "totalBytes",
        "type": "long",
        "doc": "The total number of bytes to be scanned in this query"
      }
    ]
  }
]

샘플 응답

      "StatusCode": 200,
      "ResponseHeaders": {
        "Content-Type": "avro/binary",
        "Date": "Fri, 24 Apr 2020 20:25:42 GMT",
        "ETag": "\u00220x8D7E88DA9C0A75B\u0022",
        "Last-Modified": "Fri, 24 Apr 2020 20:25:43 GMT",
        "Transfer-Encoding": "chunked",
        "x-ms-blob-type": "BlockBlob",
        "x-ms-client-request-id": "f6d1983c-55e5-9f95-6d3d-80d74862d99e",
        "x-ms-creation-time": "Fri, 24 Apr 2020 20:25:43 GMT",
        "x-ms-lease-state": "available",
        "x-ms-lease-status": "unlocked",
        "x-ms-request-id": "46c09ab1-b01e-0001-1076-1acef2000000",
        "x-ms-version": "2019-12-12"
	},
	"ResponseBody":{...}
  

권한 부여

Azure Storage에서 데이터 액세스 작업을 호출할 때 권한 부여가 필요합니다. 아래에 설명된 대로 작업에 권한을 Query Blob Contents 부여할 수 있습니다.

Azure Storage는 Microsoft Entra ID 사용하여 Blob 데이터에 대한 요청에 권한을 부여할 수 있도록 지원합니다. Microsoft Entra ID 사용하면 Azure RBAC(Azure 역할 기반 액세스 제어)를 사용하여 보안 주체에 권한을 부여할 수 있습니다. 보안 주체는 사용자, 그룹, 애플리케이션 서비스 주체 또는 Azure 관리 ID일 수 있습니다. 보안 주체는 OAuth 2.0 토큰을 반환하기 위해 Microsoft Entra ID 인증됩니다. 그런 다음 토큰을 사용하여 Blob service에 대한 요청을 승인할 수 있습니다.

Microsoft Entra ID 사용하여 권한 부여에 대한 자세한 내용은 Microsoft Entra ID 사용하여 Blob에 대한 액세스 권한 부여를 참조하세요.

사용 권한

아래에는 Microsoft Entra 사용자, 그룹 또는 서비스 주체가 작업을 호출 Query Blob Contents 하는 데 필요한 RBAC 작업과 이 작업을 포함하는 최소 권한의 기본 제공 Azure RBAC 역할이 나와 있습니다.

Azure RBAC를 사용하여 역할을 할당하는 방법에 대한 자세한 내용은 Blob 데이터에 액세스하기 위해 Azure 역할 할당을 참조하세요.

설명

  • 작업은 Query Blob Contents 형식에서 BlockBlob 만 지원됩니다.
  • 고객이 제공한 키로 암호화된 Blob의 콘텐츠 쿼리는 이 버전의 API에서 지원되지 않습니다.
  • 이 작업은 인프라 암호화 를 사용하도록 설정된 계정의 Blob에서 지원되지 않습니다.
  • 전용 컨테이너에 속하는 Blob을 검색하려면 x-ms-version 헤더가 필요합니다. Blob이 전체 또는 부분 공용 액세스에 사용할 수 있는 컨테이너에 속하는 경우 모든 클라이언트는 버전을 지정하지 않고 읽을 수 있습니다. 서비스 버전은 공용 컨테이너에 속하는 Blob을 검색하는 데 필요하지 않습니다. 자세한 내용은 컨테이너 및 Blob에 대한 액세스 제한을 참조하십시오.
  • 작업을 사용하여 Query Blob Contents 구분/CSV 또는 JSON 형식이 있는 개체만 쿼리할 수 있습니다.

결제

가격 책정 요청은 Blob Storage REST API를 통해 직접 또는 Azure Storage 클라이언트 라이브러리에서 Blob Storage API를 사용하는 클라이언트에서 비롯할 수 있습니다. 이러한 요청은 트랜잭션당 요금을 발생합니다. 트랜잭션 유형은 계정 청구 방식에 영향을 줍니다. 예를 들어 읽기 트랜잭션은 쓰기 트랜잭션과 다른 청구 범주에 발생합니다. 다음 표에서는 스토리지 계정 유형에 따라 요청에 대한 Query Blob Contents 청구 범주를 보여 줍니다.

작업 Storage 계정 유형 청구 범주
Blob 콘텐츠 쿼리 프리미엄 블록 Blob
표준 범용 v2
읽기 작업1

1읽기 요금 외에도 계정은 쿼리 가속 - 데이터 스캔쿼리 가속 - 반환된 데이터 트랜잭션 범주에 대한 요금이 부과됩니다. 이러한 범주에 대한 가격 책정은 Azure Data Lake Storage 가격 책정 페이지에 표시됩니다.

추가 정보

Azure Storage 상태 및 오류 코드Blob Storage 오류 코드에 대한 요청 권한 부여Blob Storage 작업에 대한 시간 제한 설정쿼리 가속: SQL 언어 참조