Azure AI Search の検索インデックスにデータを読み込む

この記事では、REST API、Azure SDK、または Azure portal を使用して、定義済みの検索インデックスにドキュメントをインポートする方法について説明します。

ヒント

データを読み込むための最速のパスについては、Azure portal で データのインポート ウィザードを使用します。このウィザードでは、インデックスが作成され、1 つのワークフローに読み込まれます。

[前提条件]

Azure AI Search サービス (任意のレベル)。サービスを作成するか、既存のサービスを検索します。
既存の検索インデックス。この記事では、インデックスを既に作成していることを前提としています。 1 つの手順で作成して読み込む必要がある場合は、インポートウィザードまたはインデクサーを使用します。
ドキュメントを読み込むアクセス許可:
- キーベースの認証: 検索サービスの管理 API キー。
- ロールベースの認証: 検索サービスにおけるインデックスデータ共同作成者ロール。
SDK 開発の場合は、Azure Search クライアントライブラリをインストールします。
- .NET: Azure.Search.Documents
- Python: azure-search-documents
- JavaScript: @azure/search-documents
- Java: azure-search-documents

Azure ポータルの使用

Azure portal でインポートウィザードを使用して、シームレスなワークフローでインデックスを作成して読み込みます。既存のインデックスを読み込む場合は、別の方法を選択します。

Azure portal で、Search サービスに移動します。
[ 概要 ] ページで、コマンドバーの [ データのインポート ] を選択して、検索インデックスを作成して設定します。

次のリンクからワークフローを確認できます: 「クイックスタート: Azure AI Search インデックスの作成」と「クイックスタート: 垂直統合」。
ウィザードが完了したら、検索エクスプローラーを使って結果を確認します。

ヒント

インポートウィザードはインデクサーを作成して実行します。インデクサーが既に定義されている場合は、Azure portal からインデクサーをリセットして実行できます。これは、フィールドを段階的に追加する場合に便利です。リセットにより、インデクサーが強制的に最初からやり直しをし、すべてのソースドキュメントからすべてのフィールドを取得します。

REST API を使用する

ドキュメント - インデックスは、データを検索インデックスにインポートするための REST API です。

要求の本文には、インデックスを作成する 1 つまたは複数のドキュメントが含まれます。ドキュメントは、大文字と小文字を区別するキーを使用して一意に識別されます。各ドキュメントは、"upload"、"delete"、"merge"、または "mergeOrUpload" アクションに関連付けられます。アップロード要求には、キーと値のペアのセットとしてドキュメントデータを含める必要があります。

REST API は初期の概念実証テストに役立ち、多くのコードを記述しなくてもインデックス作成ワークフローをテストできます。 @search.action パラメーターは、特定のフィールドの新しい値または置換値の観点から、ドキュメントの全体が追加されるのか、部分的に追加されるのかを決定します。

クイックスタート: REST を使用したフルテキスト検索 の手順について説明します。次の例は、例の変更されたバージョンです。簡潔にするために値がトリミングされ、既存のドキュメントが上書きされないように最初の HotelId 値が変更されます。

インデックス名、"docs/index" エンドポイント、および @search.action パラメーターを含む要求本文を指定する POST 呼び出しを作成します。

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/index?api-version=2025-09-01
Content-Type: application/json   
api-key: [admin key] 
{
    "value": [
    {
    "@search.action": "upload",
    "HotelId": "1111",
    "HotelName": "Stay-Kay City Hotel",
    "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
    "Category": "Boutique",
    "Tags": [ "pool", "air conditioning", "concierge" ]
    },
    {
    "@search.action": "mergeOrUpload",
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
    "Category": "Boutique",
    "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
    }
  ]
}

ドキュメントを作成または上書きするには、@search.action パラメーターを upload に設定します。ドキュメント内の特定のフィールドを更新の対象にする場合は、merge または uploadOrMerge に設定します。前の例では、両方のアクションが示されています。

アクション	結果
アップロード	"upsert" と同様に、ドキュメントが新しい場合は挿入され、存在する場合は更新または置換されます。インデックスに必要な値がドキュメントにない場合、ドキュメントフィールドの値は null に設定されます。
マージ	既に存在するドキュメントを更新し、ドキュメントが見つからない場合は失敗します。マージは既存の値を置き換えます。そのため、`Collection(Edm.String)` 型のフィールドなど、複数の値を含むコレクションフィールドは必ず確認してください。たとえば、`tags` フィールドの値が `["budget"]` で始まり、値 `["economy", "pool"]` でマージを実行した場合、`tags` フィールドの最終値は `["economy", "pool"]` になります。 `["budget", "economy", "pool"]`ではありません。
マージまたはアップロード	ドキュメントが存在する場合は merge、ドキュメントが新しい場合は upload と同じように動作します。これは、増分更新の最も一般的なアクションです。
削除する	削除すると、指定したドキュメントがインデックスから削除されます。キーフィールド以外の削除操作で指定したフィールドは無視されます。ドキュメントから個々のフィールドを削除する場合は、代わりにマージを使ってフィールドを明示的に null に設定します。詳細については、「検索インデックス内のドキュメントを削除する」を参照してください。

