設定搜尋服務以使用受管理身份來連接

Note

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

您可以使用 Microsoft Entra ID 安全性原則和角色指派，用於從 Azure AI 搜尋服務到在編製索引或查詢期間提供資料、應用 AI 或向量化的其他 Azure 資源的輸出連線。

若要在輸出連線中使用角色，首先設定您的搜尋服務以使用系統指派的或使用者指派的受控識別作為在 Microsoft Entra 租用戶中您的搜尋服務的安全性主體。當你擁有管理身份後，可以指派授權存取的角色。受管理身份與角色指派消除了在連接字串或程式碼中傳遞秘密與憑證的需求。

先決條件

任何地區的 Azure AI 搜尋服務服務，需為 Basic 等級或更高。
一個接受來自具備有效角色指派之 Microsoft Entra 安全性主體傳入要求的 Azure 資源。
要建立受管理身份，您必須是擁有者或使用者存取管理員。要指派角色，您必須是擁有者、使用者存取管理員、角色為基礎的存取控制管理員，或具有 Microsoft.Authorization/roleAssignments/write 權限的自訂角色成員。

支援劇本

你可以在以下情境中使用受管理身份。

劇本	系統分配	使用者指派
連接索引器資料來源¹	是的	是的
透過技能/向量化工具連線至 Azure OpenAI、Microsoft Foundry 和 Azure Functions 中的內嵌和聊天完成模型 ²	是的	是的
連接至 Azure Key Vault 以使用客戶管理的金鑰	是的	是的
連線到偵錯工作階段 (裝載於 Azure 儲存體)¹	是的	不
連線至託管於 Azure 儲存體的擴充快取（預覽）^1,³	是的	是的， ⁴
連接至知識庫（託管於 Azure 儲存體）¹	是的	是的

¹ 對於搜尋與儲存之間的連接，網路安全會限制你能使用哪種類型的管理身份。只有系統管理身份才能用於與Azure 儲存體的相同區域連線，且該連線必須透過受信任服務例外或資源實例規則。詳情請參閱「存取網路保護儲存帳戶」。

² 透過技能及向量器連接至 Azure OpenAI、Foundry 和 Azure Functions 包括：Custom skill、Custom 向量器、Azure OpenAI 嵌入技能、Azure OpenAI 向量器、AML 技能以及 Microsoft Foundry 模型目錄向量器。

³ AI 搜尋服務目前無法連接到關閉共享金鑰存取的儲存帳號上的資料表。

⁴ 擴充快取連線的使用者指派受控識別需要預覽 REST API (2025-11-01-preview 或更新版本) 或預覽 SDK 套件。本表中所有其他由使用者指派的管理身份情境均支援於 REST API 版本 2026-04-01 及之後版本。

建立系統受控識別

系統指派的受控識別是自動建立並連結至 Azure 資源 (例如 Azure AI 搜尋服務) 的 Microsoft Entra ID 安全性主體。

你可以為每個搜尋服務設定一個系統指定的管理身份。它是專屬於您的搜尋服務，且在其整個生命週期都保持綁定。

當你啟用系統指派的管理身份時，Microsoft Entra ID 會為你的搜尋服務建立一個安全主體，用來驗證其他 Azure 資源。你可以在角色分配中使用這個身份，授權存取資料和操作。

在Azure 入口網站中，進入您的搜尋服務。
從左側窗格選擇設定>識別。
在 「系統分配」 標籤中，在「狀態」下，選擇 「開啟」。
選擇儲存。

儲存設定後，頁面會更新，顯示一個分配給搜尋服務的物件識別碼。

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

欲了解更多資訊，請參見建立帶有系統指派管理身份（Azure PowerShell的搜尋服務。

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

欲了解更多資訊，請參見建立帶有系統指派管理身份（Azure CLI）的搜尋服務。

使用 Services - Create Or Update（REST API）來表達請求。

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

回應包含確認函及系統指派的管理身份物件識別碼。

建立使用者指派的管理身份

使用者指派的管理身份是一種 Azure 資源，可以被設定為訂閱、資源群組或資源類型。

你可以建立多個由使用者指派的受管理身份，以更細緻地分配角色。例如，你可能想為不同的應用和情境設定不同的身份。作為一個獨立建立和管理的資源，它並不受服務本身約束。

設定使用者指派管理身份的步驟如下：

在你的 Azure 訂閱中，建立一個由使用者指派的管理身份。
在你的搜尋服務中，將使用者指派的管理身份與你的搜尋服務關聯起來。
在你想連接的其他 Azure 服務上，為該身份建立角色指派。

Azure 入口網站、搜尋管理 REST API 及提供此功能的 SDK 套件支援將使用者指派的管理身份與 Azure AI 搜尋服務服務關聯。

Azure portal
REST API

