Azure AI 検索で最新の REST API にアップグレードする

この記事を使用して、データプレーンおよびコントロールプレーン操作用の新しいバージョンの Search Service REST APIと Search Management REST API に移行します。

REST API の最新バージョンを次に示します。

対象となる操作	REST API	ステータス
データプレーン	`2026-04-01`	安定
データプレーン	`2025-11-01-preview`	プレビュー
制御プレーン	`2025-05-01`	安定
コントロールプレーン	`2026-03-01-preview`	プレビュー

アップグレード手順は、以前のバージョンからの破壊的変更を乗り越えるためのコード変更に重点を置いています。これにより、既存のコードが以前と同様に新しい API バージョン上で動作するようにします。コードが正常に動作したら、新しい機能を採用するかどうかを決定できます。新機能の詳細については、「Azure AI 検索を参照してください。

API バージョンを連続してアップグレードし、最新のバージョンに到達するまで各バージョンを操作することをお勧めします。

2023-07-01-preview は、ベクターサポートのための最初の REST API でした。 この API バージョンは使用しないでください。現在は非推奨となり、安定版または新しいプレビュー REST API にすぐに移行する必要があります。

メモ

REST API リファレンスドキュメントがバージョン管理されるようになりました。バージョン固有のコンテンツの場合は、参照ページを開き、目次の上にあるセレクターを使用してバージョンを選択します。

アップグレードするタイミング

Azure AI 検索は、最後の手段として下位互換性を破ります。アップグレードは次の場合に必要です。

コードは、廃止された API バージョンまたはサポートされていない API バージョンを参照しており、1 つ以上の破壊的変更が発生する可能性があります。
認識できないプロパティが API 応答で返されると、コードは失敗します。ベストプラクティスとして、アプリケーションでは理解できないプロパティを無視する必要があります。
コードは API 要求を保持し、新しい API バージョンに再送信しようとします。たとえば、アプリケーションが Search API から返された継続トークンを保持している場合に発生する可能性があります (詳細については、@search.nextPageParametersでを探してください)。

アップグレード方法

データプレーンのバージョンをアップグレードする場合は、新しい API バージョンでリリースされた内容を確認してください。
要求ヘッダーで指定された api-version パラメーターを新しいバージョンに更新します。

REST API を直接呼び出すアプリケーションコードで、既存のバージョンのすべてのインスタンスを検索し、新しいバージョンに置き換えます。 REST 呼び出しの構成の詳細については、「クイックスタート: REST を使用したフルテキスト検索」を参照してください。

Azure SDKを使用している場合、各パッケージは特定のバージョンの REST API を対象とします。パッケージでサポートされている REST API のバージョンを確認するには、その変更ログを確認します。最新の機能と API の機能強化にアクセスするために、最新のパッケージバージョンに更新します。
データプレーンバージョンをアップグレードする場合は、この記事に記載されている破壊的変更を確認し、回避策を実装します。コードで使用されているバージョンから開始し、最新の安定版またはプレビューリリースに到達するまで、新しい API バージョンごとに破壊的変更を解決します。

重大な変更

次の破壊的変更は、データ操作に適用されます。

エージェント検索の破壊的変更

2026-04-01 は、エージェンティックリトリーバルのための最初の安定した REST API バージョンです。 2025-11-01-preview からの次のような重大な変更について説明します:

応答合成、クエリ計画、構成可能な推論作業は削除されます。データ取得では、抽出された根拠のある内容のみが返されます。
取得要求の図形の変更: messages は intentsに置き換えられ、いくつかのパラメーターの名前が変更または削除されます。
BLOB と OneLake ナレッジソースのドキュメントレベルのアクセス許可フィルター処理はサポートされていません。

プロパティレベルの変更と移行手順の完全な一覧については、「エージェントの取得コードを移行する」を参照してください。

ナレッジエージェントの破壊的変更

ナレッジエージェントは、 2025-05-01-previewで導入されました。 2025-08-01-previewでは、targetIndexesは新しいナレッジソースオブジェクトに置き換えられ、defaultMaxDocsForRerankerは他の API に置き換えられました。 2025-11-01-previewでは、さらに破壊的変更が導入されました。

プロパティレベルの変更と移行手順の完全な一覧については、「エージェントの取得コードを移行する」を参照してください。

接続情報を読み取るクライアントコードの破壊的変更

