共用方式為

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

  • 發行項

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

您可以使用系統指派的受控識別或使用者指派的受控識別。 受控識別是 Microsoft Entra 登入，需要 Azure 角色指派才能存取 Azure Cosmos DB 中的資料。 您可以選擇性地將 設定為適用於 NoSQL 的 Azure Cosmos DB 帳戶，以強制角色型存取作為數據連線disableLocalAuthtrue的唯一驗證方法。

必要條件

受控識別驗證的支援方法

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，這個方法仍可運作。

連接到適用於 NoSQL 的 Azure Cosmos DB 的索引器同時支援舊版 和 新 式方法-強烈建議使用 新式 方法。

限制

  • 聯機到 Azure Cosmos DB for Gremlin 和 MongoDB 的索引器（目前為預覽版）僅支援 舊版 方法。

連線至 Azure Cosmos DB for NoSQL

本節概述透過新式方法設定連線至適用於 NoSQL 的 Azure Cosmos DB 的步驟。

設定控制平面角色指派

  1. 登入 Azure 入口網站，並尋找您的 Cosmos DB for NoSQL 帳戶。

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

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

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

  5. 選取 [下一步]。

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

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

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

如需詳細資訊，請參閱 搭配適用於 NoSQL 的 Azure Cosmos DB 使用控制平面角色型訪問控制。

設定數據平面角色指派

受控識別必須指派角色，才能從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-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

如需詳細資訊，請參閱 搭配適用於 NoSQL 的 Azure Cosmos DB 使用數據平面角色型訪問控制

設定數據源定義

當您在適用於 NoSQL 的 Azure Cosmos DB 帳戶上設定控制平面和數據平面角色指派之後，您就可以設定在該角色下運作的連線。

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

提示

您可以在 Azure 入口網站 中建立 Cosmos DB 的數據源連線、指定系統或使用者指派的受控識別，然後檢視 JSON 定義，以查看如何制定 連接字串。

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

透過系統指派的身分識別進行連線

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

以下是使用建立數據源 REST API 來練習新式方法的範例。

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

注意

IdentityAuthType如果屬性不屬於 連接字串，則 Azure AI 搜尋會預設為舊版方法，以確保回溯相容性。

透過使用者指派的身分識別進行連線

您需要將「身分識別」屬性新增至數據源定義，您可以在其中指定特定身分識別（在可指派給搜尋服務的數個身分識別中），以用來連線到 Azure Cosmos DB 帳戶。

以下是透過新式方法使用使用者指派身分識別的範例。

POST https://[service name].search.windows.net/datasources?api-version=2024-11-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];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]" 
    }
}

線上至適用於 Gremlin/MongoDB 的 Azure Cosmos DB （預覽版）

本節概述透過舊版方法設定連線到適用於 Gremlin/Mongo 的 Azure Cosmos DB 的步驟。

設定控制平面角色指派

請遵循與之前相同的步驟，在適用於 Gremlin/MongoDB 的 Azure Cosmos DB 控制平面上指派適當的角色。

設定連接字串

  • 針對 MongoDB 集合，請將 "ApiKind=MongoDb" 新增至連接字串，並使用預覽 REST API。
  • 針對 Gremlin 圖形，將 "ApiKind=Gremlin" 新增至連接字串，並使用預覽 REST API。
  • 針對任一種，只支援舊版方法，亦即IdentityAuthType=AccountKey，或完全省略它是唯一有效的 連接字串。

以下是透過 REST API 使用系統指派身分識別連線到 MongoDB 集合的範例

POST https://[service name].search.windows.net/datasources?api-version=2024-11-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=2024-11-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 網路安全性 保護的內容

  • 針對適用於 NoSQL 的 Azure Cosmos DB，如果索引器因為驗證問題而失敗，請確定已在 Cosmos DB 帳戶的控制平面和數據平面上完成角色指派。

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

另請參閱