註
Azure AI 搜尋服務 可透過 Azure 入口網站、REST API 及 Azure SDK 取得。 它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。
本文說明如何使用管理身份設定索引器連接到 Azure Cosmos DB 資料庫，而非在 連接字串 中提供憑證。'
你可以使用系統指派的管理身份或使用者指派的管理身份。 受控識別是 Microsoft Entra 登入，需要 Azure 角色指派才能存取 Azure Cosmos DB 中的資料。 你可以選擇性地將角色型存取強制為資料連線的唯一驗證方法，方法是將你的 Azure Cosmos DB NoSQL 帳戶的 設定為 disableLocalAuth。
先決條件
- 為您的搜尋服務建立一個管理身份。
限制
- 連線至 Azure Cosmos DB For Gremlin 和 MongoDB 的索引子 (目前為預覽版)，僅支援舊版方法。
支援的管理身份驗證方法
Azure AI 搜尋服務 支援兩種機制，透過管理身份連接 Azure Cosmos DB。
舊版方法需要設定受控識別，使其具有目標 Azure Cosmos DB 帳戶控制平面的讀取者權限。 Azure AI 搜尋服務 利用該身份在背景取得 Cosmos DB 帳號的帳號金鑰以存取資料。 如果 Cosmos DB 帳號有
"disableLocalAuth": true，這種方法將不起作用。現代方法需要在目標 Azure Cosmos DB 帳號的控制平面與資料平面上設定適合的管理身份角色。 Azure AI 搜尋服務 接著會請求存取權杖以存取 Cosmos DB 帳戶中的資料。 即使 Cosmos DB 帳號中有
"disableLocalAuth": true，此方法依然有效。
建議使用連接到 Azure Cosmos DB for NoSQL 的索引器，這些索引器支援 legacy 和 modern 方法——其中推薦使用 modern 方法。
連線至 Azure Cosmos DB for NoSQL
本節概述透過現代方法設定連線到 Azure Cosmos DB for NoSQL 的步驟。
設定控制平面角色指派
登入 Azure 入口網站，找到你的 Cosmos DB for NoSQL 帳號。
選擇存取控制（IAM）。
選擇 新增 ，然後選擇 角色指派。
從職務職缺列表中，選擇 Cosmos DB 帳戶閱讀器。
選擇 下一步。
選擇 管理身份 ，然後選擇 成員。
依系統指派的受管身份或使用者指派的受管身份來篩選。 你應該會看到你之前為搜尋服務建立的管理身份。 如果你沒有，請參考 「設定搜尋以使用管理身份」。 如果您已經設定一個但無法使用，請稍候幾分鐘。
選擇身份並儲存角色分配。
如需詳細資訊，請參閱搭配 Azure Cosmos DB for NoSQL 使用控制平面角色型存取控制。
設定資料平面中的角色指派
受控識別需要被指派角色，才能從 Cosmos DB 帳戶的資料平面讀取資料。 搜尋服務系統/使用者指派身份的物件（主體）識別碼可從搜尋服務的「身份」標籤中找到。此步驟目前只能透過 Azure CLI 執行。
設定變數：
$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$scope=$(az cosmosdb show --name $cosmosdb_acc_name --resource-group $resource_group --query id --output tsv)
為系統分配的身份定義角色指派：
az cosmosdb sql role assignment create --account-name $cosmosdb_acc_name --resource-group $resource_group --role-definition-id $readOnlyRoleDefinitionId --principal-id $system_assigned_principal --scope $scope
如需詳細資訊，請參閱搭配 Azure Cosmos DB for NoSQL 使用資料平面角色型存取控制
設定資料來源定義
一旦您已在 Azure Cosmos DB for NoSQL 帳戶上設定控制平面和資料平面的角色指派，就可以建立在該角色下運作的連線。
索引器使用資料來源物件來連接外部資料來源。 本節說明如何在資料來源 連接字串 上指定系統指派的管理身份或使用者指派的管理身份。 你可以在管理身份的文章中找到更多連接字串範例。
提示
你可以在 Azure 入口網站建立一個與 Cosmos DB 的資料來源連線，指定系統或使用者指定的管理身份，然後查看 JSON 定義，看看 連接字串 是怎麼寫的。
REST API、Azure入口網站，以及 .NET SDK 支援使用系統指派或使用者指派的管理身份。
透過系統指定的身份連接
當你連接到系統指派的管理身份時，資料來源定義唯一的改變就是「憑證」屬性的格式。 提供一個資料庫名稱和一個沒有帳號金鑰或密碼的 ResourceId。 ResourceID 必須包含 Azure Cosmos DB 的訂閱 ID、資源群組，以及 Azure Cosmos DB 帳號名稱。
這裡有一個使用 Create Data Source REST API 的範例，展示現代方法的運用。
POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
"name": "my-cosmosdb-ds",
"type": "cosmosdb",
"credentials": {
"connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
},
"container": { "name": "[my-cosmos-collection]" }
}
註
如果 IdentityAuthType 屬性不包含在連接字串中，則Azure AI 搜尋服務預設採用 legacy 方法以確保向下相容。
透過使用者指定的身分來建立連線
你需要在資料來源定義中加入一個「身份」屬性，指定特定身份（從多個可指派給搜尋服務的身份中），用來連接 Azure Cosmos DB 帳號。
這裡有一個使用 現代 方法使用者指派身份的例子。
POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
"name": "[my-cosmosdb-ds]",
"type": "cosmosdb",
"credentials": {
"connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
},
"container": { "name": "[my-cosmos-collection]"},
"identity" : {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]"
}
}
連接到 Azure Cosmos DB，以支援 Gremlin/MongoDB（預覽版）
本節概述透過舊版方法設定連線到 Azure Cosmos DB for Gremlin/Mongo 的步驟。
設定控制平面角色指派
依照之前的步驟，在 Azure Cosmos DB 的控制平面上為 Gremlin/MongoDB 指派適當的角色。
設定連線字串
- 對於 MongoDB 集合，請在 連接字串 中加入「ApiKind=MongoDb」，並使用 preview REST API。
- 對於 Gremlin 圖，請在 連接字串 中加入「ApiKind=Gremlin」，並使用預覽版的 REST API。
- 無論哪種，僅支援legacy方式，也就是說，
IdentityAuthType=AccountKey或完全省略此選項是唯一有效的連接字串 (連接字串)。
這裡有一個範例，透過 REST API 使用系統指派身份連接到 MongoDB 集合
POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
"name": "my-cosmosdb-ds",
"type": "cosmosdb",
"credentials": {
"connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=MongoDb"
},
"container": { "name": "[my-cosmos-collection]", "query": null },
"dataChangeDetectionPolicy": null
}
這裡有一個範例，說明如何使用使用者指派的身份來連接到 Gremlin 圖表。
POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
"name": "[my-cosmosdb-ds]",
"type": "cosmosdb",
"credentials": {
"connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=Gremlin"
},
"container": { "name": "[my-cosmos-collection]"},
"identity" : {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]"
}
}
執行索引器來驗證權限
遠端服務的連線資訊與權限會在索引器執行時執行時驗證。 若索引器成功，則連接語法與角色指派有效。 欲了解更多資訊，請參閱 「執行或重置索引器、技能或文件」。
故障排除連線
對於 Azure Cosmos DB for NoSQL，請檢查該帳號是否限制了特定網路的存取權限。 你可以透過無限制連線來排除防火牆問題。 更多資訊請參閱索引器對受Azure網路安全保護內容的存取
對於 Azure Cosmos DB for NoSQL，如果索引子因驗證問題而失敗，請確定已在 Cosmos DB 帳戶的控制平面和資料平面上完成角色指派。
對於 Gremlin 或 MongoDB，如果你最近輪換了 Azure Cosmos DB 帳號金鑰，你需要等待最多 15 分鐘，才能讓管理身份的 連接字串 正常運作。