インデクサー、スキル、ドキュメントを実行またはリセットする

2025-10-02

Azure AI Search では、インデクサーを実行する方法がいくつかあります。

インデクサーの作成時にすぐに実行します。これは、インデクサーを "無効" 状態で作成しない限り、既定値です。
スケジュールに基づいて実行する: これによって、定期的に実行を呼び出します。
"リセット" あり、またはなしでオンデマンドで実行する。

この記事では、リセットの有無に関係なく、オンデマンドでインデクサーを実行する方法について説明します。また、インデクサーの実行、期間、コンカレンシーについても説明します。

インデクサーが Azure リソースに接続する方法

インデクサーは、他の Azure リソースへの公開の送信呼び出しを行う数少ないサブシステムの 1 つです。外部データソースに応じて、キーまたはロールを使用して接続を認証できます。

Azure ロールに関しては、インデクサーには個別の ID がありません。検索エンジンから別の Azure リソースへの接続は、検索サービスのシステムまたはユーザー割り当てマネージド ID と、ターゲットの Azure リソースに対するロールの割り当てを使用して行われます。インデクサーが仮想ネットワーク上の Azure リソースに接続する場合は、その接続用に共有プライベートリンクを作成する必要があります。

インデクサーの実行

検索サービスは、検索ユニットごとに 1 つのインデクサージョブを実行します。すべての検索サービスは 1 つの検索単位で始まりますが、新しいパーティションまたはレプリカごとにサービスの検索単位が増加します。検索ユニット数は、Azure portal の [概要] ページの [要点] セクションで確認できます。同時処理が必要な場合は、検索ユニットに十分なレプリカが含まれていることをご確認ください。インデクサーはバックグラウンドで実行されないため、サービスに負荷がかかっている場合は、通常よりも多くのクエリ調整が発生する可能性があります。

次のスクリーンショットは、一度に実行できるインデクサーの数を決定する検索単位の数を示しています。

インデクサーの実行が開始されると、一時停止または停止することはできません。インデクサーの実行は、読み込むまたは更新するドキュメントがなくなった場合、あるいは実行時間の上限に達すると停止します。

十分な容量を想定して一度に複数のインデクサーを実行できますが、各インデクサー自体は単一インスタンスです。インデクサーが既に実行されているときに新しいインスタンスを開始すると、エラー "Failed to run indexer "<indexer name>" error: "Another indexer invocation is currently in progress; concurrent invocations are not allowed."が発生します。

インデクサー実行環境

インデクサージョブは、マネージド実行環境で実行されます。現在、次の 2 つの環境があります。

プライベート実行環境は、検索サービスに固有の検索クラスターで実行されます。
マルチテナント環境は、追加料金なしで Microsoft によって管理およびセキュリティ保護されるコンテンツプロセッサを備えています。この環境は、大量のコンピューティング処理を要する処理の負荷を軽減して、サービス固有のリソースをルーチン処理に残しておくために使います。可能な限り、ほとんどのスキルセットはマルチテナント環境で実行されます。これは既定値です。

"計算負荷の高い処理" は、コンテンツプロセッサで実行されているスキルセット、大量のドキュメントや大きなサイズのドキュメントを処理するインデクサージョブを指します。マルチテナントコンテンツプロセッサでの非スキルセット処理は、ヒューリスティックとシステム情報によって決定され、顧客の管理下にありません。

インデクサーとスキルセットの処理を検索クラスターのみにピン留めすることで、Standard2 以降のサービスでマルチテナント環境を使用できないようにすることができます。インデクサー定義の executionEnvironment パラメーターを、プライベート実行環境で常にインデクサーを実行するように設定します。

IP ファイアウォールはマルチテナント環境をブロックするため、ファイアウォールがある場合は、マルチテナントプロセッサ接続を許可する規則を作成します。

インデクサーの制限は、環境ごとに異なります。

