Azure Blob Storage にあるデータのインデックスを作成する

[アーティクル]
03/18/2024

この記事では、インデクサーを構成する方法について学習します。これにより、Azure Blob Storage からコンテンツをインポートし、Azure AI Search でその検索ができるようになります。インデクサーへの入力は、1 つのコンテナー内の BLOB です。出力は、検索可能なコンテンツとメタデータが個々のフィールドに格納される検索インデックスです。

この記事では、インデクサーの作成に関する記事を補足するため、特に Blob Storage について説明します。 REST API を使用して、すべてのインデクサーに共通する 3 部構成のワークフロー (データソースの作成、インデックスの作成、インデクサーの作成) を示します。データ抽出は、インデクサーの作成要求を送信したときに発生します。

AI エンリッチメントとテキスト指向処理の両方で BLOB インデクサーがよく使われます。この記事では、テキストベースのインデックス作成用のインデクサーに焦点を当てて説明します。テキストのコンテンツとメタデータは、フルテキスト検索のシナリオで取り込まれます。

前提条件

Azure Blob Storage、Standard パフォーマンス (汎用 v2).
Blob Storage のアクセス層には、ホット、クール、アーカイブがあります。検索インデクサーからアクセスできるのは、ホットとクールのみです。
テキストコンテンツとメタデータを提供する BLOB。 BLOB にバイナリコンテンツまたは非構造化テキストが含まれている場合は、画像と自然言語処理用の AI エンリッチメントを追加することを検討してください。検索サービスレベルのインデクサー制限を超える BLOB コンテンツは使用できません。
サポートされているネットワーク構成とデータアクセス。少なくとも、Azure Storage の読み取りアクセス許可が必要です。アクセスキーを含むストレージ接続文字列は、ストレージコンテンツへの読み取りアクセスが許可されます。代わりに、Microsoft Entra ログインとロールを使用している場合は、検索サービスのマネージド ID にストレージ BLOB データ閲覧者のアクセス許可があることを確認してください。

既定では、検索とストレージの両方がパブリック IP アドレスからの要求を受け入れます。ネットワークセキュリティが緊急の問題でない場合は、接続文字列と読み取りアクセス許可のみを使用して BLOB データのインデックスを作成できます。ネットワーク保護を追加する準備ができたら、データアクセスに関するガイダンスについては、Azure ネットワークセキュリティ機能によって保護されているコンテンツへのインデクサーアクセスに関するページを参照してください。
この記事に示すような REST 呼び出しを作成する場合は、REST クライアントを使用します。

サポートされるドキュメントの形式

BLOB インデクサーは、次の形式のドキュメントからテキストを抽出できます。

CSV (CSV BLOB のインデックス作成に関する記事を参照)
EML
EPUB
GZ
HTML
JSON (JSON BLOB のインデックス作成に関する記事を参照)
KML (地理的表現の XML)
Microsoft Office 形式: DOCX/DOC/DOCM、XLSX/XLS/XLSM、PPTX/PPT/PPTM、MSG (Outlook 電子メール)、XML (2003 と 2006 両方の WORD XML)
オープンドキュメント形式: ODT、ODS、ODP
PDF
プレーンテキストファイル (「プレーンテキストのインデックス作成」も参照)
RTF
XML
郵便番号

インデックスを作成する BLOB を決定する

インデックス作成を設定する前に、ソースデータを確認して、変更を事前に行う必要があるかどうかを判断します。インデクサーは、一度に 1 つのコンテナーのコンテンツにインデックスを作成できます。既定では、コンテナー内のすべての BLOB が処理されます。より選択的な処理を行うためのオプションがいくつかあります。

BLOB を仮想フォルダーに配置します。インデクサーデータソース定義には、仮想フォルダーを受け取ることができる "query" パラメーターが含まれています。仮想フォルダーを指定すると、そのフォルダー内の BLOB にのみインデックスが作成されます。
ファイルの種類によって BLOB を含めるか、除外します。除外する BLOB を決定するのに、「サポートされるドキュメントの形式」の一覧が役立ちます。たとえば、検索可能なテキストを提供しない画像またはオーディオのファイルを除外できます。この機能は、インデクサーの構成設定によって制御されます。

