透過受控識別設定 Azure Cosmos DB 的索引器連線

  • 發行項

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

您可以使用系統指派的受控識別或使用者指派的受控識別 (預覽版)。 受控識別是 Microsoft Entra 登入，需要 Azure 角色指派才能存取 Azure Cosmos DB 中的數據。

必要條件

  • 為您的搜尋服務建立受控識別。

  • 將 Cosmos DB 帳戶讀取者 角色指派給搜尋服務受控識別。 此角色會授與讀取 Azure Cosmos DB 帳戶數據的能力。 如需 Cosmos DB 中角色指派的詳細資訊，請參閱 設定數據的角色型訪問控制。

  • 數據平面角色指派：遵循 數據平面角色指派 以深入瞭解。

  • 唯讀資料平面角色指派的範例：

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription id>
$system_assigned_principal = <principal id for system assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$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

建立資料來源

建立數據源，並在 連接字串 中提供系統指派的受控識別或使用者指派的受控識別（預覽）。

系統指派的受控識別

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 和受控識別連接字串，建立資料來源以便為來自儲存體帳戶的資料編製索引。 對於 REST API、.NET SDK 和 Azure 入口網站，受控識別連接字串格式都相同。

POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
Content-Type: application/json
api-key: [Search service admin key]

{
    "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 | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

使用者指派的受控識別 （預覽）

2021-04-30-preview REST API 支援以使用者指派的受控識別為基礎的連線。 當您使用使用者指派的受控識別進行連線時，數據源定義有兩個變更：

  • 首先，「credentials」 屬性的格式是資料庫名稱和沒有帳戶密鑰或密碼的 ResourceId。 ResourceId 必須包含 Azure Cosmos DB 的訂用帳戶標識碼、資源群組和 Azure Cosmos DB 帳戶名稱。

    • 針對 SQL 集合，連接字串 不需要 “ApiKind”。
    • 針對 SQL 集合，如果以角色為基礎的存取強制為唯一的驗證方法，請新增 「IdentityAuthType=AccessToken」。。 不適用於 MongoDB 和 Gremlin 集合。
    • 針對 MongoDB 集合，將 “ApiKind=MongoDb” 新增至 連接字串
    • 針對 Gremlin 圖形，請將 “ApiKind=Gremlin” 新增至 連接字串。

  • 其次，您會新增包含使用者指派受控識別集合的「身分識別」屬性。 建立數據源時，應該只提供一個使用者指派的受控識別。 將它設定為輸入 「userAssignedIdentities」。。

以下是如何使用預覽建立或更新資料來源 REST API 來建立索引器數據源物件的範例：

POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "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 | Gremlin | MongoDB];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
}

建立索引

索引會指定文件、屬性和其他建構中可形塑搜尋體驗的欄位。

以下的建立索引 REST API 呼叫使用可搜尋的 booktitle 欄位：

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-target-index",
    "fields": [
    { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "booktitle", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

建立索引器

索引子會以目標搜尋索引連接資料來源，並提供排程來將資料重新整理自動化。 建立索引和數據源之後，您就可以建立並執行索引器。 如果索引器成功，連線語法和角色指派是有效的。

以下是使用 適用於 NoSQL 索引器定義的 Azure Cosmos DB 建立索引器 REST API 呼叫。 索引器會在您提交要求時執行。

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
    Content-Type: application/json
    api-key: [admin key]

    {
      "name" : "cosmos-db-indexer",
      "dataSourceName" : "cosmos-db-datasource",
      "targetIndexName" : "my-target-index"
    }

疑難排解

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

檢查 Azure Cosmos DB 帳戶是否具有限制為選取網路的存取權。 您可以藉由嘗試連線而不限制來排除任何防火牆問題。

另請參閱