分享方式：

使用受控識別連線到 Azure Cosmos DB （Azure AI 搜尋）

  • 文章

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

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

必要條件

限制

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

在 Azure Cosmos DB 中建立角色指派

  1. 登入 Azure 入口網站，並尋找適用於 NoSQL 的 Cosmos DB 帳戶。

  2. 選取 [存取控制 (IAM)]。

  3. 選取 [ 新增 ]，然後選取 [ 角色指派]。

  4. 從作業函式角色清單中，選取 [Cosmos DB 帳戶讀取器]。

  5. 選取 [下一步]。

  6. 選取 [ 受控識別 ]，然後選取 [ 成員]。

  7. 依系統指派的受控識別或使用者指派的受控識別進行篩選。 您應該會看到您先前為搜尋服務建立的受控識別。 如果您沒有，請參閱 設定搜尋以使用受控識別。 如果您已經設定一個，但無法使用，請提供幾分鐘的時間。

  8. 選取身分識別並儲存角色指派。

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

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

一旦指派角色之後，您可以設定與在該角色下運作的適用於 NoSQL 的 Azure Cosmos DB 連線。

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

提示

您可以在 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=2023-11-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=2023-11-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
}

遠端服務的連線資訊和許可權會在索引器執行期間於運行時間進行驗證。 如果索引子成功，則連接語法和角色指派有效。 如需詳細資訊，請參閱 執行或重設索引器、技能或檔。

疑難排解

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

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

另請參閱