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

BLOB インデクサーは、Azure Blob Storageからコンテンツをインポートし、Azure AI 検索で検索できるようにします。 インデクサーは、1 つのコンテナー内の BLOB を入力として受け取ります。 出力は、検索可能なコンテンツとメタデータを個々のフィールドに格納する検索インデックスです。

この記事では、 Search Service REST API を 使用して、インデクサーを構成して実行する方法を示します。 ただし、次を使用することもできます。

• Azure SDK パッケージ (任意のバージョン)
• Azure portal のデータのインポート ウィザード

[前提条件]

• Azure Blob Storage、Standard パフォーマンス (汎用 v2).

• アクセス層には、ホット、クール、コールド、アーカイブがあります。 インデクサーでは、ホット、クール、コールドのアクセス層で BLOB を取得できます。

• テキスト コンテンツとメタデータを提供する BLOB。 BLOB にバイナリ コンテンツまたは非構造化テキストが含まれている場合は、画像と自然言語処理用の AI エンリッチメントを追加することを検討してください。 BLOB コンテンツは、価格レベルの インデクサーの制限 を超えることはできません。

  blob インデクサーの制限は、blob の最大サイズと、Azure AI 検索 が blob から抽出する文字数の上限を対象としています。 スキルセットを使用する場合、各スキルの入力またはサービスの制限は、ドキュメントクラッキング後に個別に適用されます。

• サポートされているネットワーク構成とデータ アクセス。 少なくとも、Azure Storage の読み取りアクセス許可が必要です。 アクセス キーを含むストレージ接続文字列は、ストレージ コンテンツへの読み取りアクセスが許可されます。 代わりに、Microsoft Entra ログインとロールを使用している場合は、検索サービスのマネージド ID にストレージ BLOB データ閲覧者のアクセス許可があることを確認してください。

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

• この記事に示すような REST 呼び出しを作成する場合は、REST クライアントを使用します。

サポートされているタスク

このインデクサーは、次のタスクに使用できます。

• データのインデックス作成と増分インデックス作成: このインデクサーを使用すると、BLOB コンテナーとフォルダーのファイルと関連メタデータにインデックスを作成できます。 組み込みの変更検出を使用して、新しいファイルと更新されたファイルとメタデータを検出します。 スケジュールまたはオンデマンドでデータ更新を構成できます。

• 削除の検出: このインデクサーを使用すると、ネイティブの論理的な削除を使用するか、カスタム メタデータを使用して、削除を検出できます。

• スキルセットを使用して AI を適用する: インデクサーは スキルセットを完全にサポートします。 このサポートには、データ チャンクと埋め込みを追加する 統合ベクター化などの主要な機能が含まれます。

• 解析モード: インデクサーは、JSON 配列または行を個々の検索ドキュメントに解析する場合に JSON 解析モードをサポートします。 また、Markdown 解析モードもサポートしています。

• 他の機能との互換性: インデクサーは、 デバッグ セッション、 インデクサー キャッシュ (プレビュー)、 ナレッジ ストアなど、他のインデクサー機能とシームレスに連携します。

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

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

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

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

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

• BLOB を仮想フォルダーに配置します。 インデクサー データ ソース定義 には、仮想フォルダーを受け取ることができる query パラメーターが含まれています。 仮想フォルダーを指定すると、インデクサーはフォルダー内の BLOB にのみインデックスを作成します。

• ファイルの種類によって BLOB を含めるか、除外します。 除外する BLOB を決定するのに、「サポートされるドキュメントの形式」の一覧が役立ちます。 たとえば、検索可能なテキストを提供しない画像またはオーディオのファイルを除外できます。 この機能は、インデクサーの 構成設定 を使用して制御します。

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

  プロパティ名	プロパティ値	Explanation
  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 メタデータのインデックスを作成できます。 インデクサーはメタデータ プロパティを抽出し、それらをインデックス フィールドに格納します。これは、フィルターとクエリを作成するのに役立ちます。

キャプチャするメタデータ プロパティの検索インデックス内のフィールドを定義します。 使用可能なすべての標準またはカスタム メタデータ プロパティを定義する必要はありません。 アプリケーションに必要なプロパティをキャプチャするだけです。

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

標準の BLOB メタデータ プロパティ

標準 BLOB メタデータの場合は、同じアンダースコア付き名前を使用してインデックス内のフィールドを定義します。 詳細なフィールド定義の例については、「 インデックスに検索フィールドを追加する」を参照してください。

抽出するメタデータを制御する dataToExtract 設定を含むインデクサーの構成については、「 BLOB インデクサーの構成と実行」を参照してください。

インデックスに対応するフィールドを定義すると、インデクサーは次の標準メタデータ プロパティを認識し、マップできます。

• metadata_storage_name (Edm.String) は BLOB のファイル名です。 たとえば、BLOB /my-container/my-folder/subfolder/resume.pdfがある場合、このフィールドの値は resume.pdf。

• metadata_storage_path (Edm.String) は、ストレージ アカウントを含む BLOB の完全な URI です。 たとえば、「 https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf 」のように入力します。 ナビゲーションまたはソース属性の検索結果に BLOB URL を含めるには、このプロパティを使用します。