2024 年 3 月 29 日より、サポートされているすべての REST API に適用されます。

GET スキルセット、 GET Index、 GET インデクサーは、応答でキーまたは接続プロパティを返さなくなりました。 GET 応答からキーまたは接続 (機密データ) を読み取るダウンストリームコードがある場合、これは重大な変更です。
検索サービスの管理者またはクエリ API キーを取得する必要がある場合は、 Search Management REST API を使用します。
Azure StorageやAzure Cosmos DBなど、別のAzure リソースの接続文字列を取得する必要がある場合は、そのリソースの API と公開されたガイダンスを使用して情報を取得します。

セマンティックランカーの破壊的変更

セマンティックランカーは、 2023-11-01で一般公開されました。以前のリリースからの破壊的変更を次に示します。

2020-06-01-preview後のすべてのバージョンでは、semanticConfigurationは L2 ランク付けに使用するフィールドを指定するためのメカニズムとしてsearchFieldsを置き換えます。
すべての API バージョンで、2023 年 7 月 14 日に Microsoft ホスト型セマンティックモデルが更新され、セマンティックランカー言語に依存せず、queryLanguage プロパティが実質的に使用停止になりました。コードに "破壊的変更" はありませんが、プロパティは無視されます。

を使用するようにコードを移行するには、「semanticConfigurationする」を参照してください。

データプレーンのアップグレード

アップグレードガイダンスでは、最新バージョンからのアップグレードを前提としています。コードが古い API バージョンに基づいている場合は、以降の各バージョンをアップグレードして最新バージョンにすることをお勧めします。

2026-04-01 へのアップグレード

2026-04-01 は、最新の安定した REST API バージョンです。エージェント検索、ナレッジソースの選択、およびいくつかのスキルと機能を一般提供に昇格させます。

アップグレードする前に、次の 2026-04-01 重大な変更のいずれかがコードに適用されるかどうかを確認します。

GenAI Prompt スキル定義から、httpMethod、timeout、batchSize、degreeOfParallelism、httpHeaders、authResourceIdの 6 つのプロパティが削除されます。アップグレードする前に、これらのプロパティを削除してください。これらのプロパティをまだ含む定義では、 400 Bad Request エラーが返されます。
エージェント検索には課金に対する独自の同意が必要になりました。現在 semanticSearch=standardがある場合は、アップグレードする前に knowledgeRetrieval=standard を明示的に設定する必要があります。詳細については、「エージェント検索の課金を有効または無効にする」を参照してください。
エージェント検索コードが 2025-11-01-previewを対象とする場合、 2026-04-01 は複数のプレビュー機能を削除し、意図の入力、抽出出力、および最小限の推論に関する取得を標準化します。詳細については、エージェント型取得コードの移行に関するドキュメントをご覧ください。

他のすべての既存の API では、動作の変更はありません。新しい API バージョンでスワップすることができ、コードは以前と同じように実行されます。

2025-11-01-preview にアップグレードする

2025-11-01-preview では、 2025-08-01-previewに実装されているエージェント検索に次の破壊的変更が導入されています。

agentsをknowledgebasesに置き換えます。ナレッジソースに関連するいくつかのプロパティが、ナレッジベース定義から取得アクションに移動しました。
ナレッジソースのプロパティがリファクタリングされ、インデクサーパイプラインを生成するナレッジソース用の新しい ingestionParameters オブジェクトが実装されます。

プロパティレベルの変更と移行手順の完全な一覧については、「エージェントの取得コードを移行する」を参照してください。

2025-09-01 にアップグレードする

2025-09-01 は、OneLake インデクサー、ドキュメントレイアウトスキル、およびその他の API の一般提供を追加する安定した REST API バージョンです。

2024-07-01からアップグレードし、プレビュー機能を使用していない場合、破壊的変更はありません。新しい安定版リリースを使用するには、API のバージョンを変更し、コードをテストします。

2025-08-01-preview にアップグレードする

2025-08-01-preview では、 2025-05-01-previewを使用して作成されたナレッジエージェントに次の破壊的変更が導入されています。

targetIndexesをknowledgeSourcesに置き換えます。
置換せずに defaultMaxDocsForReranker を削除します。

それ以外の場合、既存の API に対する動作の変更はありません。新しい API バージョンでスワップすることができ、コードは以前と同じように実行されます。

2025-05-01-preview にアップグレードする