任意の BLOB を含めるか、除外します。何らかの理由で特定の BLOB をスキップする場合は、Blob Storage 内の BLOB に次のメタデータのプロパティと値を追加できます。インデクサーでこのプロパティが検出されると、インデックス作成の実行時に BLOB またはそのコンテンツがスキップされます。

プロパティ名	プロパティ値	説明
"AzureSearch_Skip"	`"true"`	BLOB を完全にスキップするように BLOB インデクサーに指示します。メタデータとコンテンツのどちらの抽出も行われません。特定の BLOB で何度もエラーが発生し、インデックス作成プロセスが中断されるときに利用できます。
"AzureSearch_SkipContent"	`"true"`	コンテンツをスキップし、メタデータだけを抽出します。これは、構成設定で説明されている `"dataToExtract" : "allMetadata"` 設定に相当し、特定の BLOB のみを対象とします。

包含または除外の条件を設定していない場合、インデクサーは、不適格な BLOB をエラーとして報告し、先に進みます。十分なエラーが発生した場合は、処理が停止することがあります。エラーの許容範囲は、インデクサーの構成設定で指定できます。

インデクサーは通常、BLOB ごとに 1 つの検索ドキュメントを作成します。ここで、テキストコンテンツとメタデータは、インデックス内の検索可能フィールドとして取得されます。 BLOB がファイル全部の場合は、それらを複数の検索ドキュメントに解析できます。たとえば、CSV ファイル内の行を解析して、1 行につき 1 つの検索ドキュメントを作成できます。

複合または埋め込みドキュメント (ZIP アーカイブ、添付ファイルが含まれている Outlook メールが埋め込まれた Word 文書、添付ファイル付き .MSG ファイルなど) も、1 つのドキュメントとして、インデックスが作成されます。例えば、.MSG ファイルの添付ファイルから抽出されたすべての画像が normalized_images フィールドに返されます。画像がある場合は、そのコンテンツからさらに検索ユーティリティを取得するために AI エンリッチメントを追加することを検討してください。

ドキュメントのテキストコンテンツが、"content" という名前の文字列フィールドに抽出されます。標準およびユーザー定義のメタデータを抽出することもできます。

BLOB メタデータのインデックス作成

BLOB メタデータのインデックスを作成することもできます。これは、標準またはカスタムのメタデータプロパティがフィルターとクエリで役に立つと思われる場合に便利です。

ユーザーが指定したメタデータプロパティは、そのまま抽出されます。値を受け取るには、Edm.String 型の検索インデックスに、BLOB のメタデータキーと同じ名前のフィールドを定義する必要があります。たとえば、BLOB に値が High のメタデータキー Sensitivity がある場合、検索インデックスで Sensitivity という名前のフィールドが定義されている必要があり、値 High が設定されます。

次に示すように、標準の BLOB メタデータプロパティは、同じような名前のフィールドおよび型指定されたフィールドに抽出できます。 BLOB インデクサーでは、これらの BLOB メタデータプロパティの内部フィールドマッピングを自動的に作成し、ハイフンが付きの元の名前 ("metadata-storage-name") を下線付きの同等の名前 ("metadata_storage_name") に変換します。

その場合でも、インデックス定義に下線付きフィールドを追加する必要がありますが、インデクサーによって自動的に関連付けが実行されるため、フィールドマッピングを省略できます。