• metadata_storage_content_type (Edm.String) は、BLOB のアップロードに使用したコードで指定されたコンテンツ タイプです。 たとえば、「 application/octet-stream 」のように入力します。

• metadata_storage_last_modified (Edm.DateTimeOffset) は、BLOB の最後に変更されたタイムスタンプです。 Azure AI 検索は、このタイムスタンプを使用して変更された BLOB を識別し、最初のインデックス作成後にインデックスを再作成しないようにします。

• metadata_storage_size (Edm.Int64) は、BLOB のサイズ (バイト単位) です。

• metadata_storage_content_md5 (Edm.String) は、BLOB コンテンツの MD5 ハッシュ (使用可能な場合) です。

• metadata_storage_sas_token (Edm.String) は、 カスタム スキル が BLOB へのアクセスに使用できる一時的な SAS トークンです。 有効期限が切れる可能性があるため、後で使用するためにこのトークンを格納しないでください。

カスタムおよびコンテンツ固有のメタデータ

カスタムまたはユーザー定義の BLOB メタデータの場合は、BLOB のメタデータ キーとまったく同じ名前のフィールドを定義します。 たとえば、BLOB に値がSensitivityメタデータ キーHighがある場合は、インデックスにSensitivity型のEdm.Stringという名前のフィールドを定義します。

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

データ ソースを定義する

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

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

   {
       "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>" }
   }
   

2. type を azureblob に設定します (必須)。

3. credentialsを Azure Storage 接続文字列に設定します。 続く部分は、サポートされている形式を記述します。

4. containerを BLOB コンテナーに設定し、queryを使用してサブフォルダーを指定します。

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

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

インデクサーは、次の接続を使用して BLOB コンテナーに接続できます。

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

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

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

   POST https://[service name].search.windows.net/indexes?api-version=2026-04-01
   {
       "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 },        
       ]
   }
   

2. ドキュメント キー フィールド ("key": true) を作成します。 BLOB コンテンツの場合、候補として最適なのはメタデータ プロパティです。

   • metadata_storage_path (既定値) は、オブジェクトまたはファイルへの完全なパスです。 キー フィールド (この例ではID ) には、既定値であるため、metadata_storage_pathの値が設定されます。

   • metadata_storage_name は、名前が一意の場合にのみ使用できます。 このフィールドをキーとして必要とする場合は、"key": true をこのフィールド定義に移動します。

   • BLOB に追加するカスタム メタデータ プロパティ。 この方法を選んだ場合、BLOB のアップロード プロセスで、該当するメタデータのプロパティをすべての BLOB に追加する必要があります。 キーは必須プロパティであるため、値が不足している BLOB にはインデックスを作成できません。 カスタム メタデータ プロパティをキーとして使用する場合は、そのプロパティを変更しないでください。 キー プロパティが変更された場合、インデクサーは同じ BLOB に重複するドキュメントを追加します。

   メタデータ プロパティには、ドキュメント キーとして無効な文字 (/ や - など) が含まれていることがよくあります。 ただし、インデクサーはキー メタデータ プロパティを自動的にエンコードします。構成やフィールド マッピングは必要ありません。

3. BLOB の content プロパティを使用して、各ファイルから抽出されたテキストを格納するcontent フィールドを追加します。 この名前を使用する必要はありませんが、それを使用することで、暗黙的なフィールド マッピングを利用できます。

4. 標準メタデータ プロパティのフィールドを追加します。 インデクサーは、カスタム メタデータ プロパティ、標準メタデータ プロパティ、コンテンツ固有メタデータ プロパティを読み取ることができます。

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

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

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

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

2. 既定の (10 個のドキュメント) で使用可能なリソースの使用率が低いか、過剰になる場合は、 batchSize を設定します。 既定のバッチ サイズは、データ ソースによって異なります。 BLOB のインデックス作成では、より大きな平均ドキュメント サイズを認識して、バッチ サイズが 10 のドキュメントに設定されます。

3. configurationで、ファイルの種類に基づいてインデックス化する BLOB を制御するか、未指定のままにするとすべての BLOB を取得します。

   indexedFileNameExtensions には、ファイル拡張子のコンマ区切りリストを指定します (先頭にドットを付けます)。 excludedFileNameExtensionsで、インデクサーがスキップする拡張機能を指定する場合も同じ操作を行います。 同じ拡張子が両方のリストにある場合、インデクサーによってインデックス作成から除外されます。

4. configurationの下で、どのBLOBの部分をインデックス化するかを制御するためにdataToExtractを設定します。

   • contentAndMetadata は、インデクサーが BLOB から抽出されたすべてのメタデータとテキスト コンテンツにインデックスを作成することを指定します。 これが既定値です。

   • storageMetadata は、インデクサーが 標準の BLOB プロパティとユーザー指定のメタデータのみをインデックス化することを指定します。

   • allMetadata は、BLOB コンテンツからインデクサーを抽出し、標準の BLOB プロパティと見つかったコンテンツの種類に対するメタデータをインデックス化することを指定します。

   • 使用可能な標準メタデータ プロパティとそのフィールドの種類の完全な一覧については、「 BLOB メタデータのインデックス作成」を参照してください。

