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

この記事では、定義済みの検索インデックスにドキュメントをインポートする方法について説明します。 Azure AI 検索では、検索インデックスが最初に作成された後、2 番目のステップとしてデータのインポートが行われます。 ただし、Azure portal の インポート ウィザード と インデクサー パイプラインは例外であり、1 つのワークフローでインデックスを作成して読み込みます。

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

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

• プレーン テキスト コンテンツは、外部データ ソースのフィールド、メタデータ プロパティ、または スキルセットによって生成されたエンリッチされたコンテンツから取得されます。 スキルは、画像や非構造化コンテンツからテキストの説明を抽出または推論できます。

• ベクトル コンテンツは、それを提供するデータ ソースから取得されるか、Azure AI Search インデクサー ワークロードで垂直統合を実装するスキルセットによって作成されます。

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

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

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

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

Azure ポータルの使用

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

1. Azure アカウントを使って Azure portal にサインインし、使う検索サービスを見つけます。

2. [ 概要 ] ページで、コマンド バーの [ データのインポート] または [データのインポート (新規)] を選択して、検索インデックスを作成して設定します。

   

   次のリンクからワークフローを確認できます: 「クイック スタート: Azure AI Search インデックスの作成」と「クイックスタート: 垂直統合」。

3. ウィザードが完了したら、検索エクスプローラーを使って結果を確認します。

REST API を使用する

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

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

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

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

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

   POST https://[service name].search.windows.net/indexes/hotels-sample-index/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" ]
       }
     ]
   }
   

2. ドキュメントを作成または上書きするには、@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 として格納されます。 タイム ゾーン情報を格納する必要がある場合は、インデックスに列を追加します。

3. 要求を送信します。

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

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

   注

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

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

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

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

Azure SDK を使用する

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

関連項目

• 検索インデックスの概要
• データ インポートの概要
• データのインポート ウィザードの概要
• インデクサーの概要