要求本文内のどのアクションが最初に実行されるかについて、順序の保証はありません。 1 つの要求本文で、同じドキュメントに複数の "マージ" アクションを関連付けすることはお勧めしません。同じドキュメントに対して複数の "マージ" アクションが必要な場合は、検索インデックス内のドキュメントを更新する前に、クライアント側でのマージを実行します。

プリミティブコレクションでは、ドキュメントに ["budget"] の値を持つ Collection(Edm.String) 型の Tags フィールドが含まれており、Tag に対して ["economy"、"pool"] の値を使用してマージを実行すると、Tags フィールドの最終的な値は ["economy"、"pool"になります。 ["予算"、"経済"、"プール"]ではない。

複合コレクションにおいて、Roomsという名前の複合コレクションフィールドが[{ "Type": "Budget Room", "BaseRate": 75.0 }]という値を持つ場合に、[{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]という値でマージを行うと、Roomsフィールドの最終値は[{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]になります。次のいずれかにはなりません。

[{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }](要素の追加)
[{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }](要素を順番にマージしてから、余分な要素を追加します)

注

タイムゾーン情報を含む DateTimeOffset 値をインデックスにアップロードすると、Azure AI Search によってこれらの値が UTC に正規化されます。たとえば、2025-01-13T14:03:00-08:00 は 2025-01-13T22:03:00Z として格納されます。タイムゾーン情報を格納する必要がある場合は、インデックスに列を追加します。

要求を送信します。

次の表では、応答で返すことができるドキュメントごとのさまざまな状態コードについて説明します。状態コードには、要求自体に問題があることを示すものと、一時的なエラー状態を示すものがあります。後者の場合は、待機してから再試行する必要があります。

状態コード	Meaning	リトライ可能	注記
200	ドキュメントは正常に変更または削除されました。	n/a	削除操作はべき等性を持っています。つまり、インデックスにドキュメントキーが存在しない場合でも、そのキーで削除操作を行おうとすると 200 状態コードが返されます。
201	ドキュメントは正常に作成されました。	n/a
400	ドキュメントにエラーがあり、インデックスを作成できませんでした。	いいえ	応答に含まれるエラーメッセージに、ドキュメントに関する問題が示されます。
404	指定されたキーがインデックス内に存在しないため、ドキュメントをマージできませんでした。	いいえ	このエラーは、アップロードの場合は新しいドキュメントが作成されるため発生せず、削除の場合はべき等なので発生しません。
409	ドキュメントのインデックスを作成しようとしたときにバージョンの競合が検出されました。	イエス	これは、同じドキュメントに対して同時に複数回インデックスを作成しようとしたときに発生することがあります。
422	インデックスは、allowIndexDowntime フラグを true に設定して更新されたため、一時的に使用できない状態です。	イエス
429	インデックスあたりのドキュメント数のクォータを超えたことを示します。	いいえ	容量制限を高くするには、新しいインデックスを作成するか、アップグレードする必要があります。
503	検索サービスは一時的に使用できない状態です。負荷が高いことが原因として考えられます。	イエス	この場合は、待機してから再試行する必要があります。そうしないと、サービスを使用できない状態が長引く場合があります。

注

クライアントコードで 207 応答が頻繁に検出される場合、理由の 1 つとしてシステムが高負荷の状態にあることが考えられます。これを確認するには、 statusCode プロパティで 503 を確認します。その場合は、インデックス作成要求のペースを制限することをお勧めします。もしインデックス作成トラフィックが減らない場合、システムは503エラーで全ての要求を拒否し始める可能性があります。

検証手順として追加したドキュメントを参照します。

GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2025-09-01

Reference:Documents - Index、 Documents - Get

インデックス要求が成功すると、すべてのドキュメントが成功したバッチの HTTP 200 (OK) が返されます。一部のドキュメントが失敗した場合は HTTP 207 (複数状態) が返されます。応答本文には、各ドキュメントの状態が含まれています。

{
    "value": [
        { "key": "1111", "status": true, "statusCode": 201 },
        { "key": "2", "status": true, "statusCode": 200 }
    ]
}

ドキュメントキーまたは ID が新しい場合、 null はドキュメントで指定されていないフィールドの値になります。既存のドキュメントに対するアクションの場合、更新された値が前の値に置き換わります。 "merge" または "mergeUpload" で指定されなかったフィールドは、検索インデックスでそのまま残ります。

Azure SDK を使用する

プログラミング機能は、次の Azure SDK で提供されています。

Azure SDK for Python では、ドキュメントのインデックスへの簡易および一括アップロード用に、次の API が提供されています。

Reference:SearchClient、 IndexDocumentsBatch

コードのサンプルには次のものが含まれます。

sample_crud_operations.py
ベクトルフィールドのインデックス作成方法がわかるコードの例については、azure-search-vector-samples リポジトリを確認してください。

Azure SDK for .NET では、ドキュメントのインデックスへの簡易および一括アップロード用に、次の API が提供されています。

次の例では、既存のインデックスにドキュメントをアップロードします。

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Create the search client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Define documents to upload
var documents = new[]
{
    new { HotelId = "1111", HotelName = "Stay-Kay City Hotel", Category = "Boutique" },
    new { HotelId = "1112", HotelName = "Old Century Hotel", Category = "Luxury" }
};

// Upload documents
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Upload(documents));

Console.WriteLine($"Uploaded {result.Results.Count} documents");

Reference:SearchClient、 IndexDocumentsAsync、 IndexDocumentsBatch

単純なインデックス作成と大規模なインデックス作成のコンテキストで、インデックス作成を説明するサンプルがいくつかあります。

「インデックスを読み込む」では、基本的な手順について説明しています。
Azure SDK チームからの「Azure.Search.Documents サンプル - ドキュメントのインデックス作成」では、SearchIndexingBufferedSender を追加しています。
任意のデータのインデックス作成に関するチュートリアルでは、バッチインデックス作成と、最適なサイズを特定するためのテスト戦略を結合しています。
ベクトルフィールドのインデックス作成方法がわかるコードの例については、azure-search-vector-samples リポジトリを確認してください。

データの読み込みを確認する

ドキュメントを読み込んだ後、データのインデックスが正しいことを確認します。

Azure portal で、検索サービスの [概要 ] ページを開きます。
コマンドバーから 検索エクスプローラー を選択します。
ドロップダウンからインデックスを選択します。
[ 検索 ] を選択すると、すべてのドキュメントを返す空のクエリが実行されます。
ドキュメント数とスポットチェックフィールドの値を確認します。

Get Document API を使用して、キーで特定のドキュメントを取得します。

GET https://[service-name].search.windows.net/indexes/hotels-sample/docs/1111?api-version=2025-09-01
api-key: [admin-key]

予期される応答: ドキュメント JSON が見つかった場合は HTTP 200、キーが存在しない場合は HTTP 404。

// Verify document was indexed
var document = await searchClient.GetDocumentAsync<Hotel>("1111");
Console.WriteLine($"Found: {document.Value.HotelName}");

データのインポートのしくみ

検索サービスでは、インデックススキーマに準拠する JSON ドキュメントが受け入れられます。検索サービスでは、JSON ドキュメント内のプレーンテキストコンテンツとベクトルコンテンツをインポートし、インデックスを付けることができます。

プレーンテキストコンテンツは、外部データソースのフィールド、メタデータプロパティ、またはスキルセットによって生成されたエンリッチされたコンテンツから取得されます。スキルは、画像や非構造化コンテンツからテキストの説明を抽出または推論できます。
ベクトルコンテンツは、それを提供するデータソースから取得されるか、Azure AI Search インデクサーワークロードで垂直統合を実装するスキルセットによって作成されます。

これらのドキュメントは自分で準備できますが、サポートされているデータソースにコンテンツが存在する場合は、インデクサーを実行するか、インポートウィザードを使用して、ドキュメントの取得、JSON シリアル化、インデックス作成を自動化できます。

データのインデックスが作成されると、インデックスの物理データ構造がロックされます。変更できるものとできないもののガイダンスについては、インデックスの更新と再構築に関する記事をご覧ください。

インデックス作成はバックグラウンドプロセスではありません。検索サービスはインデックス作成とクエリワークロードのバランスを取りますが、クエリの待機時間が長すぎる場合は、容量を追加するか、インデックスを読み込むための低いクエリアクティビティの期間を特定できます。

詳しくは、データインポート戦略に関する記事をご覧ください。

一般的なエラーのトラブルシューティング

エラー	原因	解決策
HTTP 400 無効な要求	ドキュメントに無効なデータが含まれているか、必須フィールドがありません	特定のフィールドのエラーメッセージを確認します。すべての必須フィールドが存在し、データ型がインデックススキーマと一致していることを確認します。
HTTP 404 が見つかりません (マージ)	存在しないドキュメントをマージしようとしています	ドキュメントが存在しない可能性がある場合は、`mergeOrUpload`の代わりに`merge`を使用します。
HTTP 409 の競合	同じドキュメントに対する同時更新	指数バックオフを使用して再試行ロジックを実装します。
HTTP 413 ペイロードが大きすぎます	バッチサイズが制限を超えています	バッチあたりのドキュメント数を減らします。最大バッチサイズは、1,000 ドキュメントまたは 16 MB です。
HTTP 429 要求が多すぎます	クォータを超えました	サービスレベルの制限を確認します。新しいインデックスのアップグレードまたは作成を検討してください。
HTTP 503 サービス利用不可	サービスの負荷が高い	指数バックオフを使用して再試行ロジックを実装します。インデックス作成要求の頻度を減らします。

フィードバック

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

Last updated on 2026-01-22