Workload	最大期間	最大ジョブ数	実行環境
非公開実行	24 時間	検索ユニットあたり 1 つのインデクサージョブ ¹。	インデックス作成は、バックグラウンドで実行されません。代わりに、検索サービスは、すべてのインデックス作成ジョブを、進行中のクエリやオブジェクト管理アクション (インデックスの作成や更新など) とバランスを取ります。インデクサーを実行する際、インデックスの作成量が多い場合、多少のクエリ待機時間が発生することを見込んでおく必要があります。
Multitenant	2 時間 ²	不確定 ³	コンテンツ処理クラスターはマルチテナントであるため、需要に合わせてコンテンツプロセッサが追加されます。オンデマンドまたはスケジュールされた実行で遅延が発生した場合は、システムがプロセッサを追加しているか、プロセッサが使用可能になるのを待機していることが原因である可能性があります。

¹ 検索ユニットでは、パーティションとレプリカを柔軟に組み合わせることができますが、インデクサージョブはどちらにも関連付けられません。つまり、検索ユニットのデプロイ方法に関係なく、12 個のユニットがある場合には、プライベート実行で同時に 12 個のインデクサージョブを実行できます。

² すべてのデータを処理するために 2 時間以上必要な場合は、変更検出を有効にし、インデクサーを 5 分間隔で実行するようにスケジュールし、タイムアウトのためにインデックス作成が停止した場合にインデックス作成をすばやく再開します。その他の戦略については、大規模なデータセットのインデックス作成を参照してください。

³ "不確定" は、ジョブの数によって制限が定量化されないことを意味します。スキルセット処理などの一部のワークロードは並列で実行できるため、1 つのインデクサーのみが関わっている場合でも多くのジョブが発生する可能性があります。環境で制約が課されない場合でも、検索サービスのインデクサーの制限は適用されます。

リセットなしで実行

インデクサーの実行操作では、検索インデックスを基になるデータソースの変更と同期するために必要なもののみが検出され、処理されます。増分インデックスは、内部の高基準値を見つけて、最後に更新された検索ドキュメントを見つけることから始まります。これは、データソース内の新規および更新されたドキュメントに対するインデクサー実行の開始点になります。

変更の検出は、データソースの新しい内容または更新された内容を判別するために不可欠です。インデクサーは、基になるデータソースの変更の検出機能を使用して、データソースの新しい内容または更新された内容を判別します。

Azure Storage には、LastModified プロパティを利用する組み込みの変更の検出機能があります。
Azure SQL や Azure Cosmos DB などの他のデータソースは、インデクサーで新しいおよび更新された行を読み取る前に変更を検出するように構成する必要があります。

基になる内容が変更されていない場合、実行操作は無効になります。この場合、インデクサーの実行履歴は、処理されたドキュメント 0\0 示します。

完全に再処理するには、次のセクションで説明するようにインデクサーをリセットする必要があります。

インデクサーのリセット

最初の実行後、インデクサーは、内部のハイウォーターマークを使用して、インデックスされた検索ドキュメントを追跡します。このマーカーは公開されませんが、内部でインデクサーは最後に停止した場所を認識します。

インデックスのすべてまたは一部を再構築する必要がある場合は、オブジェクト階層内のレベルを下げる場合に使用できるリセット API を使用します。

インデクサーのリセットによって、高基準値がクリアされ、すべてのドキュメントの完全な再インデックス化が実行される
インデクサーの再同期 (プレビュー) では、すべてのドキュメントの効率的な部分的なインデックス再作成が実行されます
ドキュメントのリセット (プレビュー) によって、特定のドキュメントまたはドキュメントの一覧が再インデックス化される
スキルのリセット (プレビュー) によって、特定のスキルのスキル処理が呼び出される

リセットした後、続いて実行コマンドを発行し、新規および既存のドキュメントを再処理します。データソース内に対応するドキュメントがない孤立した検索ドキュメントは、リセットと実行を使用して削除できません。ドキュメントを削除する必要がある場合は、Documents の Index に関する記事を参照してください。

Note

テーブルを空にすることはできません。 TRUNCATE TABLE を使用して行をクリアすると、インデクサーのリセットと再実行によって、対応する検索ドキュメントは削除されません。孤立した検索ドキュメントを削除するには、削除アクションでインデックスを作成する必要があります。

