使用角色型存取控制和 Microsoft Entra ID 連線到 Azure Cosmos DB for Table

適用於: ✅ Table

角色型存取控制是指管理 Azure 中資源存取權的方法。此方法是以指派角色的特定身分為基礎，這些角色會管理他們對一或多個資源的存取層級。角色型存取控制提供彈性的精細存取管理系統，確保身分識別僅具有執行任務所需的最低權限層級。

如需詳細資訊，請參閱角色型存取控制。

先決條件

具有有效訂閱的 Azure 帳戶。免費建立帳戶。
現有的 Azure Cosmos DB for Table 帳戶。
Microsoft Entra ID 中的一或多個現有身分識別。

使用 Azure Cloud Shell 中的 Bash 環境。如需詳細資訊，請參閱開始使用 Azure Cloud Shell。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱如何在 Docker 容器中執行 Azure CLI。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 向 Azure 進行驗證。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能的詳細資訊，請參閱使用和管理 Azure CLI 的擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

如果您選擇在本機使用 Azure PowerShell：
- 安裝最新版的 Az PowerShell 模組。
- 使用 Connect-AzAccount Cmdlet 連線到您的 Azure 帳戶。
如果您選擇使用 Azure Cloud Shell：
- 請參閱 Azure Cloud Shell 概觀以取得詳細資訊。

停用金鑰型驗證

停用金鑰型授權可防止在沒有更安全的 Microsoft Entra ID 驗證方法的情況下使用您的帳戶。此程序是應在安全工作負載中的新帳戶上執行的步驟。或者，在移轉至安全工作負載模式的現有帳戶上執行此程序。

首先，停用現有帳戶的金鑰型驗證，讓應用程式必須使用 Microsoft Entra ID 驗證。請用 az resource update 來修改 properties.disableLocalAuth 已存在的用戶帳戶。

az resource update \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-account>" \
    --resource-type "Microsoft.DocumentDB/databaseAccounts" \
    --set properties.disableLocalAuth=true

首先，建立已停用金鑰型驗證的新帳戶，讓應用程式必須使用 Microsoft Entra 驗證。

建立新的 Bicep 檔案，以部署已停用金鑰型驗證的新帳戶。將檔案命名為 deploy-new-account.bicep。

metadata description = 'Deploys a new Azure Cosmos DB account with key-based auth disabled.'

@description('Name of the Azure Cosmos DB account.')
param name string = 'csms-${uniqueString(resourceGroup().id)}'

@description('Primary location for the Azure Cosmos DB account.')
param location string = resourceGroup().location

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = {
  name: name
  location: location
  kind: 'GlobalDocumentDB'
  properties: {
    databaseAccountOfferType: 'Standard'
    locations: [
      {
        locationName: location
      }
    ]
    disableLocalAuth: true
  }
}

用 az deployment group create 來使用新帳戶部署 Bicep 檔案。

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file deploy-new-account.bicep

首先，停用現有帳戶的金鑰型驗證，讓應用程式必須使用 Microsoft Entra 驗證。使用 Get-AzResource 和 Set-AzResource 分別讀取和更新現有帳戶。

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    ResourceName = "<name-of-existing-account>"
    ResourceType = "Microsoft.DocumentDB/databaseAccounts"
}
$resource = Get-AzResource @parameters

$resource.Properties.DisableLocalAuth = $true

$resource | Set-AzResource -Force

使用下列步驟來建立新的 Azure Cosmos DB for NoSQL 帳戶，並停用金鑰型驗證，讓應用程式只需要使用 Microsoft Entra 驗證。

設定新的適用於 NoSQL 的 Azure Cosmos DB 帳戶時，請流覽至帳戶建立程式的 [ 安全性 ] 區段。
然後，針對金鑰型驗證選項選取停用。

這很重要

