快速入門：連線到搜尋服務

在本快速入門中，您會使用角色型訪問控制 （RBAC） 和 Microsoft Entra ID 來建立 Azure AI 搜尋服務的無密鑰連線。 接著，您會在 Visual Studio Code 中使用 Python 與服務互動。

無密鑰連線可透過細微的許可權和身分識別型驗證來提供增強的安全性。 我們不建議硬式編碼的 API 金鑰，但如果您偏好這些密鑰，請參閱 使用密鑰聯機到 Azure AI 搜尋服務。

先決條件

• 具有有效訂閱的 Azure 帳戶。 免費建立帳戶。

• 任何區域或階層中的 Azure AI 搜尋服務 。

• Azure CLI 用於與 Microsoft Entra ID 進行無密鑰驗證。

• 具有 Python 延伸模組和 Jupyter 套件的 Visual Studio Code。

設定角色型存取

在本節中，您會在 Azure AI 搜尋服務上啟用 RBAC，並指派建立、載入和查詢搜尋物件所需的角色。 如需這些步驟的詳細資訊，請參閱 使用角色連線到 Azure AI 搜尋服務。

若要設定存取：

1. 登入 Azure 入口網站 ，然後選取您的搜尋服務。

2. 從左窗格中，選取 [ 設定 > 金鑰]。

3. 如果您需要時間將客戶端轉換為 RBAC，請選取 [角色型存取控制 ] 或 [ 兩者 ]。

   

4. 從左窗格中，選取 [訪問控制][IAM]。

5. 選取 新增>新增角色指派。

   

6. 將 搜尋服務參與者 角色指派給用戶帳戶或受控識別。

7. 重複 搜尋索引數據參與者的角色指派。

取得服務資訊

在本節中，您會擷取 Azure AI 搜尋服務的訂用帳戶標識碼和端點。 如果您只有一個訂用帳戶，請略過訂用帳戶標識碼，並只擷取端點。 在本快速入門的其餘區段中，您會使用這些值。

若要取得您的服務資訊：

1. 登入 Azure 入口網站 ，然後選取您的搜尋服務。

2. 從左窗格中，選取 [ 概觀]。

3. 記下訂用帳戶標識碼和端點。

   

登入 Azure

連線到 Azure AI 搜尋服務之前，請使用 Azure CLI 登入包含您服務的訂用帳戶。 此步驟會建立您的Microsoft Entra 身分識別，該 DefaultAzureCredential 身分識別會在下一節中用來驗證要求。

若要登入：

1. 在您的本機系統上，開啟命令行工具。

2. 請檢查本機環境中的作用中訂用帳戶和租用戶。

   az account show
   

3. 如果作用中的訂用帳戶和租用戶對您的搜尋服務無效，請執行以下命令來更新其值。 您可以在 Azure 入口網站的搜尋服務 概覽 頁面找到訂閱 ID。 要找到租戶 ID，請在 「概覽 」頁面選擇您的訂閱名稱，然後找到 父管理群組 的值。

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

連線至 Azure AI 搜尋服務

您可以使用 Visual Studio Code 中的 Python 筆記本，將要求傳送至 Azure AI 搜尋服務。 針對要求驗證，請使用 DefaultAzureCredential Azure 身分識別程式庫中的類別。

若要使用 Python 進行連線：

1. 在您的本機系統上，開啟 Visual Studio Code。

2. 建立 .ipynb 檔案。

3. 建立程式碼單元以安裝 azure-identity 和 azure-search-documents 庫。

   pip install azure-identity azure-search-documents
   

4. 建立另一個代碼區塊以驗證並連接到您的搜尋服務。

   from azure.identity import DefaultAzureCredential
   from azure.search.documents.indexes import SearchIndexClient
   
   service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
   credential = DefaultAzureCredential()
   client = SearchIndexClient(endpoint = service_endpoint, credential = credential)
   
   # List existing indexes
   indexes = client.list_indexes()
   
   for index in indexes:
      index_dict = index.as_dict()
      print(json.dumps(index_dict, indent = 2))
   

5. 將 service_endpoint 設定為從 取得服務資訊 所得的值。

6. 選擇 全部執行 來執行兩個程式碼區塊。

   輸出應該會列出搜尋服務上現有的索引（如果有的話），表示連線成功。

針對 401 錯誤進行疑難排解

如果您遇到 401 錯誤，請遵循下列疑難解答步驟：

• 重新檢視 配置基於角色的存取權限。 您的搜尋服務必須啟用 角色型訪問控制 或 兩者 皆已啟用。 訂閱或資源群組層級的政策可能會取代你的角色分配。

• 重新查看登入 Azure。 您必須登入包含搜尋服務的訂用帳戶。

• 請確定您的端點變數有周圍的引號。

• 如果所有其他動作都失敗，請重新啟動您的裝置以移除快取的權杖，然後重複此快速入門中的步驟，從 [登入 Azure] 開始。

在本快速入門中，您會使用角色型訪問控制 （RBAC） 和 Microsoft Entra ID 來建立 Azure AI 搜尋服務的無密鑰連線。 然後在 Visual Studio Code 中使用 REST 來與您的服務互動。

無密鑰連線可透過細微的許可權和身分識別型驗證來提供增強的安全性。 我們不建議硬式編碼的 API 金鑰，但如果您偏好這些密鑰，請參閱 使用密鑰聯機到 Azure AI 搜尋服務。

先決條件

• 具有有效訂閱的 Azure 帳戶。 免費建立帳戶。

• 任何區域或階層中的 Azure AI 搜尋服務 。

• Azure CLI 用於與 Microsoft Entra ID 進行無密鑰驗證。

• Visual Studio Code 搭配 REST 用戶端擴充套件。

設定角色型存取

在本節中，您會在 Azure AI 搜尋服務上啟用 RBAC，並指派建立、載入和查詢搜尋物件所需的角色。 如需這些步驟的詳細資訊，請參閱 使用角色連線到 Azure AI 搜尋服務。

若要設定存取：

1. 登入 Azure 入口網站 ，然後選取您的搜尋服務。

2. 從左窗格中，選取 [ 設定 > 金鑰]。

3. 如果您需要時間將客戶端轉換為 RBAC，請選取 [角色型存取控制 ] 或 [ 兩者 ]。

   

4. 從左窗格中，選取 [訪問控制][IAM]。

5. 選取 新增>新增角色指派。

   

6. 將 搜尋服務參與者 角色指派給用戶帳戶或受控識別。

7. 重複 搜尋索引數據參與者的角色指派。

取得服務資訊

在本節中，您會擷取 Azure AI 搜尋服務的訂用帳戶標識碼和端點。 如果您只有一個訂用帳戶，請略過訂用帳戶標識碼，並只擷取端點。 在本快速入門的其餘區段中，您會使用這些值。

若要取得您的服務資訊：

1. 登入 Azure 入口網站 ，然後選取您的搜尋服務。

2. 從左窗格中，選取 [ 概觀]。

3. 記下訂用帳戶標識碼和端點。

   

登入 Azure

連線到 Azure AI 搜尋服務之前，請使用 Azure CLI 登入包含您服務的訂用帳戶。

若要登入：

1. 在您的本機系統上，開啟命令行工具。

2. 請檢查本機環境中的作用中訂用帳戶和租用戶。

   az account show
   

3. 如果作用中的訂用帳戶和租用戶對您的搜尋服務無效，請執行以下命令來更新其值。 您可以在 Azure 入口網站的搜尋服務 概覽 頁面找到訂閱 ID。 要找到租戶 ID，請在 「概覽 」頁面選擇您的訂閱名稱，然後找到 父管理群組 的值。

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

取得權杖

REST API 呼叫需要包含 Microsoft Entra ID 權杖。 您會使用此 token 來驗證下一節中的要求。

若要取得您的令牌：

1. 使用相同的命令列工具，產生存取權杖。

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

2. 記下權杖輸出。

連線至 Azure AI 搜尋服務

您可以使用 Visual Studio Code 中的 REST 用戶端擴充功能，將要求傳送至 Azure AI 搜尋服務。 為了進行請求認證，請加入 Authorization 標頭，該標頭包含了您之前生成的 Microsoft Entra ID 令牌。

若要使用 REST 進行連線：

1. 在您的本機系統上，開啟 Visual Studio Code。

2. 建立 .rest 或 .http 檔案。

3. 將以下變數和請求貼上到檔案中。

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
   @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
   
   ### List existing indexes
   GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
      Content-Type: application/json
      Authorization: Bearer {{token}}
   

4. 將 @baseUrl 設定為從 取得服務資訊 所得的值。

5. 設定 @token 為你在 Get 代幣中獲得的數值。

6. 在 底下 ### List existing indexes，選取 [ 傳送要求]。

   您應該會收到 HTTP/1.1 200 OK 回應，指示您的搜尋服務已成功連線。

針對 401 錯誤進行疑難排解

如果您遇到 401 錯誤，請遵循下列疑難解答步驟：

• 重新檢視 配置基於角色的存取權限。 您的搜尋服務必須啟用 角色型訪問控制 或 兩者 皆已啟用。 訂用帳戶或資源群組層級的原則可能會覆寫您的角色指派。

• 重新查看登入 Azure。 您必須登入包含搜尋服務的訂用帳戶。

• 請確定您的端點和令牌變數沒有周圍引號或額外空格。

• 請確定您的權杖在要求標頭中沒有 @ 符號。 例如，如果變數是 @token，則要求中的參考應該是 {{token}}。

• 如果所有其他動作都失敗，請重新啟動您的裝置以移除快取的權杖，然後重複此快速入門中的步驟，從 [登入 Azure] 開始。