快速入門：不使用密鑰連線

發行項
12/20/2024

將 Azure AI 搜尋設定為使用 Microsoft Entra ID 驗證和角色型存取控制（RBAC），讓您可以使用 Jupyter Notebook 或 REST 用戶端來與搜尋服務互動，從本機系統連線到沒有 API 密鑰。

如果您逐步執行使用 API 金鑰連線的其他快速入門，本快速入門會示範如何切換至以身分識別為基礎的驗證，以避免範例程式代碼中的硬式編碼密鑰。

必要條件

Azure 訂用帳戶。免費建立一個。
Azure AI 搜尋，任何區域或層級，但您需要基本或更高層級來設定 Azure AI 搜尋的受控識別。
命令行工具，例如 PowerShell 或 Bash，以及 Azure CLI。

步驟 1：取得您的 Azure 訂用帳戶和租用戶標識碼

如果您有一個以上的訂用帳戶或租使用者，則需要此步驟。

取得搜尋服務的 Azure 訂用帳戶和租使用者：
1. 登入 Azure 入口網站並流覽至您的搜尋服務。
2. 請注意 Overview Essentials 中的>訂用帳戶名稱和標識碼。
3. 現在選取訂用帳戶名稱，以顯示下一頁的父管理群組（租用戶標識元）。
您現在知道哪個訂用帳戶和租使用者 Azure AI 搜尋正在下。切換至本機裝置和命令提示字元，並識別裝置上作用中的 Azure 訂用帳戶和租使用者：
```
az account show
```
如果作用中的訂用帳戶和租使用者與上一個步驟中取得的資訊不同，請變更訂用帳戶標識碼。接下來，使用您在上一個步驟中找到的租用戶標識符登入 Azure：
```
 az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>
```

步驟 2：設定 RBAC 的 Azure AI 搜尋

登入 Azure 入口網站並流覽至您的 Azure AI 搜尋服務。
開啟角色型存取控制（RBAC）：
1. 移至 [ 設定>金鑰]。
2. 如果您需要時間將客戶端轉換為角色型訪問控制，請選擇 [角色型控制 ] 或 [兩者 ]。
  
  如果您選擇角色型控件，請確定您在下一個指示中自行指派所有名為的角色，否則您將無法在 Azure 入口網站或透過本機用戶端完成工作。
在 Azure 入口網站中指派角色：
1. 瀏覽至您的搜尋服務。
2. 在左側導覽窗格中選取 [存取控制 (IAM)]。
3. 選取 [+新增]>[新增角色指派]。
4. 選擇角色（Search Service 參與者、搜尋索引數據參與者、搜尋索引數據讀取器），並將它指派給您Microsoft Entra 使用者或群組身分識別。
  
  針對每個角色重複。
  
  您需要搜尋服務參與者加上搜尋索引數據參與者，才能在 Azure AI 搜尋服務上建立、載入和查詢物件。如需詳細資訊，請參閱使用角色連線。

提示

稍後，如果您收到驗證失敗錯誤，請重新檢查本節中的設定。訂用帳戶或資源群組層級可能會有原則覆寫您指定的任何 API 設定。

步驟 3：從本機系統連線

如果您尚未登入 Azure：

az login

使用 Python 和 Jupyter 筆記本

安裝 Azure 身分識別和 Azure 搜尋服務連結庫：
```
pip install azure-identity azure-search-documents
```

驗證並連線到 Azure AI 搜尋：

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = "https://<your-search-service-name>.search.windows.net"
index_name = "hotels-sample-index"

credential = DefaultAzureCredential()
client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)

results = client.search("beach access")
for result in results:
    print(result)

使用 REST 用戶端

數個快速入門和教學課程會使用 REST 用戶端，例如 Visual Studio Code 搭配 REST 擴充功能。以下是從Visual Studio Code 連線到 Azure AI 搜尋的方式。

您應該會有 .rest 或 .http 檔案，類似於快速入門：向量搜尋中所述的檔案。

產生存取權杖。

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

在檔案頂端，設定用於連線的變數、貼上完整搜尋服務端點，以及您在上一個步驟中取得的存取令牌。您的變數看起來應該類似下列範例。請注意，值不會加上引號。
```
@baseUrl = https://contoso.search.search.windows.net
@token = <a long GUID>
```

在 REST 呼叫中指定授權持有人令牌：

 POST https://{{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2024-07-01 HTTP/1.1
   Content-type: application/json
   Authorization: Bearer {{token}}

     {
          "queryType": "simple",
          "search": "beach access",
          "filter": "",
          "select": "HotelName,Description,Category,Tags",
          "count": true
      }

針對 401 錯誤進行疑難解答

檢查作用中的訂用帳戶和租使用者（az account show），並確定它對您的搜尋服務有效。
檢查 Azure 入口網站中的搜尋服務 [設定>金鑰] 選項，並確認服務已針對 [兩者] 或 [角色型訪問控制] 進行設定。
僅適用於 REST 用戶端：檢查檔案中指定的令牌和端點，並確定沒有周圍引號或額外空格。

如果所有其他項目都失敗，請重新啟動您的裝置以移除任何快取的令牌，然後重複本節中的步驟，從開始 az login。

其他設定

設定輸出連線的受控識別：

為您的搜尋服務設定系統指派或使用者指派的受控識別。
使用角色指派來授權存取其他 Azure 資源。

網路存取設定：

設定輸入規則，以根據IP位址接受或拒絕對Azure AI搜尋的要求。

共用方式為