2025-05-01-preview は新しい機能を提供しますが、既存の API に動作の変更はありません。新しい API バージョンでスワップすることができ、コードは以前と同じように実行されます。

2025-03-01-preview にアップグレードする

2025-03-01-preview は新しい機能を提供しますが、既存の API に動作の変更はありません。新しい API バージョンでスワップすることができ、コードは以前と同じように実行されます。

2024-11-01-preview にアップグレードする

2024-11-01-preview クエリ書き換え、ドキュメントのレイアウトスキル、スキル処理のキーレス課金、Markdown パースモード、圧縮ベクターの再スコアリングオプション。

2024-09-01-previewからアップグレードする場合は、新しい API バージョンでスワップすることができ、コードは以前と同じように実行されます。

ただし、新しいバージョンでは、 vectorSearch.compressionsに構文の変更が導入されています。

rerankWithOriginalVectorsを次のように置き換えます。enableRescoring
defaultOversamplingを新しいrescoringOptionsプロパティオブジェクトに移動します

下位互換性は内部 API マッピングのために保持されますが、新しいプレビューバージョンを採用する場合は構文を変更することをお勧めします。構文の比較については、「スカラー量子化またはバイナリ量子化を使用してベクターを圧縮する」を参照してください。

2024-09-01-preview にアップグレードする

2024-09-01-preview は、テキスト埋め込み 3 モデル用にMatryoshka Representation Learning (MRL) 圧縮を追加し、ハイブリッドクエリ用のターゲットベクターフィルタリング、デバッグ用のベクターサブスコア詳細、およびText Split スキルのトークンチャンクを提供します。

2024-05-01-previewからアップグレードする場合は、新しい API バージョンでスワップすることができ、コードは以前と同じように実行されます。

2024-07-01 へのアップグレード

2024-07-01 は一般的なリリースです。以前のプレビュー機能が一般公開されました。統合チャンクとベクター化 (テキスト分割スキル、AzureOpenAIEmbedding スキル)、AzureOpenAIEmbedding に基づくクエリベクターライザー、ベクター圧縮 (スカラー量子化、バイナリ量子化、格納プロパティ、狭いデータ型)。

2024-05-01-previewから安定版にアップグレードする場合、重大な変更はありません。新しい安定版リリースを使用するには、API のバージョンを変更し、コードをテストします。

2023-11-01から直接アップグレードする場合は、重大な変更があります。新しいプレビューごとに説明されている手順に従って、 2023-11-01 から 2024-07-01に移行します。

2024-05-01-preview にアップグレードする

2024-05-01-preview は、Microsoft OneLake、バイナリベクター、その他の埋め込みモデルのインデクサーを追加します。

2024-03-01-previewからアップグレードする場合、AzureOpenAIEmbedding スキルにモデル名とディメンションプロパティが必要になりました。

コードベースで AzureOpenAIEmbedding 参照を検索します。
modelNameを "text-embedding-ada-002" に設定し、dimensionsを "1536" に設定します。

2024-03-01-preview にアップグレードする

2024-03-01-preview では、狭いデータ型、スカラー量子化、ベクターストレージオプションが追加されます。

2023-10-01-previewからアップグレードする場合、重大な変更はありません。ただし、動作には 1 つの違いがあります。2023-11-01 以降のプレビューでは、フィルター式に対する vectorFilterMode の既定の動作が、「ポストフィルター」から「プリフィルター」に変更されました。

コードベースで vectorFilterMode 参照を検索します。
プロパティが明示的に設定されている場合、アクションは必要ありません。既定値に依存している場合、新しい既定の動作では、クエリの実行前にフィルター処理が行われます。クエリ後のフィルター処理を行う場合は、古い動作を保持するために、 vectorFilterMode を postfilter に明示的に設定します。

2023-11-01 へのアップグレード

2023-11-01 は一般的なリリースです。以前のプレビュー機能が一般公開されました。セマンティックランカーとベクターのサポート。

2023-10-01-previewからの破壊的変更はありませんが、2023-07-01-previewから2023-11-01に複数の破壊的変更があります。詳細については、「 2023-07-01-preview からのアップグレード」を参照してください。

新しい安定版リリースを使用するには、API のバージョンを変更し、コードをテストします。

2023-10-01-preview にアップグレードする

