Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
了解如何使用 Management REST API 建立並設定 Foundry IQ(Azure AI 搜尋服務)服務。 只有管理 REST API 保證提供早期存取預覽功能。
Management REST API 提供穩定版與預覽版。 如果你正在使用預覽功能,務必設定預覽 API 版本。
所有管理 REST API 都有範例。 如果本文未涵蓋某項任務,請參考 API 參考文獻 。
提示
如果你用 CURL 呼叫管理 REST API,記得把內容型別標頭設為 application/json: -H "Content-Type: application/json"。 或者,如果你想嵌入 JSON 檔案,也可以使用 --JSON 標誌。
先決條件
一個有有效訂閱的 Azure 帳號。 免費建立帳戶。
Azure CLI 以取得存取權杖,步驟如下所述。 您必須是 Azure 訂閱的擁有者或管理員。
Management REST API 呼叫透過 Microsoft Entra ID 進行認證。 你必須在請求時提供存取權杖,並取得建立和設定資源的權限。 除了Azure CLI之外,你還可以用 Azure PowerShell 來建立一個存取權杖。
開啟適用於 Azure CLI 的命令介面。
登入你的 Azure 訂閱。 如果你有多個租戶或訂閱,務必選擇正確的。
az login取得租戶ID和訂閱ID。
az account show申請一個存取權。
az account get-access-token --query accessToken --output tsv你應該有租戶 ID、訂閱 ID 和持有人代幣。 你會把這些值貼到你下一步建立的
.rest或.http檔案中。
設定 Visual Studio Code
如果你不熟悉 Visual Studio Code 的 REST 客戶端,本節包含設定說明,讓你能完成本文中的任務。
開始Visual Studio Code並選擇 Extensions圖塊。
搜尋 REST 用戶端並選擇 安裝。
開啟或建立新檔案,名稱附有
.rest或.http的副檔名。為在前一步驟中取得的數值提供變數。
@tenant-id = PUT-YOUR-TENANT-ID-HERE @subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE @token = PUT-YOUR-TOKEN-HERE請在您的訂閱中列出 Foundry IQ 服務,以確認工作階段是否運作。
### List search services GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01 HTTP/1.1 Content-type: application/json Authorization: Bearer {{token}}選擇 「發送請求」。 回應應該會出現在相鄰的窗格。 如果你已有 Foundry IQ 服務,這些服務都會列出。 否則,清單是空的,但只要 HTTP 代碼是 200 OK,你就準備好進行下一步了。
HTTP/1.1 200 OK Cache-Control: no-cache Pragma: no-cache Content-Length: 22068 Content-Type: application/json; charset=utf-8 Expires: -1 x-ms-ratelimit-remaining-subscription-reads: 11999 x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c Strict-Transport-Security: max-age=31536000; includeSubDomains X-Content-Type-Options: nosniff X-Cache: CONFIG_NOCACHE X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z Date: Thu, 14 Mar 2024 01:20:52 GMT Connection: close { "value": [ . . . ] }
建立或更新服務
在目前訂閱下建立或更新 Foundry IQ 服務。 此範例使用尚未定義的 Foundry IQ 服務名稱與區域變數。 要麼直接提供名稱,要麼在集合中新增變數。
### Create a search service (provide an existing resource group)
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"location": "North Central US",
"sku": {
"name": "basic"
},
"properties": {
"replicaCount": 1,
"partitionCount": 1,
"hostingMode": "default"
}
}
建立一個帶有自動生成 DNS 標籤的服務
自動產生的 DNS 標籤會為您的 Foundry IQ 服務端點主機名稱新增生成的後綴。 Foundry IQ 會自動產生標籤;您僅選擇其重用範圍。 範圍決定標籤是否為唯一,或在你的訂閱或 Microsoft Entra 租戶中,是否會針對相同的服務名稱重複使用。
建立服務時,請透過 2026-09-01-preview 管理 REST API 設定此功能。 建立時選擇標籤的重用範圍,因為之後無法更改範圍。
如果你省略 autoGeneratedDomainNameLabelScope 或設定為 null,服務會使用預設端點格式,沒有自動產生的標籤。
請使用上述 的前置條件 和 REST 用戶端變數 。 設定 resource-group 為現有資源群組、search-service 為新的服務名稱,以及 region 為你訂閱可用的區域。
以下請求會建立一個具有唯一標籤的 Basic 服務:
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-NEW-SERVICE-NAME-HERE
@region = PUT-YOUR-REGION-HERE
### Create a service with an auto-generated DNS label
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2026-09-01-preview HTTP/1.1
Content-Type: application/json
Authorization: ******
{
"location": "{{region}}",
"sku": {
"name": "basic"
},
"properties": {
"replicaCount": 1,
"partitionCount": 1,
"autoGeneratedDomainNameLabelScope": "NoReuse"
}
}
配置成功後,回應會包含產生的端點及所選範圍:
{
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/my-resource-group/providers/Microsoft.Search/searchServices/mysearchservice",
"name": "mysearchservice",
"type": "Microsoft.Search/searchServices",
"location": "westus",
"sku": {
"name": "basic"
},
"properties": {
"endpoint": "https://mysearchservice-12345678abcdefgh.sg.search.windows.net/",
"provisioningState": "Succeeded",
"autoGeneratedDomainNameLabelScope": "NoReuse"
}
}
參考資料: Foundry IQ 服務建立或更新。
在連接資料平面 API 之前,先從服務回應讀取 properties.endpoint。 具有自動產生標籤的端點格式如下: https://<service-name>-<label>.sg.search.windows.net/。 服務的name和 Azure Resource Manager 資源id不會改變。
請選擇下列其中一個值:
| Value | 標籤重複使用 |
|---|---|
NoReuse |
為服務名稱產生唯一標籤,無論租戶或訂閱為何。 |
SubscriptionReuse |
在訂閱中為相同的服務名稱重複使用標籤。 |
TenantReuse |
在同一個 Microsoft Entra 租用戶內,針對相同的服務名稱重複使用標籤。 |
參考資料: Foundry IQ 服務屬性。
升級服務
部分 Foundry IQ 功能僅提供給新服務。 為了避免服務重現並將這些功能帶到現有服務,你或許可以 升級服務。
### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
變更定價層級
如果你需要更多或更少的容量,可以 切換到不同的價格等級。 目前你只能在基本和標準(S1、S2、S3)等級之間切換。 使用該 sku 屬性來指定新的階層。
### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"sku": {
"name": "standard2"
}
}
建立 S3HD 服務
要建立 S3HD 服務,請結合 sku 和 hostingMode 屬性。 設定 sku 為 , standard3 且「hostingMode」設為 HighDensity。
### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"location": "{{region}}",
"sku": {
"name": "standard3"
},
"properties": {
"replicaCount": 1,
"partitionCount": 1,
"hostingMode": "HighDensity"
}
}
設定資料平面的角色型存取
適用於: 搜尋索引資料貢獻者、搜尋索引資料閱讀器、搜尋服務貢獻者
將您的 Foundry IQ 服務設定為在提供 OAuth2 存取權杖的資料請求時識別 授權標頭 。
若要使用基於角色的存取控制來進行資料平面操作,請設定 authOptions 為 並 aadOrApiKey 發送請求。
若要完全使用基於角色的存取控制,請在進行第二個請求時關閉API 金鑰認證,這次將 disableLocalAuth 設定為 true。
### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"disableLocalAuth": false,
"authOptions": {
"aadOrApiKey": {
"aadAuthFailureMode": "http401WithBearerChallenge"
}
}
}
}
配置機密運算
機密運算 是一種可選的計算類型,用於保護正在使用的資料。 設定完成後,您的 Foundry IQ 服務會部署在機密虛擬機(DCasv5 或 DCesv5)上,而非標準虛擬機。 此運算類型對收費層級需加收 10% 附加費。 欲了解更多資訊,請參閱 價格頁面。
日常使用時,機密運算並非必要。 我們僅在嚴格的法規、合規或安全要求下推薦使用此運算類型。 欲了解更多資訊,請參閱 機密運算的使用案例。
計算類型在您的 Foundry IQ 服務生命週期內固定不變。 若要永久配置機密運算,請在新服務上將屬性computeType設為confidential。
### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"location": "{{region}}",
"sku": {
"name": "basic"
},
"properties": {
"computeType": "confidential"
}
}
執行由客戶管理的金鑰政策
如果您使用 客戶管理的加密,您可以啟用「encryptionWithCMK」並將「enforcement」設為「啟用」,讓您希望 Foundry IQ 服務回報其合規狀態。
啟用此政策後,任何建立包含敏感資料(如資料來源內連接字串)物件的 REST 呼叫,若未提供加密金鑰,將失敗:"Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."
### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"encryptionWithCmk": {
"enforcement": "Enabled"
}
}
}
關閉將資料推送到外部資源的工作負載
Foundry IQ 在更新知識庫、儲存除錯工作階段狀態或快取豐富內容時 ,會寫入外部資料來源 。 以下範例在服務層級禁用這些工作負載。
### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"publicNetworkAccess": "Disabled"
}
}
刪除 Foundry IQ 服務
### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
列出管理員 API 金鑰
### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
重新產生管理員 API 金鑰
你一次只能重新產生一個管理員 API 金鑰。
### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
建立查詢 API 金鑰
### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE
POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
列出私有端點連線
### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
列表搜尋操作
### List search operations
GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
下一步
在設定好 Foundry IQ 服務後,您的下一步包括使用 Azure 入口網站、REST API 或 Azure SDK 建立索引或查詢索引。