Azure Files のインデックス データ

重要

Azure Files インデクサーは、現在、追加の使用条件の下でパブリック プレビュー段階にあります。 プレビュー REST API を使用してインデクサー データ ソースを作成します。

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

インデクサーの作成」について補足するこの記事では、Azure Storage 内のファイルのインデックス作成に固有の情報を扱います。 REST API を使用して、すべてのインデクサーに共通する 3 部構成のワークフロー (データ ソースの作成、インデックスの作成、インデクサーの作成) を示します。 データ抽出は、インデクサーの作成要求を送信したときに発生します。

前提条件

  • Azure Files、トランザクション最適化レベル。

  • ソース コンテンツを提供する SMB ファイル共有NFS 共有はサポートされていません。

  • テキストを含むファイル。 バイナリ データがある場合は、画像分析向けに AI エンリッチメントを含めることができます。

  • Azure Storage に対する読み取りアクセス許可。 "フル アクセス" 接続文字列には、コンテンツへのアクセスを許可するキーが含まれています。

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

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

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

Azure Files のインデックス作成方法

既定では、1 つのテキスト チャンクとしてインデックスが作成される、JSON や CSV などの構造化コンテンツを持つファイルを含め、ほとんどのファイルはインデックス内で 1 つの検索ドキュメントとしてインデックスが作成されます。

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

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

データ ソースを定義する

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

"type": "azurefile" に対しては 2020-06-30-preview 以降を使用できます。 最新のプレビュー API をお勧めします。

  1. "type": "azurefile" に対してプレビュー API を使用してデータ ソースを作成してその定義を設定します。

    POST /datasources?api-version=2024-05-01-preview
    {
        "name" : "my-file-datasource",
        "type" : "azurefile",
        "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
        "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
    }
    
  2. "type" を "azurefile" に指定します (必須)。

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

  4. "container" をルート ファイル共有に設定し、"query" を使用してサブフォルダーを指定します。

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

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

インデクサーがテーブルへの接続に使用する接続は次のとおりです。

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

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

検索インデックスでは、Azure ファイルのコンテンツとメタデータを検出するフィールドを追加します。

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

    POST /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_path", "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": true, "filterable": true, "sortable": true }        
      ]
    }
    
  2. ドキュメント キー フィールド ("key": true) を作成します。 BLOB コンテンツの場合、候補として最適なのはメタデータ プロパティです。 メタデータ プロパティには、ドキュメント キーとして無効な文字 (/- など) が含まれていることがよくあります。 インデクサーはキー メタデータ プロパティを自動的にエンコードし、構成やフィールドのマッピングは必要ありません。

    • metadata_storage_path (既定) オブジェクトまたはファイルへの完全なパス

    • metadata_storage_name 名前が一意である場合にのみ使用可能

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

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

  4. 標準メタデータ プロパティのフィールドを追加します。 ファイルのインデックス作成では、標準メタデータ プロパティは BLOB メタデータ プロパティと同じです。 Azure Files インデクサーにより、これらのプロパティの内部フィールド マッピングが自動的に作成され、ハイフンでつながれたプロパティ名が下線付きプロパティ名に変換されます。 なお、インデックス定義を使用するには、必要なフィールドを追加する必要がありますが、データ ソースでのフィールド マッピングの作成は省略できます。

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

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

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

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

    POST /indexers?api-version=2024-07-01
    {
      "name" : "my-file-indexer",
      "dataSourceName" : "my-file-datasource",
      "targetIndexName" : "my-search-index",
      "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null,
         "configuration": {
            "indexedFileNameExtensions" : ".pdf,.docx",
            "excludedFileNameExtensions" : ".png,.jpeg" 
        }
      },
      "schedule" : { },
      "fieldMappings" : [ ]
    }
    
  2. 省略可能な "configuration" セクションで一致条件または除外条件を指定します。 指定されていない場合は、ファイル共有内のすべてのファイルが取得されます。

    indexedFileNameExtensionsexcludedFileNameExtensions の両方のパラメーターがある場合、Azure AI Search では最初に indexedFileNameExtensions を調べ、次に excludedFileNameExtensions を調べます。 同じファイル拡張子が両方の一覧にある場合、インデックス作成から除外されます。

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

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

  4. その他のプロパティについては、「インデクサーの作成方法」を参照してください。

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

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

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

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 件が含まれます。時系列の逆の順に並べられるため、最後の実行が最初に表示されます。

次のステップ

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