5. [ configurationでparsingModeを設定する。 既定の解析モードは、BLOB ごとに 1 つの検索ドキュメントです。 BLOB がプレーン テキストの場合は、プレーン テキスト解析に切り替えることで、パフォーマンスを向上させることができます。 BLOB を複数の検索ドキュメントにマップするより詳細な解析が必要な場合は、別のモードを指定します。 一対多の解析は、以下で構成される BLOB でサポートされています。

   • JSON ドキュメント
   • CSV ファイル

6. フィールドの名前または種類に違いがある、または検索インデックスで複数のソース フィールドのバージョンが必要な場合、フィールド マッピングを定義します。

   BLOB インデックス作成では、インデクサーに content プロパティとメタデータ プロパティをインデックス内の同様の名前付きフィールドと型指定されたフィールドにマッピングするための組み込みのサポートがあるため、フィールド マッピングを省略できることがよくあります。 メタデータ プロパティの場合、インデクサーにより検索インデックスでハイフン - は自動的にアンダースコアに置き換えられます。

7. その他のプロパティについては、「インデクサーの作成方法」を参照してください。 パラメーターの説明の完全な一覧については、REST API を参照してください。

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

複数の Azure Blob コンテナーのデータを 1 つのインデックスにインデックス化する

インデクサーでインデックスを作成できるのは、1 つのコンテナーからのみであることに注意してください。 複数のコンテナーのデータにインデックスを作成し、1 つの AI Search インデックスに統合する必要がある場合は、すべて同じインデックスを指す複数のインデクサーを構成します。 SKU ごとに使用できるインデクサーの最大数に注意してください。

たとえば、2 つのインデクサーを使用して、 my-blob-datasource1 と my-blob-datasource2という名前の 2 つの異なるデータ ソースからデータをプルできます。 それぞれのデータ ソースが別個の Azure BLOB コンテナーを指していますが、どちらも my-search-index という名前の同じインデックスに送られます。

最初のインデクサー定義の例:

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

並列で実行される 2 番目のインデクサー定義の例:

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

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

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-04-01
  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 個が含まれます。 エントリは時系列の逆順に並べ替えられるため、最新の実行が最初に行われます。

Troubleshooting

このセクションでは、不足しているメタデータ値と一般的な BLOB インデックス作成エラーを診断します。

検索結果のメタデータ フィールドが null である

検索結果のメタデータ フィールドに null または空の値が表示される場合は、次のチェックリストを使用します。

1. インデックス スキーマにフィールドが存在するかどうかを確認します 。キャプチャするメタデータ プロパティごとにフィールドを定義したことを確認します。 インデックスに対して GET 要求を実行して、フィールドが存在することを確認します。

2. 正しいフィールド名を使用します。標準的な BLOB プロパティの場合は、metadata_storage_pathの代わりにアンダースコア付き名前 (metadata-storage-path など) を使用します。 カスタム メタデータの場合、フィールド名は BLOB のメタデータ キーと正確に一致する必要があります。

3. インデクサーが正しく設定 dataToExtract 確認します。

   • contentAndMetadata (既定値) は、コンテンツと標準/カスタムメタデータの両方を抽出します。
   • storageMetadata では、標準の BLOB プロパティとカスタム メタデータのみが抽出されます。
   • allMetadata では、標準プロパティとコンテンツ タイプ固有のメタデータが抽出されます。

   インデクサーの構成を確認して、設定が意図と一致していることを確認します。

4. スキーマの更新後にインデクサーを再実行します 。インデックスに新しいフィールドを追加した場合は、更新されたスキーマに対してドキュメントが処理されるように、インデクサーをもう一度実行します。 新しいフィールドが設定される前に、既存のドキュメントを再処理する必要がある場合があります。

5. インデクサーの実行履歴を確認します。Azure ポータルでインデクサーに移動するか、インデクサーの状態の取得 (REST API) を使用して実行の詳細とエラー メッセージを表示します。

インデクサーのエラーとサポートされていないコンテンツ タイプ

既定では、BLOB インデクサーは、オーディオ ファイルなど、サポートされていないコンテンツ タイプの BLOB が検出されるとすぐに停止します。 excludedFileNameExtensions パラメーターを使用して特定のコンテンツの種類をスキップできます。

一部のドキュメントが失敗したときにインデックス作成を続行する場合は、次のパラメーターを調整してから、後で個々のドキュメントを調査します。 詳細については、 インデクサーのトラブルシューティング ガイダンス と インデクサーのエラーと警告を参照してください。

エラーが発生すると、5 つのインデクサー パラメーターによってインデクサーの応答が制御されます。

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

関連コンテンツ

• 変更検出と削除検出
• 大規模なデータ セットにインデックスを作成する
• Azure ネットワーク セキュリティ機能を使用したデータ ソースへのインデクサーのアクセス