登入 Azure 入口網站。
在儀表板左上角，選擇 「建立資源」。
使用搜尋框找到 使用者指派的管理身份，然後選擇建立。
選擇訂閱、資源群組及區域。給這個身份一個描述性的名稱。
選擇建立，等待資源部署完成。

要花好幾分鐘才能使用該身分。
在你的搜尋服務頁面，選擇設定>身份。
在 「使用者指派」 標籤中，選擇 「新增」。
選擇訂閱及你先前建立的使用者指定的受管理身份。

你可以用搜尋管理 REST API 來指派使用者指定的管理身份，取代 Azure 入口網站。

使用 Services - Update （REST API）來表達請求。

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

設定 identity.type 為身份類型。
- 有效值為 SystemAssigned、UserAssigned 或 SystemAssigned, UserAssigned，皆適用於兩者。
- 若值為 None ，則會清除搜尋服務中先前指派的任何身份。
更新 identity.userAssignedIdentities 以包含您使用者指派的管理身份細節。這個身份必須已經存在，才能在請求中指定。

指派角色

當你擁有管理身份後，指派角色來決定 Azure 資源的搜尋服務權限。

索引器資料連線及存取 Azure Key Vault 中客戶管理的金鑰需要讀取權限。
AI 增強功能需要寫入權限，這些功能使用 Azure 儲存體來存放除錯會話資料、增強快取，以及在知識庫中進行長期內容儲存。

以下步驟說明角色分配的工作流程。這個範例是針對 Azure OpenAI。其他Azure資源請參見 Connect to Azure 儲存體、Connect to Azure Cosmos DB，或 Connect to Azure SQL。

請前往 Azure portal 的 Azure OpenAI 資源。
從左側選單選擇 存取控制 。
選擇新增，然後再選擇 新增角色指派。
在 工作功能角色中，選擇 認知服務 OpenAI 使用者 ，然後選擇 下一步。
在 「成員」中，選擇 「受管理身份 」，然後選擇 「成員」。
依訂閱和資源類型（搜尋服務）篩選，然後選擇你搜尋服務的管理身份。
選擇 Review + assign。

連接串範例

請回想場景描述中提到的內容，你可以在連接字串中使用管理的身份來連接其他 Azure 資源。本節提供範例。

系統指派的管理身份連線使用一般可用的 REST API 版本。使用者指派受控識別連線會使用 REST API 版本 2026-04-01 或更新版本，但擴充快取連線除外，該連線仍需要預覽 API 版本。

提示

你可以在 Azure 入口網站建立大多數這些物件，並且選擇指定系統指派或使用者指派的管理身分，然後查看 JSON 定義以取得連接字串。

Blob 資料來源（系統管理身份）：

索引器資料來源包含 credentials 一個屬性，決定如何與資料來源建立連結。以下範例顯示一個指定儲存體帳戶唯一資源識別碼的連接字串。

當連接字串是 Microsoft Entra ID 感知的服務或應用程式的唯一資源識別碼時，會指出系統受控識別。使用者指派的管理身份是透過屬性 identity 指定。

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

Blob 資料來源（使用者管理身份）：

使用者指派的管理身份可透過位於 identity 的屬性來支持，且需使用 2026-04-01 或更新版本的 REST API。

"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 存儲的「連接字串」。連接字串是儲存體帳戶的唯一資源 ID。注意這個字串路徑中沒有包含容器或表格。這些定義在嵌入投影定義中，而非連接字串（連接字串）。

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

知識庫（使用者管理身份）：

REST API 版本 2026-04-01 或更新版本可透過 identity 上的屬性支援使用者指派受控識別。

"knowledgeStore": {
  "storageConnectionString": "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 入口網站的搜尋服務「Identity」頁面找到物件 ID。

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

除錯會議：

除錯會話會在 Azure 入口網站執行，啟動會話時會接收一個連接字串。你可以貼上類似以下範例的字串。

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

自訂技能：

自訂技能會針對 Azure 函式或裝載自訂程式碼之應用程式的端點。

uri 是函式或應用程式的端點。
authResourceId 告訴搜尋服務使用管理身份連接，並將目標函式或應用程式的應用程式 ID 傳入屬性中。

{
  "@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",
  "modelName": "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",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

使用者指派的管理身份範例：

若 "apiKey" 為空且提供有效 "authIdentity" ，則使用使用者指派的管理身份。

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

這裡有一個為使用者指派的管理身份設定的向量器範例。向量化器是在搜尋索引中指定。

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

檢查防火牆存取權限

如果你的 Azure 資源被防火牆保護，請確保有一條內站規則允許來自搜尋服務和 Azure 入口網站的請求。

對於與Azure Blob 儲存體或Azure Data Lake Storage Gen2的相同區域連線，請使用系統管理身份及可信服務例外。你可以選擇設定資源實例規則來允許請求。
對於其他所有資源和連線，配置一個IP防火牆規則，允許來自Azure AI 搜尋服務的請求。詳情請參閱索引器存取受Azure網路安全功能保護的內容。

參見

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17