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

[アーティクル]
12/13/2023

重要

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

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

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

前提条件

Azure Files、トランザクション最適化レベル。
ソースコンテンツを提供する SMB ファイル共有。 NFS 共有はサポートされていません。
テキストを含むファイル。バイナリデータがある場合は、画像分析向けに AI エンリッチメントを含めることができます。
Azure Storage に対する読み取りアクセス許可。 "フルアクセス" 接続文字列には、コンテンツへのアクセスを許可するキーが含まれています。
この記事に示すような REST 呼び出しを作成する場合は、REST クライアントを使用します。

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

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

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
郵便番号

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

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

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

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

データソースを定義する

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

データソースを作成または更新してデータソースを定義し、"type" が "azurefile" のプレビュー API 2020-06-30-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>" }
}

"type" を "azurefile" に指定します (必須)。
"credentials" を Azure Storage 接続文字列に設定します。続く部分は、サポートされている形式を記述します。
"container" をルートファイル共有に設定し、"query" を使用してサブフォルダーを指定します。

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

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

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

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

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

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

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

POST /indexes?api-version=2020-06-30
{
  "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 }        
  ]
}

ドキュメントキーフィールド ("key": true) を作成します。 BLOB コンテンツの場合、候補として最適なのはメタデータプロパティです。メタデータプロパティには、ドキュメントキーとして無効な文字 (/ や - など) が含まれていることがよくあります。インデクサーには "base64EncodeKeys" プロパティ (規定値は true) があるため、構成やフィールドマッピングをしなくても、メタデータプロパティは自動的にエンコードされます。
- metadata_storage_path (既定) オブジェクトまたはファイルへの完全なパス
- metadata_storage_name 名前が一意である場合にのみ使用可能
- BLOB に追加するカスタムメタデータプロパティ。この方法を選んだ場合、BLOB のアップロードプロセスで、該当するメタデータのプロパティをすべての BLOB に追加する必要があります。キーは必須のプロパティであるため、値が欠落している BLOB については、インデックスが一切作成されません。カスタムメタデータプロパティをキーとして使用する場合は、そのプロパティを変更しないでください。キープロパティが変更されると、インデクサーでは同じ BLOB に対して重複したドキュメントを追加します。
"content" フィールドを追加して、各ファイルから抽出されたテキストを BLOB の "content" プロパティを通して格納します。この名前を使用する必要はありませんが、そうすることで暗黙的なフィールドマッピングを利用できます。
標準メタデータプロパティのフィールドを追加します。ファイルのインデックス作成では、標準メタデータプロパティは 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 インデクサーを構成して実行する

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

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

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
{
  "name" : "my-file-indexer",
  "dataSourceName" : "my-file-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
     "batchSize": null,
     "maxFailedItems": null,
     "maxFailedItemsPerBatch": null,
     "base64EncodeKeys": null,
     "configuration": {
        "indexedFileNameExtensions" : ".pdf,.docx",
        "excludedFileNameExtensions" : ".png,.jpeg" 
    }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

省略可能な "configuration" セクションで一致条件または除外条件を指定します。指定されていない場合は、ファイル共有内のすべてのファイルが取得されます。

indexedFileNameExtensions と excludedFileNameExtensions の両方のパラメーターがある場合、Azure AI Search では最初に indexedFileNameExtensions を調べ、次に excludedFileNameExtensions を調べます。同じファイル拡張子が両方の一覧にある場合、インデックス作成から除外されます。
フィールドの名前または種類に違いがある、または検索インデックスで複数のソースフィールドのバージョンが必要な場合、フィールドマッピングを定義します。

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

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

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

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  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 からコンテンツをプルするインデクサーを使用する場合に参照できます。

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