2023-10-01-preview は、インデックス作成中に組み込みのデータチャンクとベクトル化を追加し、組み込みのクエリベクトル化も行う最初のプレビューバージョンでした。また、以前のバージョンのベクターインデックス作成とクエリもサポートされています。

以前のバージョンからアップグレードする場合は、次のセクションに手順があります。

2023-07-01-preview からのアップグレード

この API バージョンは使用しないでください。新しい API バージョンと互換性のないベクタークエリ構文を実装します。

2023-07-01-preview は非推奨になったため、このバージョンに基づいて新しいコードを作成したり、どのような状況でもこのバージョンにアップグレードしたりしないでください。このセクションでは、 2023-07-01-preview から新しい API バージョンへの移行パスについて説明します。

ベクターインデックスのポータルのアップグレード

Azure ポータルでは、2023-07-01-preview インデックスのワンクリックアップグレードパスがサポートされています。ベクターフィールドを検出し、[ 移行 ] ボタンを提供します。

移行パスは、 2023-07-01-preview から 2024-05-01-previewです。
更新は、ベクターフィールド定義とベクター検索アルゴリズムの構成に限定されます。
更新プログラムは一方向です。アップグレードを取り消すことはできません。インデックスがアップグレードされたら、 2024-05-01-preview 以降を使用してインデックスのクエリを実行する必要があります。

ベクタークエリ構文をアップグレードするためのポータル移行はありません。クエリ構文の変更については、コードのアップグレードを参照してください。

[移行] を選択する前に、[JSON の編集] を選択して、更新されたスキーマを最初に確認します。コードのアップグレードセクションで説明されている変更に準拠するスキーマが見つかります。ポータルの移行では、1 つのベクター検索アルゴリズム構成を持つインデックスのみが処理されます。 2023-07-01-preview ベクター検索アルゴリズムにマップされる既定のプロファイルが作成されます。複数のベクター検索構成を持つインデックスには、手動での移行が必要です。

ベクターインデックスとクエリのコードアップグレード

ベクター検索のサポートは、インデックスの作成または更新 (2023-07-01-preview) で導入されました。

2023-07-01-previewから新しい安定したバージョンまたはプレビューバージョンにアップグレードするには、次のものが必要です。

インデックス内のベクター構成の名前変更と再構築
ベクタークエリの書き換え

このセクションの手順を使用して、ベクターフィールド、構成、クエリを 2023-07-01-previewから移行します。

Get Index を呼び出して、既存の定義を取得します。
ベクター検索の構成を変更します。 2023-11-01 以降のバージョンでは、ベクター関連の構成を 1 つの名前でバンドルするベクター プロファイル の概念が導入されています。新しいバージョンでは、 algorithmConfigurations の名前も algorithmsに変更されます。
- algorithmConfigurationsの名前をalgorithmsに変更します。これは配列の名前変更にすぎません。内容には下位互換性があります。つまり、既存の HNSW 構成パラメーターを使用できます。
- profilesを追加し、それぞれに名前とアルゴリズム構成を指定します。
移行前 (2023-07-01-preview):
```
  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}
```
移行後 (2023-11-01):
```
  "vectorSearch": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }
```

ベクターフィールド定義を変更し、 vectorSearchConfiguration を vectorSearchProfileに置き換えます。プロファイル名がアルゴリズム構成名ではなく、新しいベクタープロファイル定義に解決されていることを確認します。その他のベクターフィールドプロパティは変更されません。たとえば、フィルター可能、並べ替え可能、ファセット可能にしたり、アナライザーやノーマライザーやシノニムマップを使用したりすることはできません。