インデクサーをリセットおよび実行する方法

リセットによって、高基準値はクリアされます。検索インデックス内のすべてのドキュメントには、インライン更新や既存のコンテンツへのマージを行わずに、完全上書きのフラグが設定されます。スキルセットとエンリッチメントキャッシュを使用するインデクサーの場合、インデックスをリセットすると、スキルセットも暗黙的にリセットされます。

実際の作業は、リセットに続いて実行コマンドを発行したときに発生します。

基になるソースが見つかった新しいドキュメントはすべて、検索インデックスに追加されます。
データソースと検索インデックスの両方に存在するすべてのドキュメントは、検索インデックスで上書きされます。
スキルセットに基づいて作成されたエンリッチされたコンテンツはすべて再構築されます。エンリッチメントキャッシュは、有効になっている場合、更新されます。

前述のように、リセットはパッシブ操作です。インデックスを再構築するには、実行要求に従う必要があります。

リセットと実行の操作は、検索インデックスまたはナレッジストア、特定のドキュメントまたはプロジェクション、およびリセットに明示的または暗黙的にスキルが含まれている場合はキャッシュされたエンリッチメントに適用されます。

リセットは、作成操作と更新操作にも適用されます。これによって、検索インデックス内の孤立したドキュメントの削除やクリーンアップはトリガーされません。ドキュメントの削除の詳細については、「Documents - Index」を参照してください。

いったんインデクサーをリセットすると、その操作は元に戻せません。

Azure portal にサインインし、検索サービスページを開きます。
[概要] ページで、[インデクサー] タブを選択します。
インデクサーを選択します。
[リセット] コマンドを選択し、[はい] を選択して、操作を確定します。
ページを更新して状態を表示します。項目を選択すると、その詳細が表示されます。
[実行] を選択してインデクサー処理を開始するか、スケジュールされた次の実行を待ちます。

次の例は、インデクサーのリセットおよびインデクサーの実行 REST 呼び出しを示しています。 インデクサーの状態の取得を使用して結果を確認します。

これらのいずれの呼び出しにも、パラメーターやプロパティはありません。

POST /indexers/[indexer name]/reset?api-version=[api-version]

POST /indexers/[indexer name]/run?api-version=[api-version]

GET /indexers/[indexer name]/status?api-version=[api-version]

次の例 (azure-search-dotnet-samples/multiple-data-sources/ から) は、Azure .NET SDK 内の ResetIndexers および RunIndexers メソッドを示しています。

// Reset the indexer if it already exists
try
{
    await indexerClient.GetIndexerAsync(blobIndexer.Name);
    //Rest the indexer if it exsits.
    await indexerClient.ResetIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404) { }

await indexerClient.CreateOrUpdateIndexerAsync(blobIndexer);

// Run indexer
Console.WriteLine("Running Blob Storage indexer...\n");

