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

發行項
12/10/2024

在本文中，了解如何使用管理 REST API 建立和設定 Azure AI 搜尋服務。只有管理 REST API 保證能夠早期存取預覽功能。

管理 REST API 提供穩定版和預覽版。如果您要存取預覽功能，請務必設定預覽 API 版本。

建立或更新服務
啟用資料平面的 Azure 角色型存取控制
強制執行客戶自控金鑰原則
停用語意排名工具
停用將資料推送至外部資源的工作負載
建立查詢金鑰
重新產生系統管理金鑰
列出私人端點連線
列出搜尋作業
刪除搜尋服務

所有管理 REST API 都有範例。如果本文未涵蓋某項工作，請改為參閱 API 參考。

必要條件

Azure 訂用帳戶 - 建立免費帳戶。
具有 REST 用戶端 (英文) 的 Visual Studio Code (英文)
Azure CLI 用於取得存取權杖。您必須是 Azure 訂用帳戶中的擁有者或系統管理員。

取得存取權杖

管理 REST API 呼叫是透過 Microsoft Entra ID 進行驗證。您必須根據要求提供存取權杖，以及建立和設定資源的存取權限。

您可以使用 Azure CLI 或 Azure PowerShell 來建立存取權杖。

開啟 Azure CLI 的命令殼層。
登入 Azure 訂用帳戶。
```
az login
```
取得租用戶識別碼和訂用帳戶識別碼。如果您有多個租用戶或訂用帳戶，請務必使用正確的租用戶或帳戶。
```
az account show
```

取得存取權杖。

az account get-access-token --query accessToken --output tsv

您應具有租用戶識別碼、訂用帳戶識別碼和持有人權杖。您將在下一個步驟中建立的 .rest 或 .http 檔案中貼上這些值。

設定 Visual Studio Code

如果您不熟悉 Visual Studio Code 的 REST 用戶端，本節包含設定方式，以便您可以完成本快速入門中的工作。

啟動 Visual Studio Code，然後選取 [延伸模組] 圖格。
搜尋 REST 用戶端，然後選取 [安裝]。
開啟或建立以 .rest 或 .http 副檔名命名的新檔案。

提供您在上一步中擷取之值的變數。

@tenantId = PASTE-YOUR-TENANT-ID-HERE
@subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
@token = PASTE-YOUR-TOKEN-HERE

透過列出訂用帳戶中的搜尋服務，確認工作階段是否正常運作。

 ### List search services
 GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
      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 = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-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"
        }
      }

建立 S3HD 服務

建立 S3HD 服務時，會使用 sku 與 hostingMode 屬性的組合。將 sku 設定為 standard3，「hostingMode」設定為 HighDensity。

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-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。

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

強制執行客戶自控金鑰原則

如果您使用客戶管理的加密，且您希望搜尋服務報告其合規性狀態，則可以啟用「encryptionWithCMK」，並將 [強制] 設定為 [已啟用]。

當您啟用此原則時，如果未提供加密金鑰，則建立包含敏感性資料 (例如資料來源內的連接字串) 物件的任何 REST 呼叫便會失敗："Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

停用語意排名工具

雖然預設未啟用語意排名工具，但您可以鎖定服務層級的功能，以確保無法使用該功能。

### disable semantic ranker
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

停用將資料推送至外部資源的工作負載

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

### disable-external-access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

刪除搜尋服務

### delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

列出管理員 API 金鑰

### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

重新產生管理 API 金鑰

您一次只能重新產生一個系統管理員 API 金鑰。

### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

建立查詢 API 金鑰

### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

列出私人端點連線

### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

列出搜尋作業

### List search operations
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

下一步

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

共用方式為