修改 Azure Cosmos DB 帳戶需要至少具有 Microsoft.DocumentDb/databaseAccounts/*/write 權限的 Azure 角色。如需詳細資訊，請參閱 Azure Cosmos DB 的許可權。

驗證金鑰型驗證是否已停用

若要驗證金鑰型存取是否已停用，請嘗試使用 Azure SDK 使用資源擁有者密碼認證（ROPC）連線到適用於資料表的 Azure Cosmos DB。此嘗試應該會失敗。如有必要，此處提供常見程式設計語言的程式碼範例。

using Azure.Data.Tables;
using Azure.Core;

string connectionString = "AccountEndpoint=<table-endpoint>;AccountKey=<key>;";

TableServiceClient client = new(connectionString);

const { TableServiceClient } = require('@azure/data-tables');

const connectionString = 'AccountEndpoint=<table-endpoint>;AccountKey=<key>;';

const client = new TableServiceClient(connectionString);

import { TableServiceClient } from '@azure/data-tables';

let connectionString: string = 'AccountEndpoint=<table-endpoint>;AccountKey=<key>;';

const client: TableServiceClient = new TableServiceClient(connectionString);

from azure.data.tables import TableServiceClient

connection_string = "AccountEndpoint=<table-endpoint>;AccountKey=<key>;"

client = TableServiceClient(endpoint, connection_string)

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/data/aztables"
)

const connectionString = "AccountEndpoint=<table-endpoint>;AccountKey=<key>;"

func main() {
  client, _ := aztables.NewServiceClientFromConnectionString(connectionString, nil)
}

import com.azure.data.tables.TableServiceClient;
import com.azure.data.tables.TableServiceClientBuilder;

public class Table{
    public static void main(String[] args){
        TableServiceClient tableServiceClient = new TableServiceClientBuilder()
            .connectionString("AccountEndpoint=<table-endpoint>;AccountKey=<key>;")
            .buildClient();
    }
}

授與控制平面角色型存取權

控制平面存取是指管理 Azure 服務資源而不管理資料的能力。例如，Azure Cosmos DB 控制平面存取可能包含下列功能：

讀取所有帳戶和資源中繼資料
讀取並重新產生帳戶金鑰和連接字串
執行帳戶備份和還原
啟動和追蹤資料傳輸任務
管理資料庫和容器
修改帳戶屬性

這很重要

在 Azure Cosmos DB 中，您需要控制平面存取權，才能管理原生資料平面角色型存取控制定義和指派。由於 Azure Cosmos DB 的資料平面角色型存取控制機制是原生的，因此您需要控制平面存取權才能建立定義和指派，並將其儲存為 Azure Cosmos DB 帳戶內的資源。

首先，您必須準備具有 actions 清單的角色定義，以授與管理 Azure Cosmos DB 中帳戶資源的存取權。在本指南中，您將設定內建角色和自訂角色。然後，將新定義的角色指派給身分識別，讓您的應用程式可以存取 Azure Cosmos DB 中的資源。

使用 az role definition list列出與您的 Azure Cosmos DB 帳戶相關聯的所有角色定義。
```
az role definition list \
    --name "Cosmos DB Operator"
```

檢閱輸出，並找出名為 Cosmos DB 運算子的角色定義。輸出包含屬性中 id 角色定義的唯一識別碼。記錄此值，因為本指南稍後的指派步驟需要使用該值。

[
  {
    "assignableScopes": [
      "/"
    ],
    "description": "Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa",
    "name": "230815da-be43-4aae-9cb4-875f7bd000aa",
    "permissions": [
      {
        "actions": [
          "Microsoft.DocumentDb/databaseAccounts/*",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/deployments/*",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Support/*",
          "Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*",
          "Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/regenerateKey/*",
          "Microsoft.DocumentDB/databaseAccounts/listKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/listConnectionStrings/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/delete"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Cosmos DB Operator",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
  }
]

備註

在此範例中， id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa。此範例使用虛構資料，您的識別碼將與此範例不同。不過，識別碼（230815da-be43-4aae-9cb4-875f7bd000aa）在 Azure 中的所有角色定義中都是全域唯一的。

使用 az group show 取得您目前資源群組的中繼資料。

az group show \
    --name "<name-of-existing-resource-group>"

觀察上一個命令的輸出。記錄此資源群組的 id 屬性值，因為它將在下一個步驟中需要使用。
```
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}
```
備註

在此範例中， id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example。此範例使用虛構資料，您的識別碼將與此範例不同。此字串是輸出的截斷範例。
建立名為 role-definition.json的新 JSON 檔案。在檔案中，建立此資源定義，並指定此處列出的值。針對 AssignableScopes 清單，新增 id 上一個步驟中記錄的資源群組屬性。
```
{
  "Name": "Azure Cosmos DB Control Plane Owner",
  "IsCustom": true,
  "Description": "Can perform all control plane actions for an Azure Cosmos DB account.",
  "Actions": [
    "Microsoft.DocumentDb/*"
  ],
  "AssignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ]
}
```
備註

此範例使用上一個步驟中記錄的 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example 值。您的實際資源識別碼可能會有所不同。
建立新的角色定義使用az role definition create。使用 role-definition.json 檔案作為引數的 --role-definition 輸入。
```
az role definition create \
    --role-definition role-definition.json
```

檢閱定義建立指令的輸出。輸出包含屬性中 id 角色定義的唯一識別碼。記錄此值，因為本指南稍後的指派步驟需要使用該值。

{
  "assignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ],
  "description": "Can perform all control plane actions for an Azure Cosmos DB account.",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "name": "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
  "permissions": [
    {
      "actions": [
        "Microsoft.DocumentDb/*"
      ]
    }
  ],
  "roleName": "Azure Cosmos DB Control Plane Owner",
  "roleType": "CustomRole"
}

備註

在此範例中， id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1。此範例使用虛構資料，您的識別碼將與此範例不同。為了清楚起見，此範例是從部署輸出的典型 JSON 子集。

使用 az group show 再次取得您目前資源群組的中繼資料。
```
az group show \
    --name "<name-of-existing-resource-group>"
```
觀察上一個命令的輸出。記錄此資源群組的 id 屬性值，因為它將在下一個步驟中需要使用。
```
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}
```
備註

在此範例中， id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example。此範例使用虛構資料，您的識別碼將與此範例不同。此字串是輸出的截斷範例。
使用az role assignment create指派新角色。使用資源群組的識別碼作為--scope引數，角色的識別碼作為-role引數，將身分的唯一識別碼用於--assignee引數。
```
az role assignment create \
    --assignee "<your-principal-identifier>" \
    --role "subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1" \
    --scope "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
```
備註

在此範例命令中，已將設定 scope 為上一個步驟範例中的虛構範例 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example 。您的資源群組識別碼將與此範例不同。 role 已被設定為虛構 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1。同樣，您的角色識別碼將是不同的。

觀察命令的輸出。輸出包括用於指派的唯一識別碼在id屬性中。

{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "name": "ffffffff-5555-6666-7777-aaaaaaaaaaaa",
  "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
  "resourceGroup": "msdocs-identity-example",
  "roleDefinitionId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "scope": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "type": "Microsoft.Authorization/roleAssignments"
}

備註

在此範例中， id 屬性是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1，這是另一個虛構的範例。

重複這些步驟，以從您要使用的任何其他身分識別授予存取帳戶之權利。

小提示

您可以對任意數量的身分重複這些步驟。一般而言，這些步驟至少會重複，以允許開發人員使用其人類身分識別存取帳戶，並允許應用程式使用受控識別存取資料。

使用 az role definition list列出與您的 Azure Cosmos DB 帳戶相關聯的所有角色定義。
```
az role definition list \
    --name "Cosmos DB Operator"
```

[
  {
    "assignableScopes": [
      "/"
    ],
    "description": "Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa",
    "name": "230815da-be43-4aae-9cb4-875f7bd000aa",
    "permissions": [
      {
        "actions": [
          "Microsoft.DocumentDb/databaseAccounts/*",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/deployments/*",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Support/*",
          "Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*",
          "Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/regenerateKey/*",
          "Microsoft.DocumentDB/databaseAccounts/listKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/listConnectionStrings/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/delete"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Cosmos DB Operator",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
  }
]

備註

建立新的 Bicep 檔案來定義您的角色定義。將檔案命名為 control-plane-role-definition.bicep。將這些項目新增至 actions 定義：

	Description
*`Microsoft.DocumentDb/`**	啟用所有可能的動作。

metadata description = 'Create RBAC definition for control plane access to Azure Cosmos DB.'

@description('Name of the role definition.')
param roleDefinitionName string = 'Azure Cosmos DB Control Plane Owner'

@description('Description of the role definition.')
param roleDefinitionDescription string = 'Can perform all control plane actions for an Azure Cosmos DB account.'

resource definition 'Microsoft.Authorization/roleDefinitions@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionName)
  scope: resourceGroup()
  properties: {
    roleName: roleDefinitionName
    description: roleDefinitionDescription
    type: 'CustomRole'
    permissions: [
      {
        actions: [
          'Microsoft.DocumentDb/*'
        ]
      }
    ]
    assignableScopes: [
      resourceGroup().id
    ]
  }
}

output definitionId string = definition.id

使用 az deployment group create部署 Bicep 範本。指定 Bicep 範本和 Azure 資源群組的名稱。

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file control-plane-role-definition.bicep

查看部署結果。輸出包含屬性中 properties.outputs.definitionId.value 角色定義的唯一識別碼。記錄此值，因為本指南稍後的指派步驟需要使用該值。
```
{
  "properties": {
    "outputs": {
      "definitionId": {
        "type": "String",
        "value": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
      }
    }
  }
}
```
備註

在此範例中， id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1。此範例使用虛構資料，您的識別碼將與此範例不同。為了清楚起見，此範例是從部署輸出的典型 JSON 子集。

建立新的 Bicep 檔案以定義您的角色指派。將檔案命名為 control-plane-role-assignment.bicep。

metadata description = 'Assign RBAC role for control plane access to Azure Cosmos DB.'

@description('Id of the role definition to assign to the targeted principal in the context of the account.')
param roleDefinitionId string

@description('Id of the identity/principal to assign this role in the context of the account.')
param identityId string

resource assignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionId, identityId)
  scope: resourceGroup()
  properties: {
    roleDefinitionId: roleDefinitionId
    principalId: identityId
  }
}

建立名為 control-plane-role-assignment 的新 Bicep 參數檔案。bicepparam 在此參數檔案中;將先前記錄的角色定義識別碼指派給 roleDefinitionId 參數，並將身分的唯一識別碼指派給 identityId 參數。
```
using './control-plane-role-assignment.bicep'

param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'
```

使用 az deployment group create 部署此 Bicep 範本。

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters control-plane-role-assignment.bicepparam \
    --template-file control-plane-role-assignment.bicep

重複這些步驟，以從您要使用的任何其他身分識別授予存取帳戶之權利。

小提示

您可以對任意數量的身分重複這些步驟。一般而言，這些步驟至少會重複，以允許開發人員使用其人類身分識別存取帳戶，並允許應用程式使用受控識別存取資料。

登入 Azure 入口網站 (https://portal.azure.com)。
在全域搜尋列中輸入 資源群組 。
在 [服務] 中，選取 [資源群組]。
在 [資源群組] 窗格中，選取您現有的資源群組。

備註

此範例螢幕擷取畫面包含 msdocs-identity-example 資源群組。您的實際資源群組名稱可能不同。
在資源群組的窗格中，選取服務功能表中的存取控制（IAM）。
在 [存取控制（IAM）] 窗格中，選取 [ 角色]。
在 [ 角色 ] 區段中，使用搜尋片語 Cosmos DB ，並找出 Cosmos DB 運算子 角色定義。然後，選取與該定義相關聯的 「檢視 」選項。
在 [Cosmos DB 操作員] 角色定義對話方塊中，觀察指派為此角色定義一部分的動作。
關閉 [Cosmos DB 操作員 ] 角色定義對話方塊。
返回 [存取控制（IAM）] 窗格，選取 [新增]。然後選取 [新增自訂角色]。

在 [基本] 窗格中，設定下列選項，然後選取 [ 下一步]：

	價值觀
自訂角色名稱	`Azure Cosmos DB Control Plane Owner`
說明	`Can perform all control plane actions for an Azure Cosmos DB account.`
基準許可權	從頭開始

用於新增自訂角色的「基本」窗格螢幕擷取畫面。

在 [許可權] 窗格中，選取 [新增許可權]。 然後，在權限對話方塊中搜尋DocumentDB。最後，選擇 Microsoft.DocumentDB 選項。
在權限對話方塊中，為選取所有 Microsoft.DocumentDB。然後，選取 [ 新增 ] 以返回 [*權限] 窗格。
返回 [許可權] 窗格，觀察許可權清單。然後，選取 [ 檢閱 + 建立]。
在 [ 檢閱 + 建立 ] 窗格中，檢閱新角色定義的指定選項。最後，選取 [建立]。
等候入口網站完成建立角色定義。
在 [存取控制（IAM）] 窗格中，選取 [ 新增 ]，然後選取 [ 新增角色指派]。
在 [角色] 窗格中，搜尋 Azure Cosmos DB 並選取本指南稍早建立的 Azure Cosmos DB 控制平面擁有者 角色。然後選取下一步。

小提示

您可以選擇性地篩選角色清單，以僅包含自訂角色。
在 [ 成員 ] 窗格中，選取 [ 選取成員 ] 選項。在 [成員] 對話方塊中，選取您想要授與 Azure Cosmos DB 帳戶此存取層級的身分識別，然後使用 [ 選取 ] 選項來確認您的選擇。

備註

此螢幕擷取畫面說明名為 「Kai Carter」 的範例使用者，其主體為 kai@adventure-works.com。
返回 [成員] 窗格，檢閱選取的成員，然後選取 [ 檢閱 + 指派]。
在 [ 檢閱 + 指派 ] 窗格中，檢閱新角色指派的指定選項。最後，選取 [ 檢閱 + 指派]。
等候入口網站完成建立角色指派。

用 Get-AzRoleDefinition 來列出與您的 Azure Cosmos DB 帳戶相關聯的所有角色定義。
```
$parameters = @{
    Name = "Cosmos DB Operator"
}
Get-AzRoleDefinition @parameters
```

檢閱輸出，並找出名為 Cosmos DB 內建資料參與者的角色定義。輸出包含屬性中 Id 角色定義的唯一識別碼。記錄此值，因為本指南稍後的指派步驟需要使用該值。

Name             : Cosmos DB Operator
Id               : 230815da-be43-4aae-9cb4-875f7bd000aa
IsCustom         : False
Description      : Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.
Actions          : {Microsoft.DocumentDb/databaseAccounts/*, Microsoft.Insights/alertRules/*, Microsoft.Authorization/*/read, Microsoft.ResourceHealth/availabilityStatuses/read…}
NotActions       : {Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*, Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*, Microsoft.DocumentDB/databaseAccounts/regenerateKey/*, Microsoft.DocumentDB/databaseAccounts/listKeys/*…}
DataActions      : {}
NotDataActions   : {}
AssignableScopes : {/}

備註

在此範例中， Id 值會是 230815da-be43-4aae-9cb4-875f7bd000aa。識別碼在 Azure 中的所有角色定義中都是全域唯一的。

使用 Get-AzResourceGroup 取得您目前資源群組的中繼資料。

$parameters = @{
    Name = "<name-of-existing-resource-group>"
}
Get-AzResourceGroup @parameters

觀察上一個命令的輸出。記錄此資源群組的 ResourceId 屬性值，因為它將在下一個步驟中需要使用。
```
ResourceGroupName : msdocs-identity-example
Location          : westus
ProvisioningState : Succeeded
ResourceId        : /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example
```
備註

在此範例中， ResourceId 值會是 /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example。此範例使用虛構資料，您的識別碼將與此範例不同。此字串是一般輸出的截斷範例。

首先，匯入 Az.Resources 模組。然後，建立新 Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition 物件。在物件中，建立此資源定義，並指定此處列出的值。針對 AssignableScopes 清單，新增 ResourceId 上一個步驟中記錄的資源群組屬性。最後，使用角色定義物件作為-Role的參數New-AzRoleDefinition的輸入。

Import-Module Az.Resources

$parameters = @{
    TypeName = "Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition"
    Property = @{
        Name = "Azure Cosmos DB Control Plane Owner"
        Description = "Can perform all control plane actions for an Azure Cosmos DB account."
        IsCustom = $true
        Actions = @(
            "Microsoft.DocumentDb/*"
        )
        AssignableScopes = @(
            "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
        )
    }
}
$role = New-Object @parameters

New-AzRoleDefinition -Role $role

備註

此範例使用上一個步驟中記錄的 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example 值。您的實際資源識別碼可能會有所不同。

檢閱定義建立指令的輸出。輸出包含屬性中 Name 角色定義的唯一識別碼。記錄此值，因為本指南稍後的指派步驟需要使用該值。

Name             : Azure Cosmos DB Control Plane Owner
Id               : e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5
IsCustom         : True
Description      : Can perform all control plane actions for an Azure Cosmos DB account.
Actions          : {Microsoft.DocumentDb/*}
AssignableScopes : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example}

備註

在此範例中， Name 值會是 Azure Cosmos DB Control Plane Owner。為了清楚起見，此範例是部署典型輸出的子集。

使用New-AzRoleAssignment指派新角色。使用角色的名稱作為 RoleDefinitionName 參數，並使用您身分的唯一識別碼作為 ObjectId 參數。

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    ObjectId = "<your-principal-identifier>"
    RoleDefinitionName = "Azure Cosmos DB Control Plane Owner"
}
New-AzRoleAssignment @parameters

觀察命令的輸出。輸出包括用於指派的唯一識別碼在RoleAssignmentId屬性中。

RoleAssignmentName : ffffffff-5555-6666-7777-aaaaaaaaaaaa
RoleAssignmentId   : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1
Scope              : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example
DisplayName        : Kai Carter
SignInName         : <kai@adventure-works.com>
RoleDefinitionName : Azure Cosmos DB Control Plane Owner
RoleDefinitionId   : e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5

備註

在此範例中， RoleAssignmentId 屬性是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1，這是另一個虛構的範例。為了清楚起見，此範例是部署典型輸出的子集。

重複這些步驟，以從您要使用的任何其他身分識別授予存取帳戶之權利。

小提示

您可以對任意數量的身分重複這些步驟。一般而言，這些步驟至少會重複，以允許開發人員使用其人類身分識別存取帳戶，並允許應用程式使用受控識別存取資料。

這很重要

指派角色定義需要您已經擁有要授與角色型存取控制許可的任何身分的唯一識別碼。

在程式碼中驗證控制平面角色型存取

驗證您是否使用應用程式程式碼和 Azure 管理 SDK 正確授與存取權。

using Azure.Identity;
using Azure.ResourceManager;

DefaultAzureCredential credential = new();

ArmClient client = new(credential);

const { CosmosDBManagementClient } = require('@azure/arm-cosmosdb');
const { DefaultAzureCredential } = require('@azure/identity');

const subscriptionId = "<subscription-id>";

const credential = new DefaultAzureCredential();

const client = new CosmosDBManagementClient(credential, subscriptionId);

import { CosmosDBManagementClient } from '@azure/arm-cosmosdb';
import { TokenCredential, DefaultAzureCredential } from '@azure/identity';

let subscriptionId: string = "<subscription-id>";

let credential: TokenCredential = new DefaultAzureCredential();

const client: CosmosDBManagementClient = new CosmosDBManagementClient(credential, subscriptionId);

from azure.mgmt.cosmosdb import CosmosDBManagementClient
from azure.identity import DefaultAzureCredential

subscription_id = "<subscription-id>"

credential = DefaultAzureCredential()

client = CosmosDBManagementClient(credential=credential, subscription=subscription_id)

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/cosmos/armcosmos"
)

const subscriptionId = "<subscription-id>"

func main() {
    credential, _ := azidentity.NewDefaultAzureCredential(nil)
    
    client, _ := armcosmos.NewDatabaseClient(subscriptionId, credential, nil)
}

package com.example;

import com.azure.core.management.profile.AzureProfile;
import com.azure.core.management.AzureEnvironment;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.resourcemanager.cosmos.CosmosManager;

public class CosmosDB {
    public static void main(String[] args) {
        AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
          .build();

        CosmosManager manager = CosmosManager.authenticate(credential, profile);
    }
}

授與資料平面角色型存取權

資料平面存取是指在 Azure 服務內讀取和寫入資料的能力，而無法管理帳戶中的資源。例如，Azure Cosmos DB 資料平面存取可能包含下列功能：

讀取一些帳戶和資源中繼資料
建立、讀取、更新、修補和刪除項目
執行資料表查詢
從容器的變更摘要中讀取
執行預存程序
管理衝突摘要中的衝突

首先，您必須準備具有 dataActions 清單的角色定義，以授與讀取、查詢和管理 Azure Cosmos DB for Table 中資料的存取權。在本指南中，您將設定內建角色和自訂角色。然後，將新定義的角色指派給身分識別，以便讓您的應用程式可以存取 Azure Cosmos DB for Table 中的資料。

首先，使用取得 az cosmsodb show 現有 Azure Cosmos DB for Table 帳戶的資源識別碼，並將其儲存在變數中。

resourceId=$( \
    az cosmosdb show \
        --resource-group "<name-of-existing-resource-group>" \
        --name "<name-of-existing-table-account>" \
        --query "id" \
        --output tsv \
)

az rest \
    --method "GET" \
    --url $resourceId/tableRoleDefinitions?api-version=2023-04-15

然後，使用 az rest列出與適用於資料表的 Azure Cosmos DB 帳戶相關聯的所有角色定義。最後，檢閱輸出，並找出名為 Cosmos DB 內建資料參與者的角色定義。輸出包含屬性中 id 角色定義的唯一識別碼。記錄此值，因為本指南稍後的指派步驟需要使用該值。

[
  ...,
  {
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table/tableRoleDefinitions/00000000-0000-0000-0000-000000000002",
    "name": "00000000-0000-0000-0000-000000000002",
    "properties": {
      "assignableScopes": [
        "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table"
      ],
      "permissions": [
        {
          "dataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/tables/*",
            "Microsoft.DocumentDB/databaseAccounts/tables/containers/entities/*"
          ],
          "notDataActions": []
        }
      ],
      "roleName": "Cosmos DB Built-in Data Contributor",
      "type": "BuiltInRole"
    },
    "type": "Microsoft.DocumentDB/databaseAccounts/tableRoleDefinitions"
  }
  ...
]

備註

在此範例中， id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table/tableRoleDefinitions/00000000-0000-0000-0000-000000000002。此範例使用虛構資料，您的識別碼將與此範例不同。此範例輸出會截斷。

建立名為 role-definition.json的新 JSON 檔案。在此檔案中，建立資源定義，指定下列資料動作：

	Description
`Microsoft.DocumentDB/databaseAccounts/readMetadata`	可以讀取帳戶層級的中繼資料
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/`**	可以執行任何容器層級的資料作業
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/`**	可以對具有容器的項目執行任何操作

{
  "properties": {
    "roleName": "Azure Cosmos DB for Table Data Plane Owner",
    "type": "CustomRole",
    "assignableScopes": [
      "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sidandrews-rbac/providers/Microsoft.DocumentDB/databaseAccounts/sidandrews-rbac-table/"
    ],
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/tables/*",
          "Microsoft.DocumentDB/databaseAccounts/tables/containers/entities/*"
        ]
      }
    ]
  }
}

現在使用 az cosmosdb show 和 az rest 一起發起 HTTP PUT 要求來建立或更新角色定義。作為此要求的一部分，請為您的角色定義指定唯一 GUID。

resourceId=$( \
    az cosmosdb show \
        --resource-group "<name-of-existing-resource-group>" \
        --name "<name-of-existing-table-account>" \
        --query "id" \
        --output tsv \
)

az rest \
    --method "PUT" \
    --url $resourceId/tableRoleDefinitions/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4?api-version=2023-04-15 \
    --body @role-definition.json

備註

在此範例中，指定的唯一 GUID 是 d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4。您可以為自己的角色定義指定任何唯一的 GUID。

現在輸出應顯示請求已被排入隊列。現在，等待已排入佇列的角色定義部署完成。此工作可能需要幾分鐘的時間。
```
{
  "status": "Enqueued"
}
```

最後，再次檢查 az rest 角色定義清單。

resourceId=$( \
    az cosmosdb show \
        --resource-group "<name-of-existing-resource-group>" \
        --name "<name-of-existing-table-account>" \
        --query "id" \
        --output tsv \
)

az rest \
    --method "GET" \
    --url $resourceId/tableRoleDefinitions?api-version=2023-04-15

用於 az cosmosdb show 取得您目前帳戶的唯一識別碼。

az cosmosdb show \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-resource-group>" \
    --query "{id:id}"

觀察上一個命令的輸出。請記錄此帳戶的id屬性值，因為在下一步中需要使用該值。
```
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table"
}
```
備註

在此範例中， id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table。此範例使用虛構資料，您的識別碼將與此範例不同。
建立名為 role-assignment.json的新 JSON 檔案。在 JSON 檔案中，新增身分的唯一識別碼和帳戶資源的唯一識別碼。
```
{
  "properties": {
    "roleDefinitionId": "<account-resource-id>/tableRoleDefinitions/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
    "scope": "<account-resource-id>",
    "principalId": "<id-of-existing-identity>"
  }
}
```
備註

在此範例中，指定的唯一 GUID 是 d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4。您可以使用您之前使用過的唯一 GUID，來定義您自己的角色。
小提示

在 Azure Cosmos DB 的角色型存取控制原生實作中，範圍是指您想要套用權限之帳戶內資源的細微性。在最高層級，您可以使用最大範圍，將資料平面角色型存取控制指派的範圍限定為整個帳戶。此範圍包括帳戶內的所有資料庫和容器：
```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/
```
或者，您可以將資料平面角色指派的範圍限定為特定資料庫：
```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>
```
最後，您可以將指派範圍限定為單一容器，這是最精細的範圍：
```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>
```
在許多情況下，您可以使用相對範圍，而不是完全限定範圍。例如，您可以使用此相對範圍，從 Azure CLI 命令將資料平面角色型存取控制權限授與特定資料庫和容器：
```
/dbs/<database-name>/colls/<container-name>
```
您也可以使用相對範圍授與所有資料庫和容器的通用存取權：
```
/
```

現在使用 az cosmosdb show 和 az rest 一起建立或更新角色指派，以發出 HTTP PUT 要求。作為此要求的一部分，請為您的角色指派指定唯一 GUID。

resourceId=$( \
    az cosmosdb show \
        --resource-group "<name-of-existing-resource-group>" \
        --name "<name-of-existing-table-account>" \
        --query "id" \
        --output tsv \
)

az rest \
    --method "PUT" \
    --url $resourceId/tableRoleAssignments/e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5?api-version=2023-04-15 \
    --body @role-assignment.json

備註

在此範例中，指定的唯一 GUID 是 e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5。您可以為自己的角色指派指定任何唯一 GUID。

首先，使用取得 az cosmsodb show 現有 Azure Cosmos DB for Table 帳戶的資源識別碼，並將其儲存在變數中。

resourceId=$( \
    az cosmosdb show \
        --resource-group "<name-of-existing-resource-group>" \
        --name "<name-of-existing-table-account>" \
        --query "id" \
        --output tsv \
)

az rest \
    --method "GET" \
    --url $resourceId/tableRoleDefinitions?api-version=2023-04-15

[
  ...,
  {
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table/tableRoleDefinitions/00000000-0000-0000-0000-000000000002",
    "name": "00000000-0000-0000-0000-000000000002",
    "properties": {
      "assignableScopes": [
        "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table"
      ],
      "permissions": [
        {
          "dataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/tables/*",
            "Microsoft.DocumentDB/databaseAccounts/tables/containers/entities/*"
          ],
          "notDataActions": []
        }
      ],
      "roleName": "Cosmos DB Built-in Data Contributor",
      "type": "BuiltInRole"
    },
    "type": "Microsoft.DocumentDB/databaseAccounts/tableRoleDefinitions"
  }
  ...
]

備註

建立新的 Bicep 檔案來定義您的角色定義。將檔案命名為 data-plane-role-definition.bicep。將這些項目新增至 dataActions 定義：

	Description
`Microsoft.DocumentDB/databaseAccounts/readMetadata`
*`Microsoft.DocumentDB/databaseAccounts/tables/`**
*`Microsoft.DocumentDB/databaseAccounts/tables/containers/entities/`**

metadata description = 'Create RBAC definition for data plane access to Azure Cosmos DB for Table.'

@description('Name of the Azure Cosmos DB for Table account.')
param accountName string

@description('Name of the role definition.')
param roleDefinitionName string = 'API for Table Data Plane Owner'

resource account 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' existing = {
  name: accountName
}

resource definition 'Microsoft.DocumentDB/databaseAccounts/tableRoleDefinitions@2023-04-15' = {
  name: guid('table-role-definition', account.id)
  parent: account
  properties: {
    roleName: roleDefinitionName
    type: 'CustomRole'
    assignableScopes: [
      account.id
    ]
    permissions: [
      {
        dataActions: [
          'Microsoft.DocumentDB/databaseAccounts/readMetadata'
          'Microsoft.DocumentDB/databaseAccounts/tables/*'
          'Microsoft.DocumentDB/databaseAccounts/tables/containers/entities/*'
        ]
      }
    ]
  }
}

output definitionId string = definition.id

小提示

在 Azure Cosmos DB 的角色型存取控制原生實作中，範圍是指您想要套用權限之帳戶內資源的細微性。在最高層級，您可以使用最大範圍，將資料平面角色型存取控制指派的範圍限定為整個帳戶。此範圍包括帳戶內的所有資料庫和容器：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

或者，您可以將資料平面角色指派的範圍限定為特定資料庫：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

最後，您可以將指派範圍限定為單一容器，這是最精細的範圍：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

在許多情況下，您可以使用相對範圍，而不是完全限定範圍。例如，您可以使用此相對範圍，從 Azure CLI 命令將資料平面角色型存取控制權限授與特定資料庫和容器：

/dbs/<database-name>/colls/<container-name>

您也可以使用相對範圍授與所有資料庫和容器的通用存取權：

建立名為 data-plane-role-definition.bicepparam的新 Bicep 參數檔案。在此參數檔案中，將現有 Azure Cosmos DB for Table 帳戶的名稱指派給參數 accountName 。
```
using './data-plane-role-definition.bicep'

param accountName = '<name-of-existing-table-account>'
```

使用 az deployment group create部署 Bicep 範本。指定 Bicep 範本、參數檔案和 Azure 資源群組的名稱。

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters data-plane-role-definition.bicepparam \
    --template-file data-plane-role-definition.bicep

查看部署結果。輸出包含屬性中 properties.outputs.definitionId.value 角色定義的唯一識別碼。記錄此值，因為本指南稍後的指派步驟需要使用該值。
```
{
  "properties": {
    "outputs": {
      "definitionId": {
        "type": "String",
        "value": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table-account/tableRoleDefinitions/dddddddd-9999-0000-1111-eeeeeeeeeeee"
      }
    }
  }
}
```
備註

在此範例中， id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table-account/tableRoleDefinitions/dddddddd-9999-0000-1111-eeeeeeeeeeee。此範例使用虛構資料，您的識別碼將與此範例不同。為了清楚起見，此範例是從部署輸出的典型 JSON 子集。

建立另一個 Bicep 檔案，為身分識別指派角色。將此檔案命名為 data-plane-role-assignment.bicep。

metadata description = 'Assign RBAC role for data plane access to Azure Cosmos DB for Table.'

@description('Name of the Azure Cosmos DB for Table account.')
param accountName string

@description('Id of the role definition to assign to the targeted principal in the context of the account.')
param roleDefinitionId string

@description('Id of the identity/principal to assign this role in the context of the account.')
param identityId string

resource account 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' existing = {
  name: accountName
}

resource assignment 'Microsoft.DocumentDB/databaseAccounts/tableRoleAssignments@2023-04-15' = {
  name: guid(roleDefinitionId, identityId, account.id)
  parent: account
  properties: {
    principalId: identityId
    roleDefinitionId: roleDefinitionId
    scope: account.id
  }
}

output id string = assignment.id

建立名為 data-plane-role-assignment.bicepparam的新 Bicep 參數檔案。在此參數檔案中;將現有 Azure Cosmos DB for Table 帳戶的名稱指派給 accountName 參數，將先前記錄的角色定義識別碼指派給 roleDefinitionId 參數，並將身分識別的唯一識別碼指派給 identityId 參數。
```
using './data-plane-role-assignment.bicep'

param accountName = '<name-of-existing-table-account>'
param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'
```

使用 az deployment group create 部署此 Bicep 範本。

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters data-plane-role-assignment.bicepparam \
    --template-file data-plane-role-assignment.bicep

重複這些步驟，以從您要使用的任何其他身分識別授予存取帳戶之權利。

小提示

您可以對任意數量的身分重複這些步驟。一般而言，這些步驟至少會重複，以允許開發人員使用其人類身分識別存取帳戶，並允許應用程式使用受控識別存取資料。

用 Get-AzCosmosDBAccount 來取得現有 Azure Cosmos DB for Table 帳戶的資源識別碼，並將它儲存在變數中。

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-table-account>"
}
$resourceId = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Id -First 1
).Id

$parameters = @{
  Path = "$resourceId/tableRoleDefinitions?api-version=2023-04-15"
  Method = "GET"
}
Invoke-AzRestMethod @parameters

然後，使用 Invoke-AzRestMethod 來列出與資料表帳戶的 Azure Cosmos DB 相關的所有角色定義。檢閱輸出，並找出名為 Cosmos DB 內建資料參與者的角色定義。輸出包含屬性中 Id 角色定義的唯一識別碼。記錄此值，因為本指南稍後的指派步驟需要使用該值。

StatusCode : 200
Content    : {
    "value": [
      ...,
      {
        "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table/tableRoleDefinitions/00000000-0000-0000-0000-000000000002",
        "name": "00000000-0000-0000-0000-000000000002",
        "properties": {
          "assignableScopes": [
            "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table"
          ],
          "permissions": [
            {
              "dataActions": [
                "Microsoft.DocumentDB/databaseAccounts/readMetadata",
                "Microsoft.DocumentDB/databaseAccounts/tables/*",
                "Microsoft.DocumentDB/databaseAccounts/tables/containers/entities/*"
              ],
              "notDataActions": []
            }
          ],
          "roleName": "Cosmos DB Built-in Data Contributor",
          "type": "BuiltInRole"
        },
        "type": "Microsoft.DocumentDB/databaseAccounts/tableRoleDefinitions"
      }
      ...
      ]
    },
    ...
  ]
}

備註

在此範例中， Id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table/tableRoleDefinitions/00000000-0000-0000-0000-000000000002。此範例使用虛構資料，您的識別碼將與此範例不同。此範例輸出會截斷。

使用Get-AzCosmosDBAccount和Invoke-AzRestMethod一起建立或更新您的角色定義，以發出 HTTP PUT要求。此外，在此要求中，請為您的角色定義指定唯一的 GUID。最後，建立資源定義承載，指定此處列出的資料動作：

	Description
`Microsoft.DocumentDB/databaseAccounts/readMetadata`	可以讀取帳戶層級的中繼資料
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/`**	可以執行任何容器層級的資料作業
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/`**	可以對具有容器的項目執行任何操作

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-table-account>"
}
$resourceId = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Id -First 1
).Id

$payload = @{
  properties = @{
    roleName = "Azure Cosmos DB for Table Data Plane Owner"
    type = "CustomRole"
    assignableScopes = @(
      "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sidandrews-rbac/providers/Microsoft.DocumentDB/databaseAccounts/sidandrews-rbac-table/"
    )
    permissions = @(
      @{
        dataActions = @(
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/tables/*",
          "Microsoft.DocumentDB/databaseAccounts/tables/containers/entities/*"
        )
      }
    )
  }
}

$parameters = @{
  Path = "$resourceId/tableRoleDefinitions/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4?api-version=2023-04-15"
  Method = "PUT"
  Payload = $payload | ConvertTo-Json -Depth 4
}
Invoke-AzRestMethod @parameters

備註

在此範例中，指定的唯一 GUID 是 d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4。您可以為自己的角色定義指定任何唯一的 GUID。

小提示

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

或者，您可以將資料平面角色指派的範圍限定為特定資料庫：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

最後，您可以將指派範圍限定為單一容器，這是最精細的範圍：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

/dbs/<database-name>/colls/<container-name>

您也可以使用相對範圍授與所有資料庫和容器的通用存取權：

輸出應該傳回狀態碼 200。現在，等待已排入佇列的角色定義部署完成。此工作可能需要幾分鐘的時間。
```
StatusCode : 200
...
```

最後，再次檢查 Invoke-AzRestMethod 角色定義清單。

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-table-account>"
}
$resourceId = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Id -First 1
).Id

$parameters = @{
  Path = "$resourceId/tableRoleDefinitions?api-version=2023-04-15"
  Method = "GET"
}
Invoke-AzRestMethod @parameters

使用 `Get-AzCosmosDBAccount` 取得您目前帳戶的唯一識別碼。

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-table-account>"
}
Get-AzCosmosDBAccount @parameters | Select -Property Id

觀察上一個命令的輸出。請記錄此帳戶的Id屬性值，因為在下一步中需要使用該值。
```
Id
--    
/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table
```
備註

在此範例中， Id 值會是 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-table。此範例使用虛構資料，您的識別碼將與此範例不同。

現在使用 Get-AzCosmosDBAccount 和 Invoke-AzRestMethod 一起建立或更新角色指派，以發出 HTTP PUT 要求。作為此要求的一部分，請為您的角色指派指定唯一 GUID。最後，建立資源指派承載，為您的身分識別指定唯一識別碼。

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-table-account>"
}
$resourceId = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Id -First 1
).Id    

$payload = @{
  properties = @{
    roleDefinitionId = "$resourceId/tableRoleDefinitions/00000000-0000-0000-0000-000000000002"
    scope = "$resourceId"
    principalId = "<id-of-existing-identity>"
  }
}

$parameters = @{
  Path = "$resourceId/tableRoleAssignments/e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5?api-version=2023-04-15"
  Method = "PUT"
  Payload = $payload | ConvertTo-Json -Depth 2
}
Invoke-AzRestMethod @parameters

備註

在此範例中，指定的唯一 GUID 是 e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5。您可以為自己的角色指派指定任何唯一 GUID。

警告

Azure 入口網站不支援管理資料平面的角色型存取控制。

在程式碼中驗證資料平面角色型存取

請驗證您是否透過應用程式程式碼及 Azure SDK 正確授予存取權。

using Azure.Identity;
using Azure.Data.Tables;

string endpoint = "<account-endpoint>";

DefaultAzureCredential credential = new();

TableServiceClient client = new(
    endpoint: new Uri(endpoint),
    tokenCredential: credential
);

TableClient table = client.GetTableClient(
    tableName: "<name-of-table>"
);

await table.GetEntityAsync<TableEntity>(
    partitionKey: "<partition-key>",
    rowKey: "<row-key>"
);

const { TableServiceClient, TableClient } = require('@azure/data-tables');
const { DefaultAzureCredential } = require('@azure/identity');

const endpoint = '<account-endpoint>';

let credential = new DefaultAzureCredential();

let client = new TableServiceClient(endpoint, credential);

let table = new TableClient(endpoint, "<table-name>", credential);

await table.getEntity("<partition-key>", "<row-key>");

import { TableServiceClient, TableClient } from '@azure/data-tables';
import { TokenCredential, DefaultAzureCredential } from '@azure/identity';

const endpoint: string = '<account-endpoint>';

let credential: TokenCredential = new DefaultAzureCredential();

let client: TableServiceClient = new TableServiceClient(endpoint, credential);

let table: TableClient = new TableClient(endpoint, "<table-name>", credential);

await table.getEntity("<partition-key>", "<row-key>");

from azure.data.tables import TableServiceClient
from azure.identity import DefaultAzureCredential

endpoint = "<account-endpoint>"

credential = DefaultAzureCredential()

client = TableServiceClient(endpoint, credential=credential)

table = client.get_table_client("<table-name>")

table.get_entity(
    row_key="<row-key>",
    partition_key="<partition-key>"
)

import (
    "context"
    
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/data/aztables"
)

const endpoint = "<account-endpoint>"

func main() {
    credential, _ := azidentity.NewDefaultAzureCredential(nil)
    client, _ := aztables.NewServiceClient(endpoint, credential, nil)
    table := client.NewClient("<table-name>")
    
    _, err := table.GetEntity(context.TODO(), "<partition-key>", "<row-key>", nil)
    if err != nil {
        panic(err)
    }
}

import com.azure.data.tables.TableClient;
import com.azure.data.tables.TableServiceClient;
import com.azure.data.tables.TableServiceClientBuilder;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class Table{
    public static void main(String[] args){
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .build();
        
        TableServiceClient client = new TableServiceClientBuilder()
            .endpoint("<table-endpoint>")
            .credential(credential)
            .buildClient();

        TableClient table = client
            .getTableClient("<table-name>");

        table.getEntity("<partition-key>", "<row-key>");
    }
}

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-09-11

共用方式為

使用角色型存取控制和 Microsoft Entra ID 連線到 Azure Cosmos DB for Table

先決條件

停用金鑰型驗證

驗證金鑰型驗證是否已停用

授與控制平面角色型存取權

在程式碼中驗證控制平面角色型存取

授與資料平面角色型存取權

在程式碼中驗證資料平面角色型存取

相關內容

意見反應

其他資源