metadata_storage_name (Edm.String) - BLOB のファイル名。たとえば、/my-container/my-folder/subfolder/resume.pdf という BLOB がある場合、このフィールドの値は resume.pdf になります。
metadata_storage_path (Edm.String) - ストレージアカウントを含む、BLOB の完全な URI。たとえば、https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf のように指定します。
metadata_storage_content_type (Edm.String) - BLOB をアップロードするためのコードで指定したコンテンツタイプ。たとえば、「 application/octet-stream 」のように入力します。
metadata_storage_last_modified (Edm.DateTimeOffset) - 前回変更時の BLOB のタイムスタンプ。インデックスの初回作成後に最初から作成し直さなくても済むよう、変更された BLOB を Azure AI Search が特定するために、このタイムスタンプが使用されます。
metadata_storage_size (Edm.Int64) - BLOB のサイズ (バイト単位)。
metadata_storage_content_md5 (Edm.String) - BLOB コンテンツの MD5 ハッシュ (利用可能な場合)。
metadata_storage_sas_token (Edm.String) - BLOB に対してアクセスするために、カスタムスキルで使用できる一時的な SAS トークン。このトークンは、有効期限が切れる可能性があるため、後で使用するために保存しないでください。

最後に、インデックスを作成している BLOB のドキュメント形式に固有のメタデータプロパティも、インデックススキーマで表すことができます。コンテンツ固有のメタデータの詳細については、コンテンツのメタデータプロパティに関するページを参照してください。

重要な指摘点としては、検索インデックスに対し、ここに挙げたすべてのプロパティのフィールドを定義する必要はありません。実際のアプリケーションで必要となるプロパティだけを取り込んでください。

現時点では、BLOB インデックスタグのインデックス作成は、このインデクサーではサポートされていません。

データソースを定義する

データソース定義では、インデックスを付けるデータ、資格情報、データの変更を識別するためのポリシーを指定します。データソースは、複数のインデクサーで使用できるように、独立したリソースとして定義します。

データソースを作成または更新してその定義を設定します。

