Azure Data Lake Storage Gen2 からのデータのインデックス作成

Azure Data Lake Storage Gen2 インデクサーは、Azure Data Lake Storage Gen2 (ADLS Gen2) からAzure AI 検索 インデックスにコンテンツをインポートします。 インデクサーへの入力は、1 つのコンテナー内の BLOB です。 出力は、検索可能なコンテンツとメタデータが個々のフィールドに格納される検索インデックスです。

この記事では、ADLS Gen2 からのインデックス作成に固有の情報を使用して インデクサーを作成 する方法について説明します。 REST API を使用して、すべてのインデクサーに共通する 3 部構成のワークフロー (データ ソースの作成、インデックスの作成、インデクサーの作成) を示します。 データ抽出は、インデクサーの作成要求を送信したときに発生します。

C# のコード サンプルについては、GitHub の Microsoft Entra ID を使用した Data Lake Gen2 のインデックス作成 に関するページを参照してください。

[前提条件]

• 階層型名前空間が有効な ADLS Gen2。 ADLS Gen2 は、Azure Storage を通じて利用できます。 ストレージ アカウントを設定する場合は、 階層型名前空間を有効にして、ファイルをディレクトリと入れ子になったサブディレクトリの階層に編成することができます。 階層型名前空間を有効にすると、ADLS Gen2 が有効になります。

• ADLS Gen2 のアクセス層には、ホット、クール、アーカイブが含まれます。 検索インデクサーからアクセスできるのはホットとクールのみです。

• テキストを含む BLOB。 バイナリ データがある場合は、画像分析向けに AI エンリッチメントを含めることができます。 BLOB コンテンツは、検索サービス レベルの インデクサーの制限 を超えることはできません。

  ソース インデックス作成と AI エンリッチメントを個別の処理ステージとして扱います。 スキルまたは外部サービスは、インデクサーが抽出できるコンテンツの量よりも低い入力制限を持つことができます。 スキルセットの 各スキルのリファレンス記事 を確認します。

• Azure Storage に対する読み取りアクセス許可。 "フル アクセス" 接続文字列には、コンテンツへのアクセスを許可するキーが含まれていますが、代わりに Azure ロールを使用している場合は、 検索サービスのマネージド ID に ストレージ BLOB データ閲覧者 のアクセス許可があることを確認します。

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

制限事項

• BLOB インデクサーとは異なり、ADLS Gen2 インデクサーは、ストレージ アカウントからのコンテンツの列挙とインデックス作成にコンテナー レベルの SAS トークンを使用できません。 この制限は、インデクサーが ファイルシステム - Get プロパティ API を呼び出して、ストレージ アカウントに階層型名前空間が有効になっているかどうかを確認するためです。 階層型名前空間が有効になっていないストレージ アカウントの場合は、代わりに BLOB インデクサー を使用して、BLOB のパフォーマンスの高い列挙を確保します。

• プロパティ metadata_storage_path がインデックス キー フィールドにマップされている場合、BLOB はディレクトリ名の変更時にインデックスが再作成されるとは限りません。 名前が変更されたディレクトリの一部である BLOB のインデックスを再作成する場合は、すべての LastModified タイムスタンプを更新します。

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

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

• 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 をスキップする場合は、Blob Storage 内の BLOB に次のメタデータのプロパティと値を追加できます。 インデクサーでこのプロパティが検出されると、インデックス作成の実行時に BLOB またはそのコンテンツがスキップされます。

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

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

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

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

BLOB メタデータのインデックスを作成できます。これは、標準またはカスタムのメタデータ プロパティのいずれかがフィルターやクエリに役立つと考える場合に役立ちます。

ユーザーが指定したメタデータ プロパティは、そのまま抽出されます。 値を受け取る場合は、BLOB のメタデータ キーと同じ名前を持つ Edm.String 型の検索インデックスにフィールドを定義する必要があります。 たとえば、BLOB に値がSensitivityHighという名前のメタデータ キーがある場合は、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 検索 が特定するために、このタイムスタンプが使用されます。

• metadata_storage_size (Edm.Int64) - BLOB のサイズ (バイト単位)。

• metadata_storage_content_md5 (Edm.String) - BLOB コンテンツの MD5 ハッシュ (利用可能な場合)。

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

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

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

データ ソースを定義する

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

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

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

2. "type" を "adlsgen2" に指定します (必須)。

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

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

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

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

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

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

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

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

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

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

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

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

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

   {
     "name" : "my-adlsgen2-indexer",
     "dataSourceName" : "my-adlsgen2-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" の下で、"dataToExtract" を設定して、インデックスが作成される BLOB の部分を制御します。

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

   • "storageMetadata" には、標準的な BLOB のプロパティおよびユーザー指定のメタデータのみにインデックスを作成するように指定します。

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

5. BLOB を 複数の検索ドキュメントにマップする必要がある場合、または BLOB がプレーン テキスト、 JSON ドキュメント、または CSV ファイルで構成されている場合は、[構成] で "parsingMode" を設定します。

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

   BLOB のインデックス作成では、多くの場合、フィールド マッピングを省略できます。インデクサーには、"content" プロパティとメタデータ プロパティを、インデックス内の似たような名前と種類のフィールドにマッピングするためのサポートが組み込まれているためです。 メタデータ プロパティの場合、インデクサーはハイフン - を検索インデックスでアンダースコアに自動的に置き換えます。

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

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

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

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

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":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-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=2026-04-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}

次のステップ

これでインデクサーの実行、状態の監視、インデクサーの実行のスケジュール設定を行うことができます。 次の記事は、Azure Storage からコンテンツをプルするインデクサーを使用する場合に参照できます。

• 変更検出と削除検出
• 大規模なデータ セットにインデックスを作成する
• C# サンプル: Microsoft Entra ID を使用して Data Lake Gen2 のインデックスを作成する