Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
您可以使用 Microsoft Entra ID 的安全主體與角色指派,將來自 Foundry IQ(Azure AI 搜尋服務)的外發連線連接到其他提供資料、應用 AI 或向量化的 Azure 資源,在索引或查詢期間進行。
若要在外發連線上使用角色,請先將您的 Foundry IQ 服務設定為在 Microsoft Entra 租戶中使用系統指派或使用者指派的管理身份作為 Foundry IQ 服務的安全主體。 當你擁有管理身份後,可以指派授權存取的角色。 受管理身份與角色指派消除了在 連接字串 或程式碼中傳遞秘密與憑證的需求。
先決條件
任何區域中的 Foundry IQ 服務,且屬於 基礎等級或更高等級。
一個接受來自具備有效角色指派之 Microsoft Entra 安全性主體傳入要求的 Azure 資源。
要建立受管理身份,您必須是擁有者或使用者存取管理員。 要指派角色,您必須是擁有者、使用者存取管理員、角色為基礎的存取控制管理員,或具有 Microsoft.Authorization/roleAssignments/write 權限的自訂角色成員。
支援劇本
你可以在以下情境中使用受管理身份。
| 劇本 | 系統分配 | 使用者指派 |
|---|---|---|
| 連接索引器資料來源1 | 是的 | 是的 |
| 透過技能/向量化工具連線至 Azure OpenAI、Microsoft Foundry 和 Azure Functions 中的內嵌和聊天完成模型 2 | 是的 | 是的 |
| 連接至 Azure Key Vault 以取得客戶管理的金鑰 | 是的 | 是的 |
| 連線至 Debug sessions(託管於 Azure 儲存體)1 | 是的 | 不 |
| 連接至託管於 Azure 儲存體 的豐富快取(預覽)1,3 | 是的 | 是的, 4 |
| 連接到知識存放區(託管於 Azure 儲存體)1 | 是的 | 是的 |
1 針對 Foundry IQ 與儲存之間的連線,網路安全會限制您可使用哪種類型的管理身份。 只有系統管理身份才能用於與Azure 儲存體的相同區域連線,且該連線必須透過受信任服務例外或資源實例規則。 詳情請參閱「 存取網路保護儲存帳戶 」。
2 項透過技能/向量工具與 Azure OpenAI、Foundry 及 Azure Functions 的連結包括:自訂技能、自訂向量工具、Azure OpenAI 嵌入技能、Azure OpenAI 向量工具、AML 技能及 Microsoft Foundry 模型目錄向量器。
3 Foundry IQ 服務目前無法連接關閉 共享金鑰存取的儲存帳戶中的資料表。
4 用於豐富快取連線的使用者指派管理身份需要預覽版 REST API(2025-11-01-preview 或更新版本)或預覽版 SDK 套件。 本表中所有其他由使用者指派的管理身份情境均支援於 REST API 版本 2026-04-01 及之後版本。
建立系統受控識別
系統指派的管理身份是一個自動建立並連結至 Azure 資源(例如 Foundry IQ 服務)的 Microsoft Entra ID 安全主體。
您可以為每個 Foundry IQ 服務設定一個系統指派的管理身份。 它是您的 Foundry IQ 服務獨有的,並且會在其整個生命週期內綁定於該服務。
當您啟用系統指派的管理身份時,Microsoft Entra ID 會為您的 Foundry IQ 服務建立一個安全主體,用於驗證其他 Azure 資源。 你可以在角色分配中使用這個身份,授權存取資料和操作。
前往 Azure 入口網站中的 Foundry IQ 服務。
從左側窗格選擇設定>識別。
在 「系統分配」 標籤中,在「狀態」下,選擇 「開啟」。
選擇 儲存。
儲存設定後,頁面會更新,顯示指派給您的 Foundry IQ 服務的物件識別碼。
建立使用者指派的管理身份
使用者指派的管理身份是一種 Azure 資源,可以被設定為訂閱、資源群組或資源類型。
你可以建立多個由使用者指派的受管理身份,以更細緻地分配角色。 例如,你可能想為不同的應用和情境設定不同的身份。 作為一個獨立建立和管理的資源,它並不受服務本身約束。
設定使用者指派管理身份的步驟如下:
在你的 Azure 訂閱中,建立一個由使用者指派的管理身份。
在您的 Foundry IQ 服務中,將使用者指派的受控識別與您的 Foundry IQ 服務建立關聯。
在你想連接的其他 Azure 服務上,為該身份建立角色指派。
將使用者指派的管理身份與 Foundry IQ 服務關聯,在提供此功能的 Azure 入口網站、搜尋管理 REST API 及 SDK 套件中均受到支援。
登入 Azure 入口網站。
在儀表板左上角,選擇 「建立資源」。
使用搜尋框找到 使用者指派的管理身份,然後選擇 建立。
選擇訂閱、資源群組及區域。 給這個身份一個描述性的名稱。
選擇 建立 ,等待資源部署完成。
要花好幾分鐘才能使用該身分。
在您的 Foundry IQ 服務頁面上,選擇「 設定>識別碼」。
在 「使用者指派」 標籤中,選擇 「新增」。
選擇訂閱及你先前建立的使用者指定的受管理身份。
指派角色
取得管理身份後,指派角色以決定 Azure 資源上的 Foundry IQ 服務權限。
若要直接連線 Azure OpenAI 模型,請將 Cognitive Services OpenAI User 指派給 Foundry IQ 服務配置所選擇的系統指派或使用者指派的身份。 將範圍設定為承載部署且對應resourceUri的 Azure OpenAI 或 Microsoft Foundry 資源。 對於 Foundry 專案,請使用其父資源,而非專案物件、Foundry IQ 服務、索引、知識來源、知識庫或部署名稱。
| Value | Purpose |
|---|---|
| 管理身份主體/物件識別碼 | 識別角色指派的對象。 |
| 用戶端識別碼 | 識別身分所屬的應用程式。 這不是角色指派範圍,也不是 authIdentity.userAssignedIdentity 的值。 |
| 使用者指派的身分識別資源識別碼 | 在支援的搜尋 authIdentity 設定中選取附加的身分識別。 這不是模型資源範圍。 |
| 模型託管資源識別碼 | 設定角色指派範圍。 它用來識別父 Azure OpenAI 或 Foundry 資源。 |
| 部署名稱與端點主機名稱 | 請識別模型部署及連線目的地,而非角色指派收件人。 |
當受支援的模型端點使用 openai.azure.com、services.ai.azure.com 或 cognitiveservices.azure.com 時,同樣適用範圍規則。 對於驗證搜尋驗證並使用自身後端身份的 API 管理,請將模型角色指派給閘道的後端身份。 在閘道器上另行授權搜尋。 請參閱 搜尋到閘道驗證。
索引器資料連線及存取 Azure Key Vault 中客戶管理的金鑰需要讀取權限。
AI 增強功能需要寫入權限,這些功能使用 Azure 儲存體 來存放除錯會話資料、增強快取,以及在知識庫中進行長期內容儲存。
以下步驟說明角色分配的工作流程。 這個範例是針對 Azure OpenAI。 其他Azure資源請參見 Connect to Azure 儲存體、Connect to Azure Cosmos DB,或 Connect to Azure SQL。
前往 Azure 入口網站中託管模型的 Azure OpenAI 資源,或您 Foundry 專案的父資源。
從左側選單選擇 存取控制 。
選擇 新增 ,然後再選擇 新增角色指派。
在 工作功能角色中,選擇 認知服務 OpenAI 使用者 ,然後選擇 下一步。
在 「成員」中,選擇 「受管理身份 」,然後選擇 「成員」。
依訂閱與資源類型(Foundry IQ 服務)篩選,然後選擇您的 Foundry IQ 服務的管理身份。
選擇 Review + assign。
角色指派傳播與網路連線與身分選擇是分開的。 對於 401 或 403 錯誤,請先確認所選的身份與模型託管範圍,再授權更廣泛的存取權限。 停用本地金鑰驗證並不會消除對正確身份、角色與網路路由的需求。
有效的身份與角色指派並不會阻止快取來源令牌在長時間索引器執行期間過期。 關於執行前重新整理行為及暫時緩解措施,請參閱「執行期間受控識別權杖過期」。
連接串範例
請回想場景描述中提到的內容,你可以在連接字串中使用管理的身份來連接其他 Azure 資源。 本節提供範例。
系統指派的管理身份連線使用一般可用的 REST API 版本。 使用者指派受控識別連線會使用 REST API 版本 2026-04-01 或更新版本,但擴充快取連線除外,該連線仍需要預覽 API 版本。
提示
你可以在 Azure 入口網站建立大多數這些物件,並且選擇指定系統指派或使用者指派的管理身分,然後查看 JSON 定義以取得連接字串。
索引器資料來源包含 credentials 一個屬性,決定如何與資料來源建立連結。 以下範例顯示一個指定儲存體帳戶唯一資源識別碼的連接字串。
當連接字串是 Microsoft Entra ID 感知的服務或應用程式的唯一資源識別碼時,會指出系統受控識別。 使用者指派的管理身份是透過屬性 identity 指定。
"credentials": {
"connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}
使用者指派的管理身份可透過位於 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 入口網站的 Foundry IQ 服務的身份頁面找到物件 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指示 Foundry IQ 服務使用管理身份連線,並在屬性中傳遞目標函式或應用程式的應用程式 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": [ ...]
}
模型連接範例
對於使用受管理身份建立的連線,本節展示 Foundry IQ 服務用來連接其他資源模型的連線資訊範例。 透過系統管理身份的連線是透明的;身份與角色已經建立,若配置得當,連結會成功。 相較之下,使用者管理身份則需要額外的連線屬性。
Azure OpenAI 嵌入技能與 Azure OpenAI 向量器:
Foundry IQ(Azure 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 資源位於防火牆後方,請確保有入站規則允許來自 Foundry IQ 服務及 Azure 入口網站的請求。
對於與Azure Blob 儲存體或Azure Data Lake Storage Gen2的相同區域連線,請使用系統管理身份及可信服務例外。 你可以選擇設定 資源實例規則 來允許請求。
對於所有其他資源與連線,設定 IP 防火牆規則,允許來自 Foundry IQ 的請求。 詳情請參閱索引器存取受Azure網路安全功能保護的內容。