{
    "name" : "my-blob-datasource",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

"type" を "azureblob" に指定します (必須)。
"credentials" を Azure Storage 接続文字列に設定します。続く部分は、サポートされている形式を記述します。
"container" を BLOB コンテナーに設定し、"query" を使用してサブフォルダーを指定します。

ソースドキュメントに削除対象のフラグが設定されているときにインデクサーで検索ドキュメントを削除する場合は、データソースの定義に論理的な削除ポリシーを含めることもできます。

サポートされている資格情報と接続文字列

インデクサーで BLOB コンテナーへの接続に使用される接続は次のとおりです。

フルアクセスストレージアカウントの接続文字列
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Azure portal の Storage アカウントページで左側のナビゲーションウィンドウの [アクセスキー] を選択して接続文字列を取得できます。キーだけではなく、完全な接続文字列を選択してください。

マネージド ID の接続文字列
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
この接続文字列にアカウントキーは必要ありませんが、マネージド ID を使用して接続するように検索サービスを前もって構成しておく必要があります。

ストレージアカウントの Shared Access Signature** (SAS) の接続文字列
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
SAS にはコンテナー上およびオブジェクト (この場合は BLOB) にリストおよび読み取りアクセス許可が必要です。

コンテナーの Shared Access Signature
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
SAS にはコンテナー上にリストおよび読み取りアクセス許可が必要です。詳細については、Shared Access Signatues の使用に関するページを参照してください。

Note

SAS の資格情報を使用する場合は、その有効期限が切れないように、データソースの資格情報を更新された署名で定期的に更新する必要があります。 SAS の資格情報の有効期限が切れた場合、インデクサーは失敗し、「接続文字列で指定された資格情報が無効か期限が切れています」のようなエラーメッセージが表示されます。

インデックスに検索フィールドを追加する

検索インデックスに、Azure BLOB のコンテンツとメタデータを受け入れるためのフィールドを追加します。

インデックスを作成または更新して、BLOB のコンテンツとメタデータを格納する検索フィールドを定義します。

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
{
    "name" : "my-search-index",
    "fields": [
        { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
        { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
    ]
}

ドキュメントキーフィールド ("key": true) を作成します。 BLOB コンテンツの場合、候補として最適なのはメタデータプロパティです。
- metadata_storage_path (既定値)。オブジェクトまたはファイルへの完全なパス。キーフィールド (この例では "ID") には、metadata_storage_path の値が設定されます (これが既定値であるため)。
- metadata_storage_name。名前が一意である場合にのみ使用可能。このフィールドをキーとして必要とする場合は、"key": true をこのフィールド定義に移動します。
- BLOB に追加するカスタムメタデータプロパティ。この方法を選んだ場合、BLOB のアップロードプロセスで、該当するメタデータのプロパティをすべての BLOB に追加する必要があります。キーは必須のプロパティであるため、値が欠落している BLOB については、インデックスが一切作成されません。カスタムメタデータプロパティをキーとして使用する場合は、そのプロパティを変更しないでください。キープロパティが変更されると、インデクサーでは同じ BLOB に対して重複したドキュメントを追加します。
メタデータプロパティには、ドキュメントキーとして無効な文字 (/ や - など) が含まれていることがよくあります。インデクサーには "base64EncodeKeys" プロパティ (規定値は true) があるため、構成やフィールドマッピングをしなくても、メタデータプロパティは自動的にエンコードされます。
"content" フィールドを追加して、各ファイルから抽出されたテキストを BLOB の "content" プロパティを通して格納します。この名前を使用する必要はありませんが、そうすることで暗黙的なフィールドマッピングを利用できます。
標準メタデータプロパティのフィールドを追加します。インデクサーは、カスタムメタデータプロパティ、標準メタデータプロパティ、コンテンツ固有メタデータプロパティを読み取ることができます。

BLOB インデクサーを構成して実行する

インデックスとデータソースを作成したら、インデクサーを作成できます。インデクサーの構成では、実行時の動作を制御する入力、パラメーター、プロパティを指定します。また、インデックスを作成する BLOB の部分を指定することもできます。

名前を指定し、データソースとターゲットインデックスを参照することで、インデクサーを作成または更新します。

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
{
  "name" : "my-blob-indexer",
  "dataSourceName" : "my-blob-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "base64EncodeKeys": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

既定値 (10 個のドキュメント) では使用できるリソースが不足している場合や過剰な場合は、batchSize を設定します。既定のバッチサイズは、データソースによって異なります。 BLOB のインデックス作成では、より大きな平均ドキュメントサイズを認識して、バッチサイズが 10 のドキュメントに設定されます。
"configuration" の下で、ファイルの種類に基づいてインデックスを作成する BLOB を制御するか、指定しないままにして BLOB をすべて取得します。

"indexedFileNameExtensions" には、ファイル拡張子のコンマ区切りリストを指定します (先頭にドットを付けます)。 "excludedFileNameExtensions" についても同様に行って、スキップする必要がある拡張子を指定します。同じファイル拡張子が両方のリストにある場合、それはインデックス作成から除外されます。
"configuration" の下で、"dataToExtract" を設定して、インデックスが作成される BLOB の部分を制御します。
- "contentAndMetadata" には、すべてのメタデータと、BLOB から抽出されたテキストコンテンツにインデックスを作成するように指定します。これが既定値です。
- "storageMetadata" には、標準的な BLOB のプロパティおよびユーザー指定のメタデータのみにインデックスを作成するように指定します。
- "allMetadata" には、標準の BLOB プロパティと、見つかったコンテンツの種類に対するメタデータを BLOB のコンテンツから抽出し、インデックスを作成するように指定します。
[構成] で、"parsingMode" を設定します。既定の解析モードは、BLOB ごとに 1 つの検索ドキュメントです。 BLOB がプレーンテキストの場合は、プレーンテキスト解析に切り替えることで、パフォーマンスを向上させることができます。 BLOB を複数の検索ドキュメントにマップするより詳細な解析が必要な場合は、別のモードを指定します。一対多の解析は、以下で構成される BLOB でサポートされています。
- JSON ドキュメント
- CSV ファイル
フィールドの名前または種類に違いがある、または検索インデックスで複数のソースフィールドのバージョンが必要な場合、フィールドマッピングを定義します。

BLOB のインデックス作成では、多くの場合、フィールドマッピングを省略できます。インデクサーには、"content" プロパティとメタデータプロパティを、インデックス内の似たような名前と種類のフィールドにマッピングするためのサポートが組み込まれているためです。メタデータプロパティの場合、インデクサーにより検索インデックスでハイフン - は自動的にアンダースコアに置き換えられます。
その他のプロパティについては、「インデクサーの作成方法」を参照してください。パラメーターの説明の完全な一覧については、REST API の「BLOB の構成パラメーター」を参照してください。

インデクサーは、作成されると自動的に実行されます。これを防ぐには、"disabled" を true に設定します。インデクサーの実行を制御するには、インデクサーをオンデマンドで実行するか、スケジュールを設定します。

インデクサーの状態を確認する

インデクサーの状態と実行履歴を監視するには、インデクサーの状態の取得要求を送信します。

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  Content-Type: application/json  
  api-key: [admin key]

応答には、状態と処理された項目の数が含まれます。次の例のように表示されます。

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

実行履歴には、最近完了した実行 50 件が含まれます。時系列の逆の順に並べられるため、最後の実行が最初に表示されます。

エラーの処理

インデックス作成中に通常発生するエラーには、サポートされていないコンテンツの種類、コンテンツの欠落、BLOB のサイズ超過などがあります。

既定では、BLOB インデクサーは、サポートされていないコンテンツの種類 (オーディオファイルなど) が含まれる BLOB を検出するとすぐに停止されます。 "excludedFileNameExtensions" パラメーターを使って特定のコンテンツの種類をスキップできます。ただし、エラーが発生した場合でもインデックスの作成を継続し、後から個々のドキュメントをデバッグすることができます。インデクサーのエラーの詳細については、インデクサーのトラブルシューティングガイドおよびインデクサーのエラーと警告に関するページを参照してください。

エラーが発生したときのインデクサーの応答を制御する 5 つのインデクサープロパティがあります。

PUT /indexers/[indexer name]?api-version=2020-06-30
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

パラメーター	有効な値	説明
"maxFailedItems"	-1、null または 0、正の整数	BLOB の解析中またはインデックスへのドキュメントの追加中、処理のどこかの時点でエラーが発生した場合に、インデックス付けを続行します。これらのプロパティには、許容できるエラーの数を設定します。値を `-1` に設定すると、どれだけエラーが発生しても処理を継続します。それ以外の場合、値は正の整数です。
"maxFailedItemsPerBatch"	-1、null または 0、正の整数	上記と同じですが、バッチインデックス作成に使用されます。
"failOnUnsupportedContentType"	true または false	インデクサーがコンテンツの種類を判別できない場合は、ジョブを続行するか失敗するかを指定します。
"failOnUnprocessableDocument"	true または false	サポートされているコンテンツの種類のドキュメントをインデクサーで処理できない場合は、ジョブを続行するか失敗するかを指定します。
"indexStorageMetadataOnlyForOversizedDocuments"	true または false	サイズが大きい BLOB は、既定ではエラーとして扱われます。このパラメーターを true に設定すると、コンテンツにインデックスを作成できない場合でも、インデクサーはそのメタデータのインデックスを作成しようとします。 BLOB サイズの制限については、「サービスの制限」を参照してください。

Azure Blob Storage にあるデータのインデックスを作成する

前提条件

サポートされるドキュメントの形式

インデックスを作成する BLOB を決定する

BLOB メタデータのインデックス作成

データソースを定義する

サポートされている資格情報と接続文字列

インデックスに検索フィールドを追加する

BLOB インデクサーを構成して実行する

インデクサーの状態を確認する

エラーの処理

関連項目

その他のリソース

Azure Blob Storage にあるデータのインデックスを作成する

前提条件

サポートされるドキュメントの形式

インデックスを作成する BLOB を決定する

BLOB メタデータのインデックス作成

データ ソースを定義する

サポートされている資格情報と接続文字列

インデックスに検索フィールドを追加する

BLOB インデクサーを構成して実行する

インデクサーの状態を確認する

エラーの処理

関連項目

その他のリソース

データソースを定義する