(2023-07-01-preview) より前:

  {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

(2023-11-01) 以降:

  {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

Create または Update Index を呼び出して変更を投稿します。
検索 POST を変更してクエリ構文を変更します。この API の変更により、ポリモーフィックベクタークエリの種類がサポートされます。
- vectorsの名前をvectorQueriesに変更します。
- ベクタークエリごとに、 kindを追加し、 vectorに設定します。
- ベクタークエリごとに、 value の名前を vector に変更します。
- 必要に応じて、vectorFilterModeを使用している場合は、を追加します。既定値は、 2023-10-01後に作成されたインデックスのプリフィルターです。その日付より前に作成されたインデックスは、フィルターモードの設定方法に関係なく、ポストフィルターのみをサポートします。
(2023-07-01-preview) より前:
```
{
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}
```
(2023-11-01) 以降:
```
{
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}
```

これらの手順では、安定した API バージョン以降のプレビュー API バージョン 2023-11-01 への移行を完了します。

2020-06-30 へのアップグレード

このバージョンでは、1 つの破壊的変更といくつかの動作の違いがあります。一般提供されている機能は次のとおりです。

ナレッジストア。スキルセットを通じて作成されたエンリッチされたコンテンツの永続的なストレージ。ダウンストリーム分析用に作成され、他のアプリケーションを介して処理されます。ナレッジストアは、Azure AI 検索 REST API を使用して作成されますが、Azure Storageに存在します。

破壊的変更

以前の API バージョンに対して記述されたコードは、コードに次の機能が含まれている場合、 2020-06-30 以降で中断されます。

フィルター式内のEdm.Dateリテラル（年-月-日で構成される日付の例として2020-12-12など）はEdm.DateTimeOffset形式である2020-12-12T00:00:00Zに従う必要があります。この変更は、タイムゾーンの違いにより、誤ったクエリ結果または予期しないクエリ結果を処理するために必要でした。

動作の変更

BM25 ランク付けアルゴリズムは、以前のランク付けアルゴリズムを新しいテクノロジに置き換えます。 2019 年より後に作成されたサービスでは、このアルゴリズムが自動的に使用されます。以前のサービスでは、新しいアルゴリズムを使用するようにパラメーターを設定する必要があります。
このバージョンでは、null 値の順序付けされた結果が変更されました。並べ替えが asc 場合は null 値が最初に表示され、並べ替えが desc場合は最後に null 値が表示されます。 null 値の並べ替え方法を処理するコードを記述した場合は、この変更に注意してください。

2019-05-06 へのアップグレード

この API バージョンで一般公開された機能は次のとおりです。

オートコンプリートは、部分的に指定された用語入力を完了する先行入力機能です。
複合型は、検索インデックス内の構造化オブジェクトデータをネイティブにサポートします。
JsonLines 解析モードは、AZURE BLOB インデックス作成の一部として、改行で区切られた JSON エンティティごとに 1 つの検索ドキュメントを作成します。
AI エンリッチメントは、Foundry Tools の AI エンリッチメントエンジンを使用するインデックス作成を提供します。

重大な変更

以前の API バージョンに対して記述されたコードは、次の機能が含まれている場合、 2019-05-06 以降で中断されます。

Azure Cosmos DBのタイププロパティ。 Azure Cosmos DB for NoSQL API向けインデクサーの場合、"type": "documentdb" を "type": "cosmosdb" に変更します。
インデクサーエラー処理に status プロパティへの参照が含まれている場合は、削除する必要があります。有用な情報が提供されていないため、エラー応答から状態を削除しました。
データソース接続文字列が応答で返されなくなりました。 API バージョン 2019-05-06 以降 2019-05-06-Preview 、データソース API は REST 操作の応答で接続文字列を返さなくなりました。以前のバージョンの API では、POST を使用して作成されたデータソースの場合、Azure AI 検索は 201 に続いて OData 応答が返され、その後に接続文字列がプレーンテキストで含まれていました。
名前付きエンティティ認識コグニティブスキルは廃止されました。コードで Name Entity Recognition スキルを呼び出した場合、呼び出しは失敗します。置換機能はエンティティ認識スキル (V3) です。非推奨のスキルの推奨事項に従って、サポートされているスキルに移行します。

複合データ型のアップグレード

API バージョン 2019-05-06 複合型の正式なサポートが追加されました。コードで、2017-11-11-Preview または 2016-09-01-Preview で複合型の等価性に関する以前の推奨事項を実装した場合、バージョン 2019-05-06 以降には、注意する必要がある新しい制限と変更された制限がいくつかあります。

サブフィールドの深さとインデックスあたりの複雑なコレクションの数の制限が下がりました。プレビュー API バージョンを使用してこれらの制限を超えるインデックスを作成した場合、API バージョンを使用してインデックスを更新または再作成しようとすると、 2019-05-06 失敗します。このような状況が発生した場合は、新しい制限内に収まるようにスキーマを再設計してから、インデックスを再構築する必要があります。
api-version 2019-05-06 では、ドキュメントごとの複雑なコレクションの要素数に関する新しい制限が開始されています。プレビュー API バージョンを使用して、これらの制限を超えるドキュメントでインデックスを作成した場合、api-version 2019-05-06 を使用してそのデータのインデックスを再作成しようとすると失敗します。このような状況が発生した場合は、データのインデックスを再作成する前に、ドキュメントごとの複雑なコレクション要素の数を減らす必要があります。

詳細については、 Azure AI 検索を参照してください。

古い複合型構造体をアップグレードする方法

コードで以前のプレビュー API バージョンの 1 つで複合型を使用している場合は、次のようなインデックス定義形式を使用している可能性があります。

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

インデックスフィールドを定義するための新しいツリーのような形式が、API バージョンの 2017-11-11-Previewで導入されました。新しい形式では、各複合フィールドには、そのサブフィールドが定義されているフィールドコレクションがあります。 API バージョン 2019-05-06 では、この新しい形式が排他的に使用され、古い形式を使用してインデックスを作成または更新しようとすると失敗します。以前の形式を使用してインデックスを作成した場合は、API バージョン 2019-05-06 を使用して管理する前に、API バージョンの 2017-11-11-Preview を使用して新しい形式に更新する必要があります。

API バージョンの 2017-11-11-Previewを使用して、次の手順でフラットインデックスを新しい形式に更新できます。

GET 要求を実行してインデックスを取得します。既に新しい形式になっている場合は、完了です。
インデックスをフラット形式から新しい形式に変換します。このタスクのコードは、この書き込みの時点で使用できるサンプルコードがないため、記述する必要があります。
PUT 要求を実行して、インデックスを新しい形式に更新します。既存のインデックスの物理的な式に影響を与える変更は Update Index API では許可されていないため、フィールドの検索可能性やフィルター可能性など、インデックスの他の詳細は変更しないでください。

メモ

Azure ポータルから古い "フラット" 形式で作成されたインデックスを管理することはできません。できるだけ早く、インデックスを "フラット" 表現から "ツリー" 表現にアップグレードします。

コントロールプレーンのアップグレード

適用対象:2014-07-31-Preview、 2015-02-28、および 2015-08-19

以前のバージョンの Search Management API に対する listQueryKeys GET 要求は非推奨になりました。 listQueryKeys POST 要求を使用するには、最新の安定したコントロールプレーン API バージョンに移行することをお勧めします。

既存のコードで、 api-version パラメーターを最新バージョン (2025-05-01) に変更します。

GETからPOSTに要求をリフレームします。

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/listQueryKeys?api-version=2025-05-01
Authorization: Bearer {{token}}

Azure SDKを使用している場合は、最新バージョンにアップグレードすることをお勧めします。

次の手順

検索 REST API リファレンスドキュメントを確認します。問題が発生した場合は、 Stack Overflow に関するサポートを依頼するか、サポートにお問い合わせください。

Search Service REST API リファレンス

フィードバック

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

Last updated on 2026-05-12

Azure AI 検索で最新の REST API にアップグレードする

アップグレードするタイミング

アップグレード方法

重大な変更

エージェント検索の破壊的変更

ナレッジ エージェントの破壊的変更

接続情報を読み取るクライアント コードの破壊的変更

セマンティック ランカーの破壊的変更

データ プレーンのアップグレード

2026-04-01 へのアップグレード

2025-11-01-preview にアップグレードする

2025-09-01 にアップグレードする

2025-08-01-preview にアップグレードする

2025-05-01-preview にアップグレードする

2025-03-01-preview にアップグレードする

2024-11-01-preview にアップグレードする

2024-09-01-preview にアップグレードする

2024-07-01 へのアップグレード

2024-05-01-preview にアップグレードする

2024-03-01-preview にアップグレードする

2023-11-01 へのアップグレード

2023-10-01-preview にアップグレードする

2023-07-01-preview からのアップグレード

ベクター インデックスのポータル のアップグレード

ベクター インデックスとクエリのコード アップグレード

2020-06-30 へのアップグレード

破壊的変更

動作の変更

2019-05-06 へのアップグレード

重大な変更

複合データ型のアップグレード

古い複合型構造体をアップグレードする方法

コントロール プレーンのアップグレード

次の手順

フィードバック

その他のリソース

ナレッジエージェントの破壊的変更

接続情報を読み取るクライアントコードの破壊的変更

セマンティックランカーの破壊的変更

データプレーンのアップグレード

ベクターインデックスのポータルのアップグレード

ベクターインデックスとクエリのコードアップグレード

コントロールプレーンのアップグレード