タグによる BLOB の検索

  • [アーティクル]

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

要求

要求は 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 の最大数を指定します。 要求で 5,000 を超える値が指定 maxresults されていない場合、サーバーは最大 5,000 個のアイテムを返します。 返される追加の結果がある場合、サービスは応答要素で継続トークンを NextMarker 返します。 場合によっては、サービスから返される結果が指定よりも maxresults 少なくなる場合があります。 サービスは継続トークンを返す場合もあります。

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

要求ヘッダー

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

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

要求本文

[なし] :

Response

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

status code

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

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

応答ヘッダー

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

応答ヘッダー 説明
Content-Type application/xmlコンテンツ タイプとして を指定します。
Content-Length 返される XML ドキュメントのサイズをバイト単位で指定します。
x-ms-request-id 行われた要求を一意に識別します。 これを使用して、要求のトラブルシューティングを行うことができます。 詳細については、「 API 操作のトラブルシューティング」を参照してください。
x-ms-version 要求の実行に使用されたAzure Blob Storageのバージョンを示します。
Date サービスが応答を送信した時刻を示す UTC 日付/時刻値。
x-ms-client-request-id 要求と対応する応答のトラブルシューティングに使用できます。 このヘッダーの値は、要求に存在し、その値が最大 1,024 文字の可視 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 ドキュメントです。

承認

Azure Storage でデータ アクセス操作を呼び出す場合は、承認が必要です。 以下で説明するように、操作を Find Blobs by Tags 承認できます。

重要

Microsoft では、マネージド ID でMicrosoft Entra IDを使用して、Azure Storage への要求を承認することをお勧めします。 Microsoft Entra IDは、共有キーの承認と比較して優れたセキュリティと使いやすさを提供します。

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ユーザー、グループ、マネージド ID、またはサービス プリンシパルが操作を呼び出Find Blobs by Tagsすために必要な RBAC アクションと、このアクションを含む最小特権の組み込み Azure RBAC ロールを次に示します。

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

注釈

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

階層型名前空間が有効になっているアカウントの場合、 Find Blobs by Tags BLOB タグは階層型名前空間アカウントではサポートされていないため、操作はサポートされていません。

を使用する Find Blobs by Tags セカンダリ インデックスは、最終的に一貫性があります。 を介した Set Blob Tags BLOB タグへのUpdatesは、操作に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 Storage REST API を介して直接、または Azure Storage クライアント ライブラリを介して Blob Storage API を使用するクライアントから送信できます。 これらの要求では、トランザクションあたりの料金が発生します。 トランザクションの種類は、アカウントの課金方法に影響します。 たとえば、読み取りトランザクションは、書き込みトランザクションとは異なる課金カテゴリに計上されます。 次の表は、ストレージ アカウントの種類に基づく要求の課金カテゴリ Find Blobs by Tags を示しています。

操作 ストレージ アカウントの種類 課金カテゴリ
タグによる BLOB の検索 Premium ブロック BLOB
Standard 汎用 v2
Standard 汎用 v1		 コンテナー操作の一覧表示とCreate

指定した課金カテゴリの価格については、「Azure Blob Storage価格」を参照してください。

こちらもご覧ください

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