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

發行項
06/14/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

設定 Visual Studio Code

如果您不熟悉 Visual Studio Code 的 REST 用戶端，本節會包含安裝程式，讓您可以完成本快速入門中的工作。

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

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

@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 屬性的組合。將設定為 standard3 ，並將「hostingMode」設定sku為 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": "Disabled",
            "encryptionComplianceStatus": "Compliant"
            },
        }
    }

停用語意排名

雖然預設未啟用語意排名，但您可以鎖定服務層級的功能。

### disable semantic ranking
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

建立查詢 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}}

下一步

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

共用方式為