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

[アーティクル]
02/19/2024

この記事では、インデクサーを構成する方法について説明します。こうすると、Azure Data Lake Storage (ADLS) Gen2 からコンテンツをインポートし、Azure AI Search でその検索ができるようになります。インデクサーへの入力は、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 コンテンツは使用できません。
Azure Storage に対する読み取りアクセス許可。 "フルアクセス" の接続文字列には、コンテンツへのアクセスを許可するキーが含まれますが、代わりに Azure ロールを使用している場合は、検索サービスのマネージド ID にストレージ BLOB データ閲覧者のアクセス許可があることを確認してください。
この記事に示すような REST 呼び出しを作成する場合は、REST クライアントを使用します。

Note

ADLS Gen2 では、BLOB レベルで Azure ロールベースのアクセス制御 (Azure RBAC) と POSIX のようなアクセス制御リスト (ACL) の両方をサポートするアクセス制御モデルが実装されています。 Azure AI Search では、ドキュメントレベルのアクセス許可はサポートされていません。インデックスで検索と取得が可能なあらゆるコンテンツに対して、すべてのユーザーに同じアクセスレベルが与えられます。ドキュメントレベルのアクセス許可がアプリケーションの要件である場合は、考えられる解決策としてセキュリティトリミングを検討してください。

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

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

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 つの検索ドキュメントを作成できます。

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

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

データソースを定義する

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

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

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

"type" を "adlsgen2" に指定します (必須)。
"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) にリストおよび読み取りアクセス許可が必要です。

Note

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

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

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

インデックスを作成または更新して、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 }     
    ]
}

ドキュメントキーフィールド ("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" プロパティを通して格納します。この名前を使用する必要はありませんが、そうすることで暗黙的なフィールドマッピングを利用できます。
標準メタデータプロパティのフィールドを追加します。インデクサーは、カスタムメタデータプロパティ、標準メタデータプロパティ、コンテンツ固有メタデータプロパティを読み取ることができます。

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

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

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

{
  "name" : "my-adlsgen2-indexer",
  "dataSourceName" : "my-adlsgen2-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 のコンテンツから抽出し、インデックスを作成するように指定します。
BLOB が複数の検索ドキュメントにマップされる必要がある場合や、プレーンテキスト、JSON ドキュメント、または CSV ファイルで構成されている場合は、"configuration" の下に "parsingMode" を設定します。
フィールドの名前または種類に違いがある、または検索インデックスで複数のソースフィールドのバージョンが必要な場合、フィールドマッピングを定義します。

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

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

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

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-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=2023-11-01
{
  "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 サイズの制限については、「サービスの制限」を参照してください。

制限事項

BLOB インデクサーとは異なり、ADLS Gen2 インデクサーは、ストレージアカウントからのコンテンツの列挙とインデックス作成にコンテナーレベルの SAS トークンを使用できません。これは、インデクサーが、Filesystem - Get properties API を呼び出して、ストレージアカウントで階層型名前空間が有効になっているかどうかを確認するためです。階層型名前空間が有効になっていないストレージアカウントの場合は、代わりに BLOB インデクサーを使用して、BLOB のパフォーマンスの高い列挙を確保することをお勧めします。
プロパティ metadata_storage_path がインデックスキーフィールドになるようにマップされている場合、BLOB はディレクトリ名の変更後にインデックスが再作成される保証はありません。名前が変更されたディレクトリの一部である BLOB のインデックスを再作成する場合は、すべての LastModified タイムスタンプを更新します。

次のステップ

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