try
{
    await indexerClient.RunIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
    Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

スキルをリセットする方法 (プレビュー)

スキルのリセット要求は、次のインデクサー実行で 1 つ以上のスキルを選択的に処理します。スキルセットを持つインデクサーの場合は、個々のスキルをリセットして、そのスキルとその出力に依存するダウンストリームスキルのみを強制的に再処理できます。エンリッチメントキャッシュが有効になっている場合、それも更新されます。

キャッシュが有効になっているインデクサーの場合、インデクサーが検出できないスキル更新の処理を明示的に要求できます。たとえば、カスタムスキルのリビジョンなど、外部の変更を行う場合は、この API を使用してスキルを再実行できます。ナレッジストアや検索インデックスなどの出力は、キャッシュからの再利用可能なデータと、更新されたスキルごとの新しいコンテンツを使用して更新されます。

最新のプレビュー API をお勧めします。

POST /skillsets/[skillset name]/resetskills?api-version=2025-08-01-preview
{
    "skillNames" : [
        "#1",
        "#5",
        "#6"
    ]
}

上記の例に示されているように、個々のスキルを指定することもできます。しかし、それらのスキルのいずれかで、一覧にないスキル (#2 から #4) からの出力が必要な場合は、キャッシュが必要な情報を提供できない限り、一覧にないスキルが実行されます。これが可能であるには、#2 から #4 のスキルのキャッシュされたエンリッチメントが #1 に依存していない必要があります (リセットのためにリストされています)。

スキルが指定されていない場合は、スキルセット全体が実行されます。また、キャッシングが有効になっている場合は、キャッシュも更新されます。

実際の処理を呼び出すには、デクサーを実行することを忘れないでください。

ドキュメントをリセットする方法 (プレビュー)

インデクサー - ドキュメントのリセット (プレビュー) は、特定のドキュメントを更新できるようにドキュメントキーの一覧を受け入れます。リセットパラメーターを指定すると、基になるデータの他の変更には関係なく、リセットパラメーターによってのみ処理対象が決定されます。たとえば、インデクサーの最後の実行後に 20 個の BLOB が追加または更新されたが、1 つのドキュメントのみをリセットした場合、そのドキュメントだけが処理されます。

ドキュメントごとに、検索ドキュメント内のすべてのフィールドがデータソースの値とメタデータで更新されます。更新するフィールドは選択できません。

データソースが Azure Data Lake Storage (ADLS) Gen2 で、BLOB がアクセス許可メタデータに関連付けられている場合、基になるデータのアクセス許可が変更された場合、それらのアクセス許可も検索インデックスに再取り込まれます。詳細については、 ADLS Gen2 インデクサーを使用した ACL および RBAC スコープのインデックス再作成に関するページを参照してください。

ドキュメントがスキルセットによってエンリッチされ、キャッシュされたデータがある場合は、指定されたドキュメントに対してのみスキルセットが呼び出され、再処理されたドキュメントに対してキャッシュが更新されます。

この API を初めてテストするときは、次の API が、動作の検証とテストに役立ちます。最新のプレビュー API をお勧めします。

プレビュー API バージョンのインデクサー - 状態の取得を呼び出して、リセットの状態と実行の状態を確認します。状態応答の最後でリセット要求に関する情報を確認できます。
プレビュー API バージョンのインデクサー - ドキュメントのリセットを呼び出して、処理するドキュメントを指定します。
```
POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2025-08-01-preview
{
    "documentKeys" : [
        "1001",
        "4452"
    ]
}
```
- API は、2 種類のドキュメント識別子を入力として受け入れます。検索インデックス内のドキュメントを一意に識別するドキュメントキーと、データソース内のドキュメントを一意に識別するデータソースドキュメント識別子です。本文には、ドキュメントキーの一覧 または インデクサーがデータソースで検索するデータソースドキュメント識別子の一覧が含まれている必要があります。 API を呼び出すと、インデクサーメタデータにリセットするドキュメントキーまたはデータソースドキュメント識別子が追加されます。インデクサーの次回のスケジュールされた実行またはオンデマンド実行では、インデクサーはリセットドキュメントのみを処理します。
- ドキュメントキーを使用してドキュメントをリセットし、ドキュメントキーがインデクサーフィールドマッピングで参照されている場合、インデクサーはフィールドマッピングを使用して基になるデータソース内の適切なフィールドを検索します。
- 要求で提供されるドキュメントキーは検索インデックスの値であり、データソース内の対応するフィールドとは異なる場合があります。キーの値がわからない場合は、クエリを送信して値を返します。 select を使用すると、ドキュメントキーフィールドのみを返すことができます。
- 複数の検索ドキュメントに解析される BLOB の場合 (たとえば、parsingMode が jsonLines または jsonArrays、あるいは delimitedText に設定されている場合)、ドキュメントキーがインデクサーによって生成され、ユーザーにはわからないことがあります。このシナリオでは、ドキュメントキーが正しい値を返すクエリです。
- インデクサーでリセットドキュメントの処理を停止する場合は、"documentKeys" または "datasourceDocumentIds" を空のリスト "[]" に設定できます。これにより、インデクサーは高い基準に基づいて通常のインデックス作成を再開します。無効なドキュメントキーまたは存在しないドキュメントキーは無視されます。
インデクサーの実行 (任意の API バージョン) を呼び出して、指定したドキュメントを処理します。これらの特定のドキュメントのみがインデックス化されます。
2 回目のインデクサーの実行を呼び出して、最後の高基準値から処理します。
ドキュメントの検索を呼び出して、更新された値を確認します。また、値がわからない場合は、ドキュメントキーを返します。応答に表示するフィールドを制限する場合は、"select": "<field names>" を使用します。

ドキュメントキーリストの上書き

異なるキーを使用して、ドキュメントのリセット API を複数回呼び出すと、ドキュメントキーのリセットの一覧に新しいキーが追加されます。 overwrite パラメーターを true に設定して API を呼び出すと、現在の一覧が新しい一覧で上書きされます。

POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2025-08-01-Preview
{
    "documentKeys" : [
        "200",
        "630"
    ],
    "overwrite": true
}

インデクサーを再同期する方法 (プレビュー)

再同期インデクサーは、すべてのドキュメントの部分的なインデックス再作成を実行するプレビュー REST API です。インデクサーは、ターゲットインデックス内のすべてのドキュメントの特定のフィールドがデータソース内のデータと一致している場合、そのデータソースと同期されていると見なされます。通常、インデクサーは最初の実行が成功した後に同期を実行します。ドキュメントがデータソースから削除された場合、インデクサーはこの定義に従って同期されたままになります。ただし、次のインデクサーの実行中に、削除の追跡が有効になっている場合、ターゲットインデックス内の対応するドキュメントが削除されます。

データソースでドキュメントが変更されると、インデクサーは同期されません。一般に、変更追跡メカニズムは、次の実行時にインデクサーを再同期します。たとえば、Azure Storage では、BLOB を変更すると最後に変更された時刻が更新され、更新された時間が前回の実行で設定された高基準を超えるため、後続のインデクサー実行でインデックスが再作成されます。

これに対し、ADLS Gen2 などの特定のデータソースでは、BLOB のアクセス制御リスト (ACL) を変更しても、最終変更時刻は変更されません。ACL を取り込む場合、変更の追跡をレンダリングしても効果がありません。そのため、変更後の BLOB は、最後の高基準値の後に変更されたドキュメントのみが処理されるため、後続の実行ではインデックスが再作成されません。

"reset" または "reset docs" を使用するとこの問題に対処できますが、"リセット" は時間がかかり、大規模なデータセットでは非効率的な場合があり、"ドキュメントのリセット" には更新を目的とした BLOB のドキュメントキーを識別する必要があります。

インデクサーを再同期すると、効率的で便利な代替手段が提供されます。ユーザーはインデクサーを再同期モードにし、再同期インデクサー API を呼び出して再同期するコンテンツを指定するだけです。次の実行では、インデクサーはソース内のデータの関連部分のみを検査し、指定されたデータに関連しない不要な処理を回避します。また、ターゲットインデックス内の既存のドキュメントに対してクエリを実行し、データソースとターゲットインデックスの間の不一致を示すドキュメントのみを更新します。再同期の実行後、インデクサーは同期され、後続の実行では通常のインデクサー実行モードに戻ります。

インデクサーを再同期して実行する方法

インデクサーを呼び出す - プレビュー API バージョンと再同期して、再同期するコンテンツを指定します。
```
POST https://[service name].search.windows.net/indexers/[indexer name]/resync?api-version=2025-08-01-preview
{
    "options" : [
        "permissions"
    ]
}
```
- options フィールドは必須です。現在サポートされている唯一のオプションは permissionsです。つまり、ターゲットインデックス内のアクセス許可フィルターフィールドのみが更新されます。
インデクサーの実行 (任意の API バージョン) を呼び出して、インデクサーを再同期します。
2 回目のインデクサーの実行を呼び出して、最後の高基準値から処理します。

リセット状態 "currentState" を確認する

リセット状態を確認し、処理のためにキューに入れられたドキュメントキーを確認するには、次の手順を行います。

プレビュー API のインデクサー - 状態の取得を呼び出します。

プレビュー API は、currentState セクションを返します。これは、応答の最後にあります。

"currentState": {
    "mode": "indexingResetDocs",
    "allDocsInitialTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
    "allDocsFinalTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
    "resetDocsInitialTrackingState": null,
    "resetDocsFinalTrackingState": null,
    "resyncInitialTrackingState": null,
    "resyncFinalTrackingState": null,
    "resetDocumentKeys": [
        "200",
        "630"
    ]
}

"モード" を確認します。

スキルのリセットの場合は "モード" を indexingAllDocs に設定する必要があります (AI エンリッチメントで設定されるフィールドについてはすべてのドキュメントが影響を受ける可能性があるため)。

再同期インデクサーの場合は、"mode" を indexingResync に設定する必要があります。インデクサーはすべてのドキュメントをチェックし、対象のデータソースのデータとターゲットインデックスの対象フィールドに重点を置いています。

ドキュメントのリセットの場合は、"モード" を indexingResetDocs に設定する必要があります。ドキュメントのリセット呼び出しで指定されたすべてのドキュメントキーが処理されるまで (この操作の進行中、他のインデクサージョブは実行されません)、インデクサーはこの状態を保持します。ドキュメントキーリスト内のすべてのドキュメントを見つけるには、各ドキュメントを解読してキーを特定し、一致させる必要があります。データセットが大きい場合は、この処理に時間がかかることがあります。 BLOB コンテナーに数百の BLOB が含まれていて、リセットするドキュメントが最後にある場合、インデクサーは、他のすべてのものがチェックされるまで、一致する BLOB を検索しません。
ドキュメントが再処理された後、インデクサーの状態の取得を再度実行します。インデクサーは indexingAllDocs モードに戻り、次の実行で、新しいまたは更新されたドキュメントを処理します。

S3 HD 検索サービスのインデクサーランタイムクォータを確認する

Standard 3 High Density (S3 HD) 価格レベルの検索サービスに適用されます。

インデクサーの実行時間を 24 時間ウィンドウ内で監視できるようにするために、サービス統計情報の取得とインデクサー状態の取得の応答でより多くの情報が返されるようになりました。

累積ランタイムクォータを追跡する

検索サービスの累積インデクサーランタイムの使用状況を追跡し、24 時間ウィンドウの期限内に残っているランタイムクォータの量を決定します。

検索サービスリソースプロバイダーに GET 要求を送信します。 REST クライアントの設定とアクセストークンの取得に関するヘルプについては、「検索サービスへの接続」を参照してください。

GET {{search-endpoint}}/servicestats?api-version=2025-08-01-preview 
  Content-Type: application/json
  Authorization: Bearer {{accessToken}}

応答には、開始時刻と終了時刻、使用秒数、残り秒数、過去 24 時間以内の累積ランタイムを表示する indexersRuntime プロパティが含まれています。

インデクサーランタイムクォータの追跡

1 つのインデクサーに対して同じ情報を返します。

GET {{search-endpoint}}/indexers/hotels-sample-indexer/search.status?api-version=2025-08-01-preview 
  Content-Type: application/json
  Authorization: Bearer {{accessToken}}

応答には、開始時刻と終了時刻、使用秒数、残り秒数を表示する runtime プロパティが含まれています。

次のステップ

リセット API は、次回のインデクサー実行のスコープを通知するのに使用されます。実際の処理では、オンデマンドのインデクサー実行を呼び出すか、スケジュールされたジョブで作業を完了できるようにする必要があります。実行が完了すると、スケジュールされた処理かオンデマンドの処理かにかかわらず、インデクサーは通常の処理に戻ります。

インデクサージョブをリセットして再実行した後、検索サービスで状態を監視したり、リソースログを使用して詳細情報を取得したりできます。

フィードバック

このページはお役に立ちましたか?