使用受控識別連線到 Azure Cosmos DB (Azure AI 搜尋)

發行項
10/16/2024

本文說明如何使用受控識別來設定 Azure Cosmos DB 資料庫的索引子連線，而不是在連接字串中提供認證。

您可以使用系統指派的受控識別或使用者指派的受控識別。受控識別是 Microsoft Entra 登入，需要 Azure 角色指派才能存取 Azure Cosmos DB 中的資料。

必要條件

為您的搜尋服務建立受控識別。
Azure Cosmos DB for NoSQL。您可以選擇針對您的 Cosmos DB 帳戶將 disableLocalAuth 設定為 true，以將角色型存取強制作為資料連線的唯一驗證方法。

限制

適用於 Gremlin 和 MongoDB 集合的 Azure Cosmos DB 的索引子支援目前為預覽狀態。目前預覽限制要求 Azure AI 搜尋服務使用金鑰進行連線。您仍然可以設定受控識別和角色指派，但 Azure AI 搜尋服務只會使用角色指派來取得進行連線的金鑰。這項限制表示，如果您的索引子正連線到 Gremlin 或 MongoDB，則無法設定角色型方法。

登入 Azure 入口網站，並尋找您的 Cosmos DB for NoSQL 帳戶。
選取 [存取控制 (IAM)]。
選取 [新增]，然後選取 [角色指派]。
從作業函式角色的清單中，選取 [Cosmos DB 帳戶讀者]。
選取 [下一步]。
選取受控識別，然後選取選取成員。
依系統指派的受控識別或使用者指派的受控識別進行篩選。您應該會看到先前為搜尋服務建立的受控識別。如果您沒有受控識別，請參閱設定搜尋以使用受控識別。如果您已設定一個受控識別但無法使用，請等待幾分鐘。
選取身分識別並儲存角色指派。

如需詳細資訊，請參閱使用 Microsoft Entra ID 為 Azure Cosmos DB 帳戶設定角色型存取控制。

設定變數：

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <principal ID for the search service's system assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

定義系統指派身分識別的角色指派：

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

指定連接字串中的受控識別

擁有角色指派之後，您即可設定與以該角色運作的 Azure Cosmos DB for NoSQL 的連線。

索引子會使用資料來源物件以和外部資料來源連線。本章節說明如何在資料來源連接字串上指定系統指派的受控識別或使用者指派的受控識別。您可以在受控識別文章中找到更多連接字串範例。

提示

您可以在 Azure 入口網站中建立與 CosmosDB 的資料來源連線，並指定系統或使用者指派的受控識別，然後檢視 JSON 定義以了解如何編寫連接字串。

系統指派的受控識別

REST API、Azure 入口網站和 .NET SDK 支援使用系統指派的受控識別。

當您使用系統指派的受控識別進行連線時，資料來源定義中只需要變更 "credentials" 屬性的格式。提供沒有帳戶金鑰或密碼的資料庫名稱和 ResourceId。 ResourceId 必須包含 Azure Cosmos DB 的訂用帳戶識別碼、資源群組和 Azure Cosmos DB 帳戶名稱。

針對 SQL 集合，連接字串不需要 "ApiKind"。
針對 SQL 集合，如果強制將角色型存取作為唯一的驗證方法，請新增 "IdentityAuthType=AccessToken"。這不適用於 MongoDB 和 Gremlin 集合。
針對 MongoDB 集合，請將 "ApiKind=MongoDb" 新增至連接字串，並使用預覽 REST API。
針對 Gremlin 圖形，將 "ApiKind=Gremlin" 新增至連接字串，並使用預覽 REST API。

以下範例為如何使用建立資料來源 REST API 和受控識別連接字串，建立資料來源以便為來自 Cosmos DB 帳戶的資料編製索引。對於 REST API、.NET SDK 和 Azure 入口網站，受控識別連接字串格式都相同。

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

使用者指派的受控識別

當您使用使用者指派的受控識別進行連線時，資料來源定義會有兩項變更：

首先，"credentials" 屬性的格式是資料庫名稱和沒有帳戶金鑰或密碼的 ResourceId。 ResourceId 必須包含 Azure Cosmos DB 的訂用帳戶識別碼、資源群組和 Azure Cosmos DB 帳戶名稱。
- 針對 SQL 集合，連接字串不需要 "ApiKind"。
- 針對 SQL 集合，如果強制將角色型存取作為唯一的驗證方法，請新增 "IdentityAuthType=AccessToken"。這不適用於 MongoDB 和 Gremlin 集合。
- 針對 MongoDB 集合，請將 "ApiKind=MongoDb" 新增至連接字串
- 針對 Gremlin 圖形，將 "ApiKind=Gremlin" 新增至連接字串。
其次，新增一個 "identity" 屬性，其中包含使用者指派的受控識別的集合。建立資料來源時，應該只提供一個使用者指派的受控識別。將其設定為類型 "userAssignedIdentities"。

以下範例為如何使用 REST API 建立索引子資料來源物件 \(機器翻譯\)。

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { 
        "name": "[my-cosmos-collection]", "query": null 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    },
    "dataChangeDetectionPolicy": null
}

在索引子執行期間，會在執行階段驗證遠端服務上的連線資訊和存取權限。如果索引子成功，則連接語法和角色指派有效。如需詳細資訊，請參閱執行或重設索引子、技能或文件。

疑難排解

針對 Azure Cosmos DB for NoSQL，請檢查帳戶是否將其存取權限制在選取網路。您可以在沒有既有限制的情況下嘗試連線，以排除任何防火牆問題。

針對 Gremlin 或 MongoDB，如果您最近輪替了 Azure Cosmos DB 帳戶金鑰，則最多需要等待 15 分鐘，才能讓受控識別連接字串運作。

共用方式為