升級到 Azure AI 搜尋服務中的最新 REST API

註

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

利用本文遷移至更新版本 的搜尋服務 REST API 及 搜尋管理 REST API 以進行資料平面與控制平面操作。

以下是 REST API 的最新版本：

精準行動	REST API	現況
資料平面	`2026-04-01`	穩定
資料平面	`2026-08-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 回應中回傳未識別屬性時，你的程式碼就會失敗。作為最佳實務，你的應用程式應該忽略它不理解的屬性。
你的程式碼會持久化 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 Skillset、 GET Index 和 GET Indexer 不再在回應中回傳鍵或連線屬性。如果你有下游程式碼會讀取 GET 回應的金鑰或連線（敏感資料），這是個突破性的變更。
如果你需要為搜尋服務取得管理員或查詢 API 金鑰，請使用 Search Management REST API。
如果你需要取得其他 Azure 資源的連線字串，例如 Azure 儲存體或 Azure Cosmos DB，請使用該資源的 API 及已發布的指引來取得相關資訊。

語意排名器的重大變更

語意排名器普遍可用於。以下是與早期版本相較的重大變更：

在之後 2020-06-01-preview所有版本中，以 semanticConfiguration 取代 searchFields 作為指定 L2 排名欄位的機制。
對於所有 API 版本，2023 年 7 月 14 日更新的 Microsoft 託管語意模型使語意排序器成為語言無關的，實質上停用了 queryLanguage 屬性。程式碼中沒有「破壞性變更」，但這個屬性會被忽略。

請參見從預覽版遷移以將程式碼轉變為使用semanticConfiguration。

資料平面升級

升級指引假定升級是從最新的上一版本進行的。如果您的程式碼基於舊版 API，我們建議逐步升級每個後續版本，以便升級到最新版本。

升級至 2026-08-01-preview

2026-08-01-preview 新增代理檢索控制、知識來源增強，以及為列表操作提供游標分頁功能。

升級前，請檢查以下任何破壞性變更是否 2026-08-01-preview 適用於你的程式碼：

Agent 擷取的重大變更包括：活動記錄中的巢狀 model 物件、在 MCP 知識來源中以 resultsProcessing 取代伺服器工具的 inclusionMode，以及針對 Work IQ 知識來源採用客戶擁有的 Microsoft Entra 應用程式驗證。關於逐步遷移指引，請參閱「遷移您的代理檢索程式碼」。
資料來源、索引子、索引、技能集和知識來源的清單作業不再使用 $top、$skip 和 $count，而改為使用 pageSize、search 和 @odata.nextLink 的游標分頁。欲了解更多新分頁機制，請參閱「透過 Azure AI 搜尋服務頁面列表結果（預覽）」。

對於其他所有現有的 API，行為都沒有變更。你可以換入新的 API 版本，程式碼也能跟以前一樣執行。

升級至 2026-05-01-preview

2026-05-01-preview 新增了新的知識來源類型、檢索動作的新參數、新的SharePoint索引器內容類型與 ACL 選項，以及其他功能。

與 2025-11-01-preview 相比，沒有線路層級的重大變更。然而，如果你使用 Python 或 JavaScript SDK 進行代理檢索，擷取用戶端會被重新命名為 KnowledgeBaseRetrievalClient，而 retrieveKnowledge(...) 則被替換為 retrieve(...)。關於 SDK 遷移的指引，請參見「遷移你的代理檢索程式碼」。

對於其他所有現有的 API，行為都沒有變更。你可以換入新的 API 版本，程式碼也能跟以前一樣執行。

升級至 2026-04-01

2026-04-01 是最新穩定的 REST API 版本。它會將代理式擷取、部分知識來源，以及數項技能和功能提升為正式發行。

升級前，請檢查以下任何破壞性變更是否 2026-04-01 適用於你的程式碼：

有六個屬性從生成式人工智慧提示技能定義中移除：httpMethodtimeoutbatchSizedegreeOfParallelismhttpHeadersauthResourceId。升級前請先移除這些房產。仍包含這些性質的定義會回傳 400 Bad Request 錯誤。
代理式擷取現在需要自己的計費同意。如果你目前擁有 semanticSearch=standard，你必須在升級前明確設定 knowledgeRetrieval=standard。欲了解更多資訊，請參閱啟用或停用代理檢索計費。
如果您的代理檢索程式碼鎖定2025-11-01-preview，則2026-04-01會移除多項預覽功能，並使檢索操作圍繞意圖輸入、具體輸出及最小推理進行標準化。欲了解更多資訊，請參閱遷移您的代理檢索程式碼。

對於其他所有現有的 API，行為都沒有變更。你可以換入新的 API 版本，程式碼也能跟以前一樣執行。

升級至 2025-11-01 預覽版

2025-11-01-preview 對 2025-08-01-preview 中實作的代理式擷取導入下列重大變更：

替換 agents 為 knowledgebases。與知識來源相關的多個屬性從知識庫定義中移出，轉而進入檢索動作。
知識來源屬性經過重構，並實作了一個新的 ingestionParameters 物件，用於產生索引子管線的知識來源。

有關屬性層級變更與遷移步驟的完整清單，請參見遷移您的代理檢索程式碼。

對於其他所有現有的 API，行為都沒有變更。你可以換入新的 API 版本，程式碼也能跟以前一樣執行。

升級至 2025-09-01

2025-09-01 是一個穩定的 REST API 版本，新增了 OneLake 索引器、文件排版技能及其他 API 的普遍可用性。

如果你是從 2024-07-01 升級，且沒有使用任何預覽功能，那麼就不會有破壞性的變更。要使用新的穩定版本，請更改 API 版本並測試你的程式碼。

升級至 2025-08-01-預覽

2025-08-01-preview 對使用 2025-05-01-preview 建立的知識 Agent 導入下列重大變更：

替換 targetIndexes 為 knowledgeSources。
去除 defaultMaxDocsForReranker 且不替換。

除此之外，現有 API 不會有行為上的改變。你可以換入新的 API 版本，程式碼也能跟以前一樣執行。

升級至 2025-05-01-預覽

2025-05-01-preview 提供新功能，但現有 API 沒有行為變更。你可以換入新的 API 版本，程式碼也能跟以前一樣執行。

升級至 2025-03-01-預覽

2025-03-01-preview 提供新功能，但現有 API 沒有行為變更。你可以換入新的 API 版本，程式碼也能跟以前一樣執行。

升級至 2024年11月01日預覽版

2024-11-01-preview 查詢重寫、Document Layout 技能、技能處理的無金鑰計費、Markdown 剖析模式，以及壓縮向量的重新評分選項。

如果您正從 2024-09-01-preview 升級，可以替換成新的 API 版本，程式碼將會跟以前一樣運行。

然而，新版本引入了對vectorSearch.compressions的語法變更。

替換 rerankWithOriginalVectors 為 enableRescoring
移動 defaultOversampling 到新的 rescoringOptions 屬性物件

由於內部 API 映射，向下相容性得以保留，但若採用新預覽版，建議更改語法。語法比較請參見「使用純量或二元量化壓縮向量」。

升級至 2024-09-01-預覽版

2024-09-01-preview 新增 text-embedding-3 模型的 Matryoshka Representation Learning (MRL) 壓縮、混合式查詢的目標向量篩選、用於偵錯的向量子分數詳細資料，以及文字分割技能的詞元區塊化。

如果您正從 2024-05-01-preview 升級，可以替換成新的 API 版本，程式碼將會跟以前一樣運行。

升級至 2024-07-01

2024-07-01 是一般發行版本。先前的預覽功能現已普遍提供：整合分塊與向量化（Text Split 技能、AzureOpenAIEmbedding 技能）、基於 AzureOpenAIEmbedding 的查詢向量器、向量壓縮（純量量化、二進位量化、儲存屬性、窄資料型態）。

從 2024-05-01-preview 升級到穩定版本不會有破壞性的變更。要使用新的穩定版本，請更改 API 版本並測試你的程式碼。

如果您直接從 2023-11-01 升級，會有重大變更。請按照為每個較新的預覽版本列出的步驟，從 2023-11-01 遷移到 2024-07-01。

升級至 2024-05-01-預覽

2024-05-01-preview 新增了 Microsoft OneLake索引器、二進位向量及更多嵌入模型。

如果你從2024-03-01-preview升級，AzureOpenAIEmbedding 功能現在需要提供模型名稱和尺寸屬性。

搜尋你的程式碼庫，搜尋 AzureOpenAIEmbedding 的參考資料。
設定 modelName 為「text-embedding-ada-002」，並設定 dimensions 為「1536」。

升級至 2024-03-01-預覽

2024-03-01-preview 新增窄資料型態、純量量化及向量儲存選項。

如果您從2023-10-01-preview升級，則不會有重大變更。不過，有一個行為差異：對於 2023-11-01 和較新的預覽版，vectorFilterMode 預設值已從篩選運算式的後置篩選變更為前置篩選。

搜尋你的程式碼庫以尋找 vectorFilterMode 參考資料。
如果屬性是明確設定的，則不需要任何動作。如果你依賴預設值，新的預設行為是在查詢執行前先過濾。如果你想要查詢後的過濾，可以明確設定 vectorFilterMode 為後過濾以保留舊的行為。

升級至 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-預覽

2023-10-01-preview 是第一個在索引時加入內建資料分塊與向量化功能，以及內建查詢向量化的預覽版本。它也支援向量索引與前一版本的查詢。

如果你是從前一個版本升級，下一節會有步驟說明。

從 2023-07-01-預覽版升級

不要使用這個 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 或之後才能查詢該索引。

沒有 Portal 遷移功能來升級向量查詢語法。查詢語法變更請參見程式碼升級。

在選擇遷移前，先選擇 編輯 JSON 以檢視更新後的結構。你應該能找到符合程式碼升級部分描述變更的架構。入口遷移僅處理配置為單一向量搜尋演算法的索引。它建立一個預設的設定檔，對應到 2023-07-01-preview 向量搜尋算法。具有多種向量搜尋配置的索引需要手動遷移。

向量索引與查詢的程式碼升級

在建立或更新索引（2023-07-01-preview）中，引入了向量搜尋支援。

從 2023-07-01-preview 升級到任何更新的穩定版或預覽版需要：

索引中向量配置的重新命名與重組
重寫你的向量查詢

請使用本節的指示，將向量場、配置與查詢遷移至 2023-07-01-preview。

呼叫 Get Index 以取得現有的定義。

修改向量搜尋配置。 2023-11-01 而後續版本則引入了向 量剖面 的概念，將向量相關的配置集中在一個名稱下。新版本也會重新命名 algorithmConfigurations 為 algorithms。

重新命名 algorithmConfigurations 為 algorithms。這只是陣列的重新命名。內容是向下相容的。這表示你可以使用你現有的 HNSW 配置參數。
加入 profiles，為每個提供名稱及演算法配置。

遷移前（2023-07-01-預覽）：

  "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-預覽）：

  {
      "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"
  }

請致電「建立」或「更新索引」來發布變更。

修改搜尋 POST 以更改查詢語法。此 API 變更使多型向量查詢類型得以支援。

重新命名 vectors 為 vectorQueries。
對每個向量查詢，加入 kind，並將其設為 vector。
對每個向量查詢，將重新命名 value 為 vector。
如果你使用vectorFilterMode，可以選擇新增對於 2023-10-01 之後建立的索引，預設值是前置篩選。在該日期之前建立的索引，不管你怎麼設定濾鏡模式，都只支援後置篩選器。

之前（2023-07-01-預覽）：

{
    "search": "*", //Required by the API but ignored for ranking in vector-only queries
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}

之後（2023-11-01）：

{
  "search": "*", //Required by the API but ignored for ranking in vector-only queries
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}

這些步驟完成了遷移到 2023-11-01 穩定 API 版本或更新的預覽版 API 版本。

升級至 2020-06-30

在這個版本中，有一個重大改變和幾個行為上的差異。一般可用的功能包括：

知識儲存，持續儲存透過技能組創造的豐富內容，並用於後續分析與處理，透過其他應用程式進行。知識庫是透過 Azure AI 搜尋服務 REST API 建立的，但它位於 Azure 儲存體中。

重大變更

針對較早版本的 API 撰寫的程式碼若包含以下功能，則在使用2020-06-30及後續版本時會中斷：

任何Edm.Date字面值（由年-月-日組成的日期，例如 2020-12-12）在濾波表達式中必須遵循格式：Edm.DateTimeOffset2020-12-12T00:00:00Z。此變更是為了處理因時區差異導致的錯誤或意外查詢結果。

行為改變

BM25 排名演算法以更新技術取代先前的排名演算法。 2019 年後建立的服務會自動使用此演算法。對於較舊的服務，你必須設定參數才能使用新演算法。
此版本中，空值的排序結果有所變更：若排序為 asc，空值會出現在最前面；若排序為 desc，空值會出現在最後面。如果你寫了程式碼來處理 null 值的排序方式，請注意這個變更。

更新至 2019年05月06日

此 API 版本中普遍可用的功能包括：

自動完成是一項預先輸入功能，可完成部分指定的詞彙輸入。
Complex types 提供搜尋索引中結構化物件資料的原生支援。
JsonLines 解析模式，屬於 Azure Blob 索引的一部分，會為每個以換行分隔的 JSON 實體建立一個搜尋文件。
AI 擴充提供使用 Foundry Tools 的 AI 擴充引擎進行索引。

重大變更

針對較早版本的 API 撰寫的程式碼如果包含以下功能，在 2019-05-06 版及更高版本上將會失效：

Azure Cosmos DB 的類型屬性針對以 Azure Cosmos DB 的 NoSQL API 為資料來源的索引器，請將更改為 "type": "documentdb"。
如果你的索引器錯誤處理包含對該 status 屬性的引用，你應該將其移除。我們從錯誤回應中移除了狀態，因為它沒有提供有用的資訊。
回應中不再回傳資料來源連接字串。從 API 版本 2019-05-06 起 2019-05-06-Preview ，資料來源 API 不再在任何 REST 操作的回應中回傳連接字串。在先前的 API 版本中，對於使用 POST 建立的資料來源，Azure AI 搜尋服務回傳 201，接著是包含明文連線字串的 OData 回應。
具名實體辨識認知技能已淘汰。如果你在程式碼中呼叫了名稱實體識別技能，呼叫就會失敗。替代功能為實體識別技能（V3）。請依照棄用技能中的建議遷移到支援技能。

升級複雜類型

API 版本 2019-05-06 新增了對複雜型別的正式支援。如果你的程式碼在 2017-11-11-Preview 或 2016-09-01-Preview 中實作了先前對複雜型別等價性的建議，則從版本 2019-05-06 開始有一些新的且變更的限制，你需要注意：

子欄位深度及每個索引複數集合數量的限制已降低。如果你用預覽版 API 版本建立的索引超過這些限制，任何用 API 版本 2019-05-06 更新或重建的嘗試都會失敗。如果你遇到這種情況，你需要重新設計你的結構以符合新的限制，然後重建你的索引。
從 API 版本 2019-05-06 開始，每份文件對複雜集合元素的數量有新的限制。如果你使用預覽版 API 版本建立的索引文件超過這些限制，任何用 api 版本 2019-05-06 重新索引該資料的嘗試都會失敗。如果你遇到這種情況，你需要在重新索引資料前，減少每份文件的複雜集合元素數量。

欲了解更多資訊，請參閱服務限制，Azure AI 搜尋服務。

如何升級舊有的複雜型結構

如果你的程式碼使用複雜型別，搭配較舊的預覽 API 版本，你可能使用的索引定義格式如下：

{
  "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 版本 2017-11-11-Preview 更新成新格式，才能用 API 版本 2019-05-06 來管理。

您可以使用 API 版本 2017-11-11-Preview，透過以下步驟將平面索引更新為新格式：

執行 GET 請求以取得你的索引。如果已經是新格式，那你就完成了。
將索引從平面格式轉換成新格式。你必須為這個任務寫程式碼，因為目前沒有可用的範例程式碼。
執行 PUT 請求，將索引更新為新格式。避免更改索引的其他細節，例如欄位的可搜尋性或可過濾性，因為 Update Index API 不允許改變現有索引的物理表達式。

註

無法管理從 Azure 入口網站建立的舊版「平面」格式索引。請盡快將你的指數從「平面」表示升級為「樹狀」表示。

控制平面升級

適用於：2014-07-31-Preview、 2015-02-28、 2015-08-19

listQueryKeys舊版搜尋管理 API 上的 GET 請求現已被棄用。我們建議遷移到最新的穩定控制平面 API 版本以使用 listQueryKeys POST 請求。

在現有程式碼中，將參數改 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，建議升級到最新版本。

下一步

請參考 Search REST API 參考文件。如果你遇到問題，請在 Stack Overflow 尋求協助或聯絡客服。

搜尋服務 REST API 參考

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-31

升級到 Azure AI 搜尋服務 中的最新 REST API

何時升級

如何升級

重大變更

代理檢索的重大變更

知識代理的重大變更

讀取連線資訊的用戶端程式碼的破壞性變更

語意排名器的重大變更

資料平面升級

升級至 2026-08-01-preview

升級至 2026-05-01-preview

升級至 2026-04-01

升級至 2025-11-01 預覽版

升級至 2025-09-01

升級至 2025-08-01-預覽

升級至 2025-05-01-預覽

升級至 2025-03-01-預覽

升級至 2024年11月01日預覽版

升級至 2024-09-01-預覽版

升級至 2024-07-01

升級至 2024-05-01-預覽

升級至 2024-03-01-預覽

升級至 2023-11-01

升級至 2023-10-01-預覽

從 2023-07-01-預覽版 升級

向量索引的入口升級

向量索引與查詢的程式碼升級

升級至 2020-06-30

重大變更

行為改變

更新至 2019年05月06日

重大變更

升級複雜類型

如何升級舊有的複雜型結構

控制平面升級

下一步

意見反應

其他資源

升級到 Azure AI 搜尋服務中的最新 REST API

從 2023-07-01-預覽版升級