用身份把你的應用程式連接到 Azure AI 搜尋

在你的應用程式碼中，你可以設定一個無鑰匙連接 Azure AI Search，使用 Microsoft Entra ID 和角色來進行認證與授權。大多數 Azure 服務的應用程式請求必須以金鑰或無密鑰連線進行認證。開發人員必須盡可能避免在不安全的地方公開金鑰。能夠取得金鑰存取權的任何人都可以進行服務驗證。無金鑰驗證可透過帳戶金鑰提供改良的管理和安全性優勢，因為沒有要儲存的金鑰 (或連接字串)。

本文說明如何在你的應用程式代碼中使用 DefaultAzureCredential 。

要在程式碼中實作無鍵連接，請遵循以下步驟：

在您的搜尋服務中啟用基於角色的存取權限
視需要設定環境變數。
使用 Azure Identity 函式庫的憑證類型來建立 Azure AI Search 客戶端物件。

先決條件

Azure AI 搜尋，任何區域，但必須是可計費的層級（基礎級或更高階）。
您的搜尋服務已啟用角色為基礎的存取控制。
Azure AI Search 上的職務分配。將以下角色分配給你的身份：
- 搜尋服務貢獻 者及 搜尋索引資料 貢獻者，用於地方發展（完整存取）
- 搜尋索引資料讀取器，用於生產環境中的唯讀查詢
有關逐步說明，請參閱「分配發展角色」。

安裝 Azure 身分識別用戶端程式庫

若要使用無鍵方法，請用 Azure Identity 用戶端函式庫更新你的 AI 搜尋程式碼。

安裝 .NET 的 Azure Identity 用戶端函式庫與 Azure Search Documents 用戶端函式庫：

dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents

安裝以下 POM 檔案的 Azure Identity 用戶端函式庫 (適用於 Java) 和 Azure Search Documents 用戶端函式庫：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.15.1</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

安裝 JavaScript 的 Azure Identity 用戶端函式庫及 Azure Search Documents 用戶端函式庫：

npm install --save @azure/identity @azure/search-documents

安裝 Python 的 Azure Identity 用戶端函式庫和 Azure Search Documents 用戶端函式庫：

pip install azure-identity azure-search-documents

更新原始碼以使用 DefaultAzureCredential

Azure Identity 函式庫 DefaultAzureCredential 允許你在本地開發環境和 Azure 雲端執行相同的程式碼。建立單一憑證，並視需要重複使用該憑證實例，以充分發揮代幣快取的優勢。

欲了解更多 .NET 相關資訊 DefaultAzureCredential ，請參閱 .NET 的 Azure Identity 用戶端函式庫。

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

參考資料：SearchClient， SearchIndexClient， DefaultAzureCredential

欲了解更多關於 DefaultAzureCredential Java 的資訊，請參閱 Azure Identity 用戶端函式庫。

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.search.documents.SearchAsyncClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.indexes.SearchIndexAsyncClient;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;

String ENDPOINT = System.getenv("AZURE_SEARCH_ENDPOINT");
String INDEX_NAME = "my-index";

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Sync SearchClient
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildClient();

// Sync IndexClient
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildClient();

// Async SearchClient
SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildAsyncClient();

// Async IndexClient
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildAsyncClient();

參考資料：SearchClient， SearchIndexClient， DefaultAzureCredential

欲了解更多關於 DefaultAzureCredential JavaScript 的資訊，請參閱 Azure Identity 用戶端函式庫的 JavaScript。

import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  SearchIndexClient
} from "@azure/search-documents";

const AZURE_SEARCH_ENDPOINT = process.env.AZURE_SEARCH_ENDPOINT;
const index = "my-index";
const credential = new DefaultAzureCredential();

// To query and manipulate documents
const searchClient = new SearchClient(
  AZURE_SEARCH_ENDPOINT,
  index,
  credential
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient(
  AZURE_SEARCH_ENDPOINT, 
  credential
);

參考資料：SearchClient， SearchIndexClient， DefaultAzureCredential

欲了解更多關於 DefaultAzureCredential Python 的資訊，請參閱 Azure Identity 用戶端函式庫。

import os
from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Public Cloud
audience = "https://search.azure.com"
authority = AzureAuthorityHosts.AZURE_PUBLIC_CLOUD

service_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
credential = DefaultAzureCredential(authority=authority)

search_client = SearchClient(
    endpoint=service_endpoint, 
    index_name=index_name, 
    credential=credential, 
    audience=audience)

search_index_client = SearchIndexClient(
    endpoint=service_endpoint, 
    credential=credential, 
    audience=audience)

參考資料：SearchClient， SearchIndexClient， DefaultAzureCredential

確認你的連線

設定好客戶端後，執行一個簡單的操作來驗證連線。以下範例列出您搜尋服務上的索引：

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

// List indexes to verify connection
searchIndexClient.listIndexNames().forEach(System.out::println);

// List indexes to verify connection
for await (const name of indexClient.listIndexesNames()) {
  console.log(name);
}

# List indexes to verify connection
for index in search_index_client.list_index_names():
    print(index)

成功連線會印出你的索引名稱（若沒有索引則為空清單）。若收到驗證錯誤，請確認角色基礎存取是否已啟用，以及您的身份是否已被指派所需的角色。

預設權限是 Azure 公共雲。主權雲或專用雲的自訂 audience 值包括：

適用於 Azure Government
https://search.azure.cn 適用於由 21Vianet 運作的 Azure
https://search.microsoftazure.de 適用於 Azure 德國

本地開發

利用角色的地方發展包括以下步驟：

將您的個人身份指派給特定資源上的 RBAC 角色。
使用像 Azure CLI 或 Azure PowerShell 這類工具來與 Azure 進行認證。
為你的資源建立環境變數。

地方發展角色

作為本地開發者，你的 Azure 身份必須完全控制資料平面操作。以下是建議的角色：

搜尋服務貢獻者，建立與管理物件
搜尋索引資料貢獻者，載入並查詢索引

透過以下工具之一找到你的個人身份。將該識別碼用作<identity-id>的值。

在以下指令中，將佔位符<role-name><identity-id><subscription-id><resource-group-name>、和替換為你的實際值。

登入 Azure CLI。
```
az login
```
會開啟一個瀏覽器視窗進行驗證。成功登入後，終端機會顯示您的訂閱資訊。
建立你的個人身份。
```
az ad signed-in-user show \
    --query id -o tsv
```
這個指令會回傳你的使用者物件 ID（GUID）。複製此值供下一個步驟使用。

將角色型存取控制 (RBAC) 角色指派給資源群組的身分識別。

az role assignment create \
    --role "<role-name>" \
    --assignee "<identity-id>" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"

成功的指派會回傳一個包含角色指派細節的 JSON 物件。

在以下指令中，將佔位符<role-name><identity-id><subscription-id><resource-group-name>、和替換為你的實際值。

使用 PowerShell 登入。
```
Connect-AzAccount
```
會開啟一個瀏覽器視窗進行驗證。成功登入後，終端機會顯示您的帳號和訂閱資訊。
建立你的個人身份。
```
(Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
```
這個指令會回傳你的使用者物件 ID（GUID）。複製此值供下一個步驟使用。
將角色型存取控制 (RBAC) 角色指派給資源群組的身分識別。
```
New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "<role-name>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
```
成功的指派會回傳角色指派物件，並包含RoleAssignmentId的詳細資訊。

本地開發認證

在你本地的開發環境中使用工具來驗證 Azure 身份。一旦你被認證 DefaultAzureCredential ，原始碼中的實例會找到並使用你的身份來進行認證。

選取在本機開發期間進行驗證的工具。

配置環境變數以進行本地開發

要連接 Azure AI 搜尋，你的程式碼需要知道你的資源端點。

為你的 Azure AI Search 端點建立一個名為 AZURE_SEARCH_ENDPOINT 環境變數的變數。此網址通常的格式為https://<YOUR-RESOURCE-NAME>.search.windows.net/。

生產工作負載

部署生產工作負載包含以下步驟：

選擇遵循最小權限原則的RBAC職位。
在特定資源上為你的生產身份指派 RBAC 角色。
為你的資源設定環境變數。

生產工作負載的角色

要建立生產資源，你需要建立一個由使用者指派的管理身份，然後將該身份分配給擁有正確角色的資源。

建議在生產應用中扮演以下角色：

角色名稱	身份識別碼
搜尋索引資料讀取者	1407120a-92aa-4202-b7e9-c0e197c71c8f

生產工作負載的認證

請使用以下 Azure AI Search Bicep 範本來建立資源並設定 identityId 的驗證。 Bicep 需要角色識別碼。此 Bicep 片段中顯示的 name 不是 Azure 角色；而是特定於 Bicep 部署的。

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

該檔案呼叫 main.bicep 以下通用的 Bicep 程式碼來建立各種角色。你可以選擇建立多個 RBAC 角色，例如一個給使用者，另一個給生產環境。這讓你能在同一個 Bicep 部署中啟用開發與生產環境。

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

為生產工作負載設定環境變數

要連接 Azure AI 搜尋，你的程式碼需要知道你的資源端點，以及管理身份的 ID。

為你已部署且無密鑰的 Azure AI Search 資源建立環境變數：

AZURE_SEARCH_ENDPOINT：此網址是您 Azure AI 搜尋資源的存取點。此網址通常的格式為https://<YOUR-RESOURCE-NAME>.search.windows.net/。
AZURE_CLIENT_ID：這是要用來進行身份驗證的標識。

解決常見錯誤

錯誤	原因	Solution
`AuthenticationFailedException`	缺少或無效的憑證	確保你是用 `az login` （CLI）或 `Connect-AzAccount` （PowerShell）登入的。確認你的 Azure 帳號有權限存取訂閱。
`403 Forbidden`	身份缺乏所需的角色	指派適當的角色（查詢使用搜尋索引資料讀取者，索引使用搜尋索引資料貢獻者）。角色分配可能需要長達10分鐘才能生效。
`401 Unauthorized`	搜尋服務中未啟用 RBAC	在 Azure 入口網站的設定>鍵>下啟用基於角色的存取權限。
`ResourceNotFoundException`	無效端點或索引名稱	確認 `AZURE_SEARCH_ENDPOINT` 環境變數是否符合你的搜尋服務網址（格式： `https://<service-name>.search.windows.net`）。
`CredentialUnavailableException`	未找到有效的憑證	`DefaultAzureCredential` 嘗試多種驗證方法。確保至少有一個設定已設定（Azure CLI、Visual Studio、環境變數）。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-22

共用方式為

用身份把你的應用程式連接到 Azure AI 搜尋

先決條件

安裝 Azure 身分識別用戶端程式庫

更新原始碼以使用 DefaultAzureCredential

確認你的連線

本地開發

地方發展角色

本地開發認證

配置環境變數以進行本地開發

生產工作負載

生產工作負載的角色

生產工作負載的認證

為生產工作負載設定環境變數

解決常見錯誤

相關內容

意見反應

其他資源