Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
在 Foundry IQ(Azure AI 搜尋服務)中,索引別名是搜尋索引的次要名稱。 您可以建立對應到搜尋索引的別名,並在原本會參考索引名稱的位置改用別名名稱。 此功能提供彈性,方便你更改應用程式指向的索引。 你不必更新生產程式碼中索引名稱的引用,只要更新別名映射即可。
您可以透過 HTTP 請求(POST、GET、PUT 或 DELETE)針對指定的別名資源,在 Foundry IQ 服務上建立並管理別名。 別名是服務層級資源,獨立於搜尋索引維護。 建立搜尋索引後,你可以建立一個對應到它的別名。
在使用別名之前,你的應用程式會直接向hotel-samples-index發送請求。
POST /indexes/hotel-samples-index/docs/search?api-version=2026-10-01
{
"search": "pool spa +airport",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
使用別名後,你的應用程式會向 my-alias 發送請求,該請求會對應到 hotel-samples-index。
POST /indexes/my-alias/docs/search?api-version=2026-10-01
{
"search": "pool spa +airport",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
先決條件
- 任何地區與價格層級的 Foundry IQ 服務。
- 一個你想將別名映射到的 現有搜尋索引 。
- 建立別名的權限:
- 針對基於金鑰的驗證,為您的 Foundry IQ 服務提供 管理 API 金鑰 。
- 對於角色型驗證,請使用 Search Service Contributor 角色。
限制與考量
建立索引別名
建立別名會在別名名稱與索引名稱之間建立對應關係。 如果請求成功,你可以用別名來進行索引、查詢及其他操作。
你可以透過 REST API、Azure SDK 或 Azure 入口網站來建立別名。 別名由name和該別名所對應的搜尋索引名稱組成。 你只能在陣列中 indexes 指定一個索引名稱。
你能建立的最大別名數量會依價格層級而異。 欲了解更多資訊,請參閱 索引別名限制。
使用最新穩定版的 Aliases - Create (REST API) 來建立索引別名。
POST /aliases?api-version=2026-10-01
{
"name": "my-alias",
"indexes": ["hotel-samples-index"]
}
將請求傳送到索引別名
你可以用別名來處理所有文件操作,包括查詢、索引、建議和自動補全。
以下查詢會將請求傳送至 my-alias,其對應到您 Foundry IQ 服務中的實際索引。
POST /indexes/my-alias/docs/search?api-version=2026-10-01
{
"search": "pool spa +airport",
"searchMode": "any",
"queryType": "simple",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
取得別名定義
使用 Aliases - List (REST API) 以名稱回傳現有別名物件的清單。
GET /aliases?api-version=2026-10-01&$select=name
使用 Aliases - Get (REST API) 來回傳特定別名的定義。
GET /aliases/my-alias?api-version=2026-10-01
更新別名
別名最常見的更新是當底層索引被更新版本取代時,會更改索引名稱。
使用 Aliases - Create 或 Update (REST API)來更新別名。 以下範例說明如何更新 my-alias 以指向 hotel-samples-index2 而非 hotel-samples-index。
PUT /aliases/my-alias?api-version=2026-10-01
{
"name": "my-alias",
"indexes": ["hotel-samples-index2"]
}
別名的更新可能需要長達 10 秒才能在系統中傳遞,因此在刪除該別名先前對應的索引前,至少要等 10 秒。
如果你嘗試刪除目前映射到別名的索引,操作會失敗,會出現 400(錯誤請求)並跳出錯誤訊息,說明該別名必須先刪除或映射到其他索引,才能刪除該索引。