BLOB コンテンツのクエリ

[アーティクル]
06/14/2023

この操作は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 に指定できます。

パラメーター	説明
`snapshot`	省略可能。スナップショットパラメーターは不透明`DateTime`な値です。存在する場合は、クエリを実行する BLOB スナップショットを指定します。 BLOB スナップショットの操作の詳細については、「BLOB のスナップショットを作成する」を参照してください。
`versionid`	オプション、バージョン 2019-12-12 以降。パラメーターは `versionid` 不透明 `DateTime` な値です。存在する場合は、取得する BLOB のバージョンを指定します。
`timeout`	省略可能。 `timeout` パラメーターは、秒単位で表されます。詳細については、「 Blob Storage 操作のタイムアウトを設定する」を参照してください。

要求ヘッダー

次の表では、必須および省略可能な要求ヘッダーについて説明します。

要求ヘッダー	説明
`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>`	省略可能。このヘッダーを指定すると、次の 2 つの条件を満たした場合にのみ操作が実行されます。 - BLOB のリースは現在アクティブです。 - 要求で指定されたリース ID は、BLOB のリース ID と一致します。このヘッダーを指定すると、2 つの条件を満たしていない場合は要求が失敗し、`Query Blob Contents` 操作はステータスコード 412 (Precondition Failed) で失敗します。
`Origin`	省略可能。要求の送信元を指定します。このヘッダーが存在すると、応答でクロスオリジンリソース共有 (CORS) ヘッダーが生成されます。
`x-ms-client-request-id`	省略可能。ログ記録の構成時にログに記録される 1 kibibyte (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>

要求本文の要素を次の表に示します。

要素名	説明
`QueryRequest`	必須。クエリ要求設定のセットをグループ化します。
`QueryType`	必須。指定されたクエリ式の型を示します。現在のバージョンの唯一の有効な値はです `SQL`。
`Expression`	必須。 SQL のクエリ式を示します。クエリ式の最大サイズは 256 KiB です。式の構文の詳細については、「クエリアクセラレーション: SQL 言語リファレンス」を参照してください。
`InputSerialization`	省略可能。 BLOB コンテンツの入力シリアル化に関する設定をグループ化します。指定しない場合は、区切りテキスト構成が使用されます。
`Format`	`InputSerialization` を指定した場合は必須。 BLOB データの形式に関する設定をグループ化します。
`Type`	`InputSerialization` を指定した場合は必須。形式の種類を示します。有効な値は `delimited`、`csv`、`json` です。
`DelimitedTextConfiguration`	省略可能。 BLOB が区切りテキストで書式設定されている場合に BLOB データの解釈に使用される設定をグループ化します。
`ColumnSeparator`	省略可能。列を区切るために使用される文字列を示します。
`FieldQuote`	省略可能。特定のフィールドを引用符で囲む文字列を示します。
`RecordSeparator`	省略可能。レコードを区切るために使用される文字列を示します。
`EscapeChar`	省略可能。エスケープ文字として使用される文字列を示します。
`HasHeaders`	省略可能。データにヘッダーがあるかどうかを表すブール型 (Boolean) の値を指定します。
`JsonTextConfiguration`	省略可能。 BLOB が JSON 形式の場合に BLOB データを解釈するために使用される設定をグループ化します。
`RecordSeparator`	省略可能。レコードを区切るために使用される文字列を示します。
`OutputSerialization`	省略可能。応答で返される BLOB のフィルター処理された内容のシリアル化形式を示します。指定しない場合は、区切りテキスト構成が使用されます。
`Format`	`OutputSerialization` を指定した場合は必須。返される応答の形式に関する設定をグループ化します。
`Type`	`OutputSerialization` を指定した場合は必須。形式の種類を示します。有効な値は、`delimited`、`csv`、`json`、`arrow` です。
`DelimitedTextConfiguration`	省略可能。応答を区切りテキストで書式設定する必要がある場合に、応答の書式設定に使用される設定をグループ化します。
`ColumnSeparator`	省略可能。列を区切るために使用される文字列を示します。
`FieldQuote`	省略可能。特定のフィールドを引用符で囲む文字列を示します。
`RecordSeparator`	省略可能。レコードを区切るために使用される文字列を示します。
`EscapeChar`	省略可能。エスケープ文字として使用される文字列を示します。
`HasHeaders`	省略可能。データにヘッダーがあるかどうかを表すブール型 (Boolean) の値を指定します。
`JsonTextConfiguration`	省略可能。応答を JSON 形式にする必要がある場合に、応答の書式設定に使用される設定をグループ化します。
`RecordSeparator`	省略可能。レコードを区切るために使用される文字列を示します。
`ArrowConfiguration`	省略可能。応答を Arrow 形式にする必要がある場合に、応答の書式設定に使用される設定をグループ化します。
`Schema`	`ArrowConfiguration` を指定した場合は必須。返された Arrow 応答のスキーマに関する設定をグループ化します。
`Field`	省略可能。特定のフィールドに関する設定をグループにします。
`Type`	`Field` を指定した場合は必須。フィールドの種類を示します。有効な値は、`Int`、`Float`、`Decimal`、`Bool` です。
`Precision`	省略可能。フィールドの有効桁数を示します。
`Scale`	省略可能。フィールドのスケールを示します。

Response

応答には HTTP ステータスコード、一連の応答ヘッダー、および応答の本文が含まれます。応答本文は Avro バイナリ形式です。応答コンテンツの長さは不明であるため、応答はチャンクエンコードでストリーミングされます。

status code

クエリ要求が整形式で承認されている場合、操作は状態コード 202 (Accepted) を返します。応答ストリーミング中に発生したエラーまたは進行状況メッセージは、応答本文の一部として返されます。

状態コードの詳細については、「状態とエラーコード」を参照してください。

応答ヘッダー

この操作の応答には、次のヘッダーが含まれています。応答には、追加の標準 HTTP ヘッダーも含まれる場合があります。すべての標準ヘッダーは、HTTP/1.1 プロトコル仕様に準拠しています。

構文	説明
`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 ロールベースのアクセス制御 (Azure RBAC) を使用して、セキュリティプリンシパルにアクセス許可を付与できます。セキュリティプリンシパルには、ユーザー、グループ、アプリケーションサービスプリンシパル、または 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 アクション:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
最小特権の組み込みロール:ストレージ BLOB データ閲覧者

Azure RBAC を使用したロールの割り当ての詳細については、「 BLOB データにアクセスするための Azure ロールの割り当て」を参照してください。

Shared Access Signature (SAS) は、ストレージアカウント内のリソースへのセキュリティで保護された委任されたアクセスを提供します。 SAS を使用すると、クライアントがデータにアクセスする方法をきめ細かく制御できます。クライアントがアクセスできるリソース、それらのリソースに対するアクセス許可、および SAS が有効な期間を指定できます。

この操作では Query Blob Contents 、ユーザー委任 SAS、サービス SAS、アカウント SAS の 3 種類の共有アクセス署名がサポートされています。

セキュリティのベストプラクティスとして、ストレージアカウントキーではなくMicrosoft Entra資格情報を使用することをお勧めします。これは、より簡単に侵害される可能性があります。アプリケーション設計で共有アクセス署名が必要な場合は、可能であれば、Microsoft Entra資格情報を使用してユーザー委任 SAS を作成します。

ストレージアカウントに対して共有キーアクセスが許可されていない場合、サービス SAS トークンまたはアカウント SAS トークンは、Blob Storage への要求では許可されません。詳細については、「共有キーの禁止が SAS トークンにどのように影響するかを理解する」を参照してください。

ユーザー委任 SAS

ユーザー委任 SAS は、Microsoft Entra資格情報と、SAS に対して指定されたアクセス許可によっても保護されます。

Query Blob Contentsコンテナーまたは BLOB リソースに委任された SAS トークンを使用して操作を呼び出すには、ユーザー委任 SAS トークンの一部として読み取り (r) アクセス許可が必要です。

ユーザー委任 SAS の詳細については、「ユーザー委任 SAS の作成」を参照してください。

サービス SAS

サービス SAS は、ストレージアカウントキーで保護されます。サービス SAS は、BLOB ストレージなどの単一の Azure Storage サービス内のリソースへのアクセスを委任します。

Query Blob Contentsコンテナーまたは BLOB リソースに委任された SAS トークンを使用して操作を呼び出すには、サービス SAS トークンの一部として読み取り (r) アクセス許可が必要です。

サービス SAS の詳細については、「サービス SAS の作成」を参照してください。

アカウント SAS

アカウント SAS は、ストレージアカウントキーで保護されます。アカウント SAS は、1 つ以上のストレージサービスのリソースへのアクセスを委任します。サービスまたはユーザー委任 SAS を介して実行できるすべての操作は、アカウント SAS を介しても実行できます。

次の表は、アクセスを委任するときに指定する署名付きリソースの種類と署名付きアクセス許可を示しています。

操作	署名済みサービス	署名されたリソースの種類	署名されたアクセス許可
BLOB コンテンツのクエリ	BLOB (b)	オブジェクト (o)	読み取り (r)

アカウント SAS の詳細については、「アカウント SAS の作成」を参照してください。

この操作では Query Blob Contents 、共有キーの承認がサポートされています。アカウントキーを使用した承認は、セキュリティが低く、ほとんどのシナリオでは推奨されません。

可能な場合は、ストレージアカウントの共有キーの承認を禁止することをお勧めします。詳細については、「共有キーによる承認の防止」を参照してください。

注釈

操作は Query Blob Contents 、型でのみ BlockBlob サポートされます。
このバージョンの API では、顧客が指定したキーで暗号化された BLOB の内容に対するクエリはサポートされていません。
この操作は、インフラストラクチャ暗号化が有効になっているアカウント内の 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 を示しています。

操作	ストレージアカウントの種類	課金カテゴリ
BLOB コンテンツのクエリ	Premium ブロック BLOB Standard 汎用 v2	読み取り操作¹

¹読み取り料金に加えて、 クエリ高速化 - データスキャン と クエリ高速化 - 返された トランザクションカテゴリの料金がアカウントに発生します。これらのカテゴリの価格は、[Azure Data Lake Storage価格] ページに表示されます。

こちらもご覧ください

Azure Storage の状態とエラーコードに対する要求を承認する Blob Storage エラーコード Blob Storage 操作のタイムアウトを設定するクエリアクセラレーション: SQL 言語リファレンス