次の方法で共有

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

  • [アーティクル]

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

このインデクサーを構成して実行するには、次を使用します。

この記事では、REST API を使用して各手順を説明します。

前提条件

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

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

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

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

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

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

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

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

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

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

インデックスを作成する 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 インデックス タグのインデックス作成は、このインデクサーではサポートされていません。

データ ソースを定義する

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

  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 コンテナーへの接続に使用される接続は次のとおりです。

フル アクセス ストレージ アカウントの接続文字列
{ "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 のコンテンツとメタデータを受け入れるためのフィールドを追加します。

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

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

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

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

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

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

    POST https://[service name].search.windows.net/indexers?api-version=2024-07-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" の下で、"dataToExtract" を設定して、インデックスが作成される BLOB の部分を制御します。

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

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

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

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

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

複数の Azure BLOB コンテナーのデータにインデックスを作成し、1 つのインデックスに統合する

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

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

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

POST https://[service name].search.windows.net/indexers?api-version=2024-07-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=2024-07-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=2024-07-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 件が含まれます。時系列の逆の順に並べられるため、最後の実行が最初に表示されます。

エラーの処理

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

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

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

PUT /indexers/[indexer name]?api-version=2024-07-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 サイズの制限については、「サービスの制限」を参照してください。

関連項目