使用受控識別將搜尋服務連線至其他 Azure 資源

發行項
04/04/2024

您可以設定 Azure AI 搜尋服務，以使用系統指派或使用者指派的受控識別和 Azure 角色指派來連線到其他 Azure 資源。受控識別和角色指派不需要在連接字串或程式代碼中傳遞秘密和認證。

必要條件

基本層或更新層級的搜尋服務。
Azure 資源，可接受來自具有有效角色指派之 Microsoft Entra 登入的連入要求。

支援的案例

Azure AI 搜尋可在輸出連線至 Azure 資源時，使用系統指派或使用者指派的受控識別。當連接字串是 Microsoft Entra ID 感知服務或應用程式的唯一資源識別符時，就會指出系統受控識別。使用者指派的受控識別是透過「身分識別」屬性來指定。

搜尋服務會使用 Azure 儲存體做為索引器數據源，以及作為偵錯會話、擴充快取和知識存放區的數據接收。針對回寫回記憶體的搜尋功能，受控識別需要參與者角色指派，如「指派角色」一節所述。

案例	系統受控識別	使用者指派的受控識別（預覽）
索引器連線至支援的 Azure 數據源^1,3	Yes	Yes
客戶自控金鑰的 Azure 金鑰保存庫	Yes	Yes
偵錯會話（裝載於 Azure 儲存體）¹	是	No
擴充快取（裝載於 Azure 儲存體）^1,2	Yes	Yes
知識存放區（裝載於 Azure 儲存體）¹	Yes	Yes
自訂技能（裝載於 Azure Functions 或對等專案）	Yes	Yes
Azure OpenAI 內嵌技能	Yes	Yes
Azure OpenAI 向量化程式	Yes	Yes

¹ 針對搜尋與記憶體之間的連線，您的網路安全性設定會對您可以使用的受控識別類型施加限制。只有系統受控識別可以透過受信任的服務例外狀況或資源實例規則，用於與記憶體的相同區域連線。如需詳細資訊，請參閱存取受網路保護的記憶體帳戶。

² 指定擴充快取的其中一種方法是在 [匯入數據精靈] 中。目前，精靈不接受擴充快取的受控識別連接字串。不過，精靈完成之後，您可以更新索引器 JSON 定義中的連接字串，以指定系統或使用者指派的受控識別，然後重新執行索引器。

³ 請注意，目前不支援在 Azure 記憶體帳戶中停用密鑰作為數據源的 Azure 資料表。雖然受控識別用來不明確提供記憶體密鑰，但 AI 搜尋服務仍會使用此實作的密鑰。

建立系統受控識別

啟用系統指派的受控識別時，Azure 會為您的搜尋服務建立身分識別，以用來向相同租使用者和訂用帳戶內的其他 Azure 服務進行驗證。接著，您可以在 Azure 角色型存取控制（Azure RBAC）指派中使用此身分識別，以允許在編制索引期間存取數據。

系統指派的受控識別對您的搜尋服務而言是唯一的，並系結至服務的存留期。

登入 Azure 入口網站，然後尋找您的搜尋服務。
在 [設定] 底下，選取 [身分識別]。
在 [系統指派] 索引標籤的 [狀態] 底下，選取 [開啟]。
選取 [儲存]。

儲存之後，您會看到已指派給搜尋服務的對象標識碼。

請參閱建立或更新服務（管理 REST API）。

您可以使用管理 REST API，而不是入口網站來指派使用者指派的受控識別。

制定建立或更新搜尋服務的要求。

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

系統會在回應中傳回系統受控識別的確認和物件標識碼。

建立使用者指派的受控識別（預覽）

使用者指派的受控識別是 Azure 上的資源。如果您需要角色指派的更細微度，因為您可以為不同的應用程式和案例建立個別的身分識別，這會很有用。

重要

此功能在補充使用規定下處於公開預覽狀態。目前不支援使用者指派的受控識別來連線到受網路保護的記憶體帳戶。搜尋要求目前需要公用IP位址。

Azure 入口網站
REST API

登入 Azure 入口網站
選取 [+ 建立資源]。
在 [搜尋服務和市集] 搜尋列中，搜尋「用戶指派的受控識別」，然後選取 [建立]。
選取訂用帳戶、資源群組和區域。為身分識別提供描述性名稱。
選取 [建立 ] 並等候資源完成部署。

在接下來的幾個步驟中，您會將使用者指派的受控識別指派給您的搜尋服務。
在搜尋服務頁面的 [設定] 下，選取 [身分識別]。
在 [使用者指派] 索引標籤上，選取 [新增]。
選擇訂用帳戶，然後選取您在上一個步驟中建立的使用者指派受控資源。

您可以使用管理 REST API，而不是入口網站來指派使用者指派的受控識別。請務必針對這項工作使用 2021-04-01-preview 版本。

制定建立或更新搜尋服務的要求。

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2021-04-01-preview
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

設定「identity」屬性以指定完整受控識別：
- “type” 是身分識別的類型。有效值為兩者的「SystemAssigned」、“UserAssigned” 或 “SystemAssigned， UserAssigned”。值為「None」會從搜尋服務清除任何先前指派的身分識別。
- “userAssignedIdentities” 包含使用者指派受控識別的詳細數據。您必須先存在此身分識別，才能在建立或更新服務要求中指定它。

允許防火牆存取

如果您的 Azure 資源位於防火牆後方，請確定有輸入規則可承認來自搜尋服務的要求。

針對與 Azure Blob 儲存體或 Azure Data Lake 儲存體 Gen2 的相同區域連線，請使用系統受控識別和受信任的服務例外狀況。您可以選擇性地設定資源實例規則來允許要求。
針對所有其他資源和連線，設定可允許來自搜尋要求的IP防火牆規則。如需詳細資訊，請參閱索引器存取受 Azure 網路安全性功能保護的內容。

指派角色

受控識別必須與決定 Azure 資源許可權的 Azure 角色配對。

索引器數據連線和在 Azure 金鑰保存庫中存取客戶管理的金鑰需要數據讀取器許可權。
AI 擴充功能需要參與者（寫入）許可權，這些功能會使用 Azure 儲存體在知識存放區中裝載偵錯會話數據、擴充快取和長期內容記憶體。

下列步驟適用於 Azure 儲存體。如果您的資源是 Azure Cosmos DB 或 Azure SQL，則步驟很類似。

登入 Azure 入口網站，並尋找搜尋服務必須具有存取權的 Azure 資源。
在 Azure 儲存體中，選取左側瀏覽窗格中的 [存取控制] [AIM]。
選取 [新增角色指派]。

在 [ 角色] 頁面上，選取搜尋服務所需的角色：

Task	角色指派
使用索引器編製 Blob 索引	新增儲存體 Blob 數據讀取器
使用索引器編製 ADLS Gen2 索引	新增儲存體 Blob 數據讀取器
使用索引器編製數據表索引	新增讀取器和數據存取
使用索引器編製檔案索引	新增讀取器和數據存取
寫入知識存放區	針對物件和檔案投影新增儲存體 Blob DataContributor，以及數據表投影的讀取器和數據存取。
寫入擴充快取	新增儲存體 Blob 數據參與者
儲存偵錯會話狀態	新增儲存體 Blob 數據參與者
使用 Azure OpenAI 內嵌模型內嵌資料（向量化）	新增認知服務 OpenAI 使用者

在 [ 成員] 頁面上，選取 [ 受控識別]。
選取成員。在 [ 選取受控識別] 頁面中，選擇您的訂用 帳戶，然後依服務類型進行篩選，然後選取服務。只有具有受控識別的服務才能選取。
選取檢閱+指派。

連線 ion 字串範例

為搜尋服務定義受控識別並提供角色指派后，即可修改輸出連線，以使用其他 Azure 資源的唯一資源識別符。以下是各種案例連接字串的一些範例。

Blob 資料源（系統）：

索引器數據源包含「認證」屬性，可決定如何連接數據源。下列範例顯示連接字串指定記憶體帳戶的唯一資源識別碼。 Microsoft Entra ID 會使用搜尋服務的系統受控識別來驗證要求。請注意，連接字串不包含容器。在數據源定義中，容器名稱是在「container」屬性中指定（未顯示），而不是連接字串。

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Blob 數據源（使用者）：

您也可以在目前處於預覽狀態的使用者指派受控識別下，對 Azure 儲存體進行搜尋要求。搜尋服務使用者身分識別是在「identity」屬性中指定。您可以使用入口網站或 REST API 預覽版本 2021-04-30-Preview 來設定身分識別。

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

知識存放區：

知識存放區定義包含 Azure 儲存體連接字串。在 Azure 儲存體上，知識存放區會建立投影作為 Blob 和數據表。連接字串是您記憶體帳戶的唯一資源識別碼。請注意，字串不包含路徑中的容器或數據表。這些定義是在內嵌投影定義中定義，而不是連接字串。

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

擴充快取：

索引器會建立、使用及記住用於快取擴充的容器。不需要在快取連接字串中包含容器。您可以在入口網站中 搜尋服務的 [身分 識別] 頁面上找到物件標識碼。

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

偵錯會話：

偵錯會話會在入口網站中執行，並在您啟動會話時接受連接字串。您可以貼上類似下列範例的字串。

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

自訂技能：

自定義技能的目標是裝載自定義程式碼的 Azure 函式或應用程式端點。端點是在自定義技能定義中指定。 “authResourceId” 的存在會告知搜尋服務使用受控識別進行連線，並在屬性中傳遞目標函式或應用程式的應用程式識別符。

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Azure OpenAI 內嵌技能 與 Azure OpenAI 向量化工具：

AZURE OpenAI 內嵌技能與 AI 搜尋中的向量化工具，以裝載內嵌模型的 Azure OpenAI 服務端點為目標。端點是在 Azure OpenAI 內嵌技能定義和/或 Azure OpenAI 向量化工具定義中指定。如果已設定，而且「apikey」和「authIdentity」是空的，則會使用系統管理的識別。 “authIdentity” 屬性僅用於使用者指派的受控識別。

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002"
      }
    }
  ]