Azure Files のインデックス データ
重要
Azure Files インデクサーは、現在、追加の使用条件の下でパブリック プレビュー段階にあります。 プレビュー REST API を使用してインデクサー データ ソースを作成します。
この記事では、インデクサーを構成する方法について学習します。これにより、Azure Files からコンテンツをインポートし、Azure AI Search でそれを検索できるようになります。 インデクサーへの入力は、1 つの共有内のファイルです。 出力は、検索可能なコンテンツとメタデータが個々のフィールドに格納される検索インデックスです。
このインデクサーを構成して実行するには、次を使用します。
- Search Service プレビュー REST API、すべてのプレビュー バージョン。
- Azure SDK パッケージ、すべてのバージョン。
- Azure portal のデータのインポート ウィザード。
- Azure portal のデータのインポートとベクトル化ウィザード。
前提条件
Azure Files、トランザクション最適化レベル。
ソース コンテンツを提供する SMB ファイル共有。 NFS 共有はサポートされていません。
テキストを含むファイル。 バイナリ データがある場合は、画像分析向けに AI エンリッチメントを含めることができます。
Azure Storage に対する読み取りアクセス許可。 "フル アクセス" 接続文字列には、コンテンツへのアクセスを許可するキーが含まれています。
この記事に示すような REST 呼び出しを作成する場合は、REST クライアントを使用します。
サポートされているタスク
このインデクサーは、次のタスクに使用できます。
- データのインデックス作成と増分インデックス作成: このインデクサーを使用すると、表のファイルと関連メタデータにインデックスを作成できます。 組み込みの変更検出を使用して、新しいファイルと更新されたファイルとメタデータを検出します。 スケジュールまたはオンデマンドでデータ更新を構成できます。
- 削除の検出: このインデクサーを使用すると、カスタム メタデータを使用して削除を検出できます。
- スキルセットを使用した Applied AI: このインデクサーはスキルセットを完全にサポートしています。 これには、データ チャンクと埋め込み手順を追加する統合ベクター化などの主要な機能が含まれます。
- 解析モード: インデクサーは、JSON 配列または行を個々の検索ドキュメントに解析する場合に JSON 解析モードをサポートします。 また、Markdown 解析モードもサポートしています。
- 他の機能との互換性: このインデクサーは、他のインデックス作成機能 (デバッグ セッション、増分エンリッチメント用のインデクサー キャッシュ、ナレッジ ストアなど) とシームレスに連携するように設計されています。
サポートされるドキュメントの形式
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
- プレーンテキスト ファイル (「プレーン テキストのインデックス作成」も参照)
- RTF
- XML
- 郵便番号
Azure Files のインデックス作成方法
既定では、1 つのテキスト チャンクとしてインデックスが作成される、JSON や CSV などの構造化コンテンツを持つファイルを含め、ほとんどのファイルはインデックス内で 1 つの検索ドキュメントとしてインデックスが作成されます。
複合または埋め込みドキュメント (ZIP アーカイブ、添付ファイルが含まれている Outlook メールが埋め込まれた Word 文書、添付ファイル付き .MSG ファイルなど) も、1 つのドキュメントとして、インデックスが作成されます。 例えば、.MSG ファイルの添付ファイルから抽出されたすべての画像が normalized_images フィールドに返されます。 画像がある場合は、そのコンテンツからさらに検索ユーティリティを取得するために AI エンリッチメントを追加することを検討してください。
ドキュメントのテキスト コンテンツが、"content" という名前の文字列フィールドに抽出されます。 標準およびユーザー定義のメタデータを抽出することもできます。
データ ソースを定義する
データ ソース定義では、インデックスを付けるデータ、資格情報、データの変更を識別するためのポリシーを指定します。 データ ソースは、複数のインデクサーで使用できるように、独立したリソースとして定義します。
"type": "azurefile"
に対しては 2020-06-30-preview 以降を使用できます。 最新のプレビュー API をお勧めします。
"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>" } }
"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=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 } ] }
ドキュメント キー フィールド ("key": true) を作成します。 BLOB コンテンツの場合、候補として最適なのはメタデータ プロパティです。 メタデータ プロパティには、ドキュメント キーとして無効な文字 (
/
や-
など) が含まれていることがよくあります。 インデクサーはキー メタデータ プロパティを自動的にエンコードし、構成やフィールドのマッピングは必要ありません。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 トークン。 このトークンは、有効期限が切れる可能性があるため、後で使用するために保存しないでください。
- metadata_storage_name (
Azure Files インデクサーを構成して実行する
インデックスとデータ ソースを作成したら、インデクサーを作成できます。 インデクサーの構成では、実行時の動作を制御する入力、パラメーター、プロパティを指定します。
名前を指定し、データ ソースとターゲット インデックスを参照することで、インデクサーを作成または更新します。
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" : [ ] }
省略可能な "configuration" セクションで一致条件または除外条件を指定します。 指定されていない場合は、ファイル共有内のすべてのファイルが取得されます。
indexedFileNameExtensions
とexcludedFileNameExtensions
の両方のパラメーターがある場合、Azure AI Search では最初にindexedFileNameExtensions
を調べ、次にexcludedFileNameExtensions
を調べます。 同じファイル拡張子が両方の一覧にある場合、インデックス作成から除外されます。フィールドの名前または種類に違いがある、または検索インデックスで複数のソース フィールドのバージョンが必要な場合、フィールド マッピングを定義します。
ファイルのインデックス作成では、多くの場合、フィールド マッピングを省略できます。インデクサーには、"content" プロパティとメタデータ プロパティを、インデックス内の似たような名前と種類のフィールドにマッピングするためのサポートが組み込まれているためです。 メタデータ プロパティの場合、インデクサーにより検索インデックスでハイフン
-
は自動的にアンダースコアに置き換えられます。その他のプロパティについては、「インデクサーの作成方法」を参照してください。
インデクサーは、作成されると自動的に実行されます。 これを防ぐには、"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 からコンテンツをプルするインデクサーを使用する場合に参照できます。