タグによる BLOB の検索操作

  • [アーティクル]

この操作では Find Blobs by Tags 、指定された検索式に一致するタグを持つストレージ アカウント内のすべての BLOB を検索します。

Request

Find Blobs by Tags 要求の構成は次のとおりです。 HTTPS が推奨されます。 myaccount をストレージ アカウントの名前に置き換えます。

GET メソッド要求の URI HTTP バージョン
https://myaccount.blob.core.windows.net?comp=blobs&where=<expression> HTTP/1.1

URI パラメーター

次の追加パラメーターを要求の URI で指定できます。

パラメーター 説明
expression 必須です。 指定した式に一致するタグを持つ BLOB のみを含むように結果セットをフィルター処理します。

この式を構築する方法の詳細については、「解説」を参照してください。
marker 省略可能。 次の操作で返される結果セットの部分を識別する文字列値。 返された結果セットが完了していない場合、操作は応答本文内のマーカー値を返します。 その後、後続の呼び出しでマーカー値を使用して、次の項目セットを要求できます。

マーカー値はクライアントに対して非透過的です。
maxresults 省略可能。 返す BLOB の最大数を指定します。 要求で maxresults が指定されていないか、5,000 を超える値が指定されている場合、サーバーは最大 5,000 項目を返します。 返される追加の結果がある場合、サービスは応答要素で継続トークンを NextMarker 返します。 場合によっては、サービスから返される結果が指定された maxresults 結果よりも少なく、継続トークンも返される場合があります。

maxresults をゼロ以下の値に設定すると、エラー応答コード 400 (Bad Request) が発生します。
timeout 省略可能。 timeout パラメーターは、秒単位で表されます。 詳細については、「 BLOB サービス操作のタイムアウトの設定」を参照してください。

要求ヘッダー

必須要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。

要求ヘッダー 説明
Authorization 必須です。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
Date または x-ms-date 必須です。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
x-ms-version すべての承認された要求に必要です。匿名要求の場合は省略可能です。 この要求に使用する操作のバージョンを指定します。 詳細については、「 Azure Storage Services のバージョン管理」を参照してください。
x-ms-client-request-id 省略可能。 ストレージ分析ログが有効になっているときに分析ログに記録される 1 KiB 文字の制限を持つクライアント生成の不透明な値を提供します。 クライアント側のアクティビティをサーバーが受信した要求と関連付けるには、このヘッダーを使用することが強く推奨されます。 詳細については、「Storage Analyticsログと Azure ログ: ログを使用したストレージ要求の追跡」を参照してください。

要求本文

なし。

対応

応答には、HTTP 状態コード、応答ヘッダー、および応答本文が含まれます。

状態コード

操作に成功すると、状態コード 200 (OK) が返されます。

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

レスポンス ヘッダー

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

応答ヘッダー 説明
Content-Type application/xml
Content-Length 返された XML ドキュメントのサイズ (バイト単位)
x-ms-request-id このヘッダーは要求を一意に識別するので、要求のトラブルシューティングに使用できます。 詳細については、「 API 操作のトラブルシューティング」を参照してください。
x-ms-version 要求の実行に使用する BLOB サービスのバージョンを示します。
Date サービスによって生成される、応答の開始時刻を示す UTC 日付/時刻値。
x-ms-client-request-id このヘッダーは、要求と対応する応答のトラブルシューティングに使用できます。 このヘッダーの値は、要求に存在し、値が最大 1024 の ASCII 文字で表示される場合、ヘッダーの値 x-ms-client-request-id と等しくなります。 ヘッダーが x-ms-client-request-id 要求に存在しない場合、このヘッダーは応答に存在しません。

応答本文

バージョン 2020-04-08 以降では、BLOB の一致するタグは Tags 要素内にカプセル化されます。 応答本文の形式は次のとおりです。

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint=http://myaccount.blob.core.windows.net/>  
  <Where>string-value</Where>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</Name>  
      <ContainerName>container-name</ContainerName>  
      <Tags>
        <TagSet>
          <Tag>
            <Key>matching-tag-name1</Key>
            <Value>matching-tag-value1</Value>
          </Tag>
          <Tag>
            <Key>matching-tag-name2</Key>
            <Value>matching-tag-value2</Value>
          </Tag>
        </TagSet>
      </Tags> 
    </Blob>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

応答本文は、整形式の UTF-8 XML ドキュメントです。

承認

この操作は、アカウント所有者と、タグ ( f SAS アクセス許可) で BLOB を検索するアクセス許可を持つ Shared Access Signature を持つすべてのユーザーが呼び出すことができます。 承認には アカウント SAS が必要であることに注意してください。

さらに、Microsoft.Storage/storageAccounts/blobServices/containers/blobs/filter/action アクセス許可を持つ RBAC ユーザーも、この操作を実行できます。

解説

この Find Blobs by Tags 操作は REST API バージョン 2019-12-12 以降でサポートされています。

使用される Find Blobs by Tags セカンダリ インデックスは、最終的に一貫性があります。 多くを介して Set Blob Tags BLOB タグに更新は、操作にFind Blobs by Tagsすぐには表示されません。

検索式の構築

URI パラメーターは where 、特定の式に一致するタグを持つストレージ アカウント内の BLOB を検索します。 結果セットで BLOB を true 返すには、式を評価する必要があります。

ストレージ サービスでは、クエリ パラメーターの値に対する ANSI SQL WHERE 句文法のサブセットが where=<expression> サポートされています。 次の演算子がサポートされています。

演算子 説明 例
= 等しい &where=Status = 'In Progress'
> より大きい &where=LastModified > '2018-06-18 20:51:26Z'
>= 以上 &where=Priority >= '05'
< より小さい &where=Age < '032'
<= 以下 &where=Reviewer <= 'Smith'
AND 論理 AND &where=Name > 'C' AND Name < 'D'
&where=Age > '032' AND Age < '100'
@container コンテナーを指定する &where=@container='mycontainer' AND Name = 'C'

注: URI パラメーターの値は、適切に where URI エンコードされている必要があります (スペースや演算子を含む)。 上記の例では、読みやすくするためにこれを省略しています。

すべてのタグ値は文字列であり、サポートされているバイナリ 関係演算子はタグ値の辞書式並べ替えを使用します。 数値や日付を含む文字列以外のデータ型をサポートするには、適切なパディングと並べ替え可能な書式設定を使用する必要があります。 タグの値は一重引用符で囲む必要があります。

タグ名が通常の SQL 識別子である場合は、エスケープせずに存在する可能性があります。特殊文字が含まれている場合は、二重引用符で区切る必要があります (例: "TagName" = 'TagValue')。 タグ名は常に二重引用符で囲むようお勧めします。

ストレージ サービスは、エラー コード 400 (無効な要求) を含む無効な式を含む要求を拒否します。

関連項目

BLOB インデックスを使用して Azure Blob Storage でデータを管理および検索する
Azure Storage への要求を承認する
ステータス コードとエラー コード
BLOB サービスのエラー コード