使用 REST API 管理您的 Azure AI 搜尋服務服務

Note

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

學習如何使用 Management REST API 建立並配置 Azure AI 搜尋服務服務。只有管理 REST API 保證提供早期存取預覽功能。

Management REST API 提供穩定版與預覽版。如果你正在使用預覽功能，務必設定預覽 API 版本。

建立或更新服務
升級服務
變更定價層級
為資料平面設定基於角色的存取控制
配置機密運算
啟用 Azure 基於角色的存取控制以用於資料平面
執行由客戶管理的金鑰政策
關閉將資料推送到外部資源的工作負載
建立查詢鍵
重新產生管理員金鑰
列出私有端點連線
列表搜尋操作
刪除搜尋服務

所有管理 REST API 都有範例。如果本文未涵蓋某項任務，請參考 API 參考文獻。

提示

如果你用 CURL 呼叫管理 REST API，記得把內容型別標頭設為 application/json： -H "Content-Type: application/json"。或者，如果你想嵌入 JSON 檔案，也可以使用 --JSON 標誌。

先決條件

一個有有效訂閱的 Azure 帳號。免費註冊帳號。
Visual Studio Code 配備 REST 客戶端。
Azure CLI 以取得存取權杖，步驟如下。您必須是 Azure 訂閱的擁有者或管理員。

Management REST API 呼叫透過 Microsoft Entra ID 進行認證。你必須在請求時提供存取權杖，並取得建立和設定資源的權限。除了Azure CLI之外，你還可以用 Azure PowerShell 來建立一個存取權杖。
1. 開啟適用於 Azure CLI 的命令介面。
2. 登入你的 Azure 訂閱。如果你有多個租戶或訂閱，務必選擇正確的。
```
az login
```
3. 取得租戶ID和訂閱ID。
```
az account show
```
4. 申請一個存取權。
```
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

要確認會話是否正在運作，請在訂閱中列出搜尋服務。

 ### 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}}

選擇 「發送請求」。回應應該會出現在相鄰的窗格。如果你有現有的搜尋服務，這些服務都會被列出。否則，清單是空的，但只要 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": [ . . . ]
}

建立或更新服務

建立或更新目前訂閱下的搜尋服務。這個例子使用搜尋服務名稱和區域的變數，但尚未定義。要麼直接提供名稱，要麼在集合中新增變數。

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

升級服務

部分 Azure AI 搜尋服務功能僅提供給新服務。為了避免服務重現並將這些功能帶到現有服務，你或許可以升級服務。

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

設定資料平面的角色型存取

適用於： 搜尋索引資料貢獻者、搜尋索引資料閱讀器、搜尋服務貢獻者

設定你的搜尋服務，讓它能辨識提供 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"
                }
            }
        }
    }

配置機密運算

機密運算是一種可選的計算類型，用於資料使用中的保護。設定後，您的搜尋服務部署在機密虛擬機（DCasv5 或 DCesv5）上，而非標準虛擬機。此運算類型對收費層級需加收 10% 附加費。欲了解更多資訊，請參閱價格頁面。

日常使用時，機密運算並非必要。我們僅在嚴格的法規、合規或安全要求下推薦使用此運算類型。欲了解更多資訊，請參閱機密運算的使用案例。

計算類型在搜尋服務的整個壽命內是固定的。若要永久配置機密運算，請在新服務上將屬性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」設為「啟用」，這樣搜尋服務就能回報其合規狀態。

啟用此政策後，任何建立包含敏感資料（如資料來源內連接字串）物件的 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"
            }
        }
    }

關閉將資料推送到外部資源的工作負載

Azure AI 搜尋服務在更新知識存放區、儲存偵錯工作階段狀態，或快取擴充時，會寫入外部資料來源。以下範例在服務層級禁用這些工作負載。

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

刪除搜尋服務

### 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}}

下一步

搜尋服務設定完成後，下一步包括使用 Azure入口網站、REST API 或 Azure SDK，建立索引或查詢索引。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-03