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

  • 發行項

在本文中，瞭解如何使用管理 REST API 來建立及設定 Azure AI 搜尋服務。 只有管理 REST API 保證能提供預覽功能的早期存取權。

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

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

必要條件

取得存取權杖

管理 REST API 呼叫會透過 Microsoft Entra ID 進行驗證。 您必須在要求上提供存取令牌，以及建立和設定資源的許可權。

您可以使用 Azure CLI 或 Azure PowerShell 來建立存取令牌。

  1. 開啟 Azure CLI 的命令殼層。

  2. 登入 Azure 訂用帳戶。

    az login

  3. 取得租用戶標識碼和訂用帳戶標識碼。 如果您有多個租用戶或訂用帳戶，請確定您使用正確的租使用者。

    az account show

  4. 取得存取令牌。

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

設定 Visual Studio Code

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

  1. 啟動 Visual Studio Code，然後選取 [ 延伸模組 ] 圖格。

  2. 搜尋 REST 用戶端，然後選取 [ 安裝]。

    Screenshot of the install command.

  3. 以或 .http 擴展名開啟或建立名為 .rest 的新檔案。

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

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

  5. 藉由列出訂用帳戶中的搜尋服務，確認會話是否正常運作。

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

  6. 選取 [ 傳送要求]。 回應應該會出現在相鄰窗格中。 如果您有現有的搜尋服務，則會列出它們。 否則，清單是空的，但只要 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 服務，請使用 和 hostingMode 屬性的組合sku。 將設定為 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」。，並將 」enforcement“ 設定為 ”Enabled“。

當您啟用此原則時，建立包含敏感數據的物件的任何 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 建立索引 或 查詢索引 。