練習 - 更新範本規格並進行版本設定

  • 4 分鐘

貴組織現在都使用您的 Azure Cosmos DB 範本規格來佈建許多新的 Azure Cosmos DB 帳戶。 因此，所有這些帳戶會設定為使用連續備份。

您的安全性小組最近已檢閱過 Azure Cosmos DB 安全性功能。 其決定新帳戶應使用 Microsoft Entra 驗證與 Azure Cosmos DB 角色型存取控制。

在此練習中，您會使用新版本 (包含更新的驗證設定) 來更新範本規格。

在此過程中，您將會：

  • 更新範本以重新設定備份原則。
  • 發佈新版本的範本規格。
  • 驗證範本規格已更新。
  • 透過部署另一個 Azure Cosmos DB 帳戶來測試新版本的範本規格。

更新範本

  1. 在 Visual Studio Code 中，開啟 azuredeploy.js 檔案。

  2. 更新 azuredeploy.js 檔案以包含下列變更：

    {
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "The Azure region into which the Cosmos DB resources should be deployed."
      }
    },
    "cosmosDBAccountName": {
      "type": "string",
      "defaultValue": "[concat('toy-', uniqueString(resourceGroup().id))]",
      "maxLength": 44,
      "minLength": 3,
      "metadata": {
        "description": "The name of the Cosmos DB account. This name must be globally unique, and it must only include lowercase letters, numbers, and hyphens."
      }
    },
    "roleDefinitionFriendlyName": {
      "type": "string",
      "defaultValue": "Read and Write",
      "metadata": {
        "description": "A descriptive name for the role definition."
      }
    },
    "roleDefinitionDataActions": {
      "type": "array",
      "defaultValue": [
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
      ],
      "metadata": {
        "description": "The list of actions that the role definition permits."
      }
    },
    "roleAssignmentPrincipalId": {
      "type": "string",
      "metadata": {
        "description": "The object ID of the Azure AD principal that should be granted access using the role definition."
      }
    }
  },
  "variables": {
    "roleDefinitionName": "[guid('sql-role-definition', resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName')))]",
    "roleAssignmentName": "[guid('sql-role-assignment', resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName')))]"
  },
  "resources": [
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "apiVersion": "2021-04-15",
      "name": "[parameters('cosmosDBAccountName')]",
      "kind": "GlobalDocumentDB",
      "location": "[parameters('location')]",
      "properties": {
        "consistencyPolicy": {
          "defaultConsistencyLevel": "Session"
        },
        "locations": [
          {
            "locationName": "[parameters('location')]",
            "failoverPriority": 0,
            "isZoneRedundant": false
          }
        ],
        "databaseAccountOfferType": "Standard",
        "enableAutomaticFailover": false,
        "enableMultipleWriteLocations": false,
        "backupPolicy": {
          "type": "Continuous"
        }
      }
    },
    {
      "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
      "apiVersion": "2021-04-15",
      "name": "[format('{0}/{1}', parameters('cosmosDBAccountName'), variables('roleDefinitionName'))]",
      "properties": {
        "roleName": "[parameters('roleDefinitionFriendlyName')]",
        "type": "CustomRole",
        "assignableScopes": [
          "[resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName'))]"
        ],
        "permissions": [
          {
            "dataActions": "[parameters('roleDefinitionDataActions')]"
          }
        ]
      },
      "dependsOn": [
        "[resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName'))]"
      ]
    },
    {
      "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments",
      "apiVersion": "2021-04-15",
      "name": "[format('{0}/{1}', parameters('cosmosDBAccountName'), variables('roleAssignmentName'))]",
      "properties": {
        "roleDefinitionId": "[resourceId('Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions', parameters('cosmosDBAccountName'), variables('roleDefinitionName'))]",
        "principalId": "[parameters('roleAssignmentPrincipalId')]",
        "scope": "[resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName'))]"
      },
      "dependsOn": [
        "[resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName'))]",
        "[resourceId('Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions', parameters('cosmosDBAccountName'), variables('roleDefinitionName'))]"
      ]
    }
  ]
}

  3. 儲存檔案。

  1. 在 Visual Studio Code 中，開啟 main.bicep 檔案。

  2. 更新 main.bicep 檔案以包含下列變更：

    @description('The Azure region into which the Cosmos DB resources should be deployed.')
param location string = resourceGroup().location

@description('The name of the Cosmos DB account. This name must be globally unique, and it must only include lowercase letters, numbers, and hyphens.')
@minLength(3)
@maxLength(44)
param cosmosDBAccountName string = 'toy-${uniqueString(resourceGroup().id)}'

@description('A descriptive name for the role definition.')
param roleDefinitionFriendlyName string = 'Read and Write'

@description('The list of actions that the role definition permits.')
param roleDefinitionDataActions array = [
  'Microsoft.DocumentDB/databaseAccounts/readMetadata'
  'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*'
]

@description('The object ID of the Azure AD principal that should be granted access using the role definition.')
param roleAssignmentPrincipalId string

var roleDefinitionName = guid('sql-role-definition', cosmosDBAccount.id)
var roleAssignmentName = guid('sql-role-assignment', cosmosDBAccount.id)

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2021-04-15' = {
  name: cosmosDBAccountName
  kind: 'GlobalDocumentDB'
  location: location
  properties: {
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    locations: [
      {
        locationName: location
        failoverPriority: 0
        isZoneRedundant: false
      }
    ]
    databaseAccountOfferType: 'Standard'
    enableAutomaticFailover: false
    enableMultipleWriteLocations: false
  }
}

resource roleDefinition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2021-04-15' = {
  parent: cosmosDBAccount
  name: roleDefinitionName
  properties: {
    roleName: roleDefinitionFriendlyName
    type: 'CustomRole'
    assignableScopes: [
      cosmosDBAccount.id
    ]
    permissions: [
      {
        dataActions: roleDefinitionDataActions
      }
    ]
  }
}

resource roleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2021-04-15' = {
  parent: cosmosDBAccount
  name: roleAssignmentName
  properties: {
    roleDefinitionId: roleDefinition.id
    principalId: roleAssignmentPrincipalId
    scope: cosmosDBAccount.id
  }
}

  3. 儲存檔案。

發佈新版本的範本規格

在 Visual Studio Code 終端中，使用這個 Azure PowerShell Cmdlet 來發佈範本規格：

New-AzTemplateSpec `
  -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
  -Name ToyCosmosDBAccount `
  -Version '2.0' `
  -VersionDescription 'Adds Cosmos DB role-based access control.' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
  -Name ToyCosmosDBAccount `
  -Version '2.0' `
  -VersionDescription 'Adds Cosmos DB role-based access control.' `
  -TemplateFile azuredeploy.json

在 Visual Studio Code 終端機中，使用這個 Azure CLI 命令來發佈範本規格：

az ts create \
  --name ToyCosmosDBAccount \
  --version 2.0 \
  --version-description "Adds Cosmos DB role-based access control." \
  --template-file main.bicep

az ts create \
  --name ToyCosmosDBAccount \
  --version 2.0 \
  --version-description "Adds Cosmos DB role-based access control." \
  --template-file azuredeploy.json

驗證範本規格

  1. 在瀏覽器中，返回 Azure 入口網站。 移至您的資源群組。

  2. 選取範本規格。請注意，最新版本現在會列為 2.0。

    Screenshot of the Azure portal interface for the template spec, showing the latest version as 2.0.

  3. 選取 [版本] 功能表項目。 請注意，這兩個版本現在都會列出。

    Screenshot of the Azure portal interface for the template spec, showing the list of versions as 1.0 and 2.0.

    範本規格版本可讓您視需要返回先前版本的範本規格。

部署新的範本規格版本

  1. 透過執行下列 Azure PowerShell 命令來取得新範本規格版本的資源識別碼：

    $templateSpecVersionResourceId = ( `
   Get-AzTemplateSpec `
      -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
      -Name ToyCosmosDBAccount `
      -Version 2.0 `
   ).Versions[0].Id

    請注意，您可以使用 Versions 屬性來取得範本規格版本的資源識別碼。

  2. 新的範本規格版本具有使用者主體識別碼的參數。 使用下列命令來取得您自己的使用者帳戶主體識別碼：

    $token = (Get-AzAccessToken -ResourceUrl "https://graph.windows.net/").Token
$userObjectId = (Invoke-RestMethod -Uri 'https://graph.windows.net/me?api-version=1.6' -Headers @{ 'Authorization' = "Bearer $token"}).objectID

    這些命令會使用 Microsoft Graph API 來查詢您自己的使用者設定檔。

  3. 在 Visual Studio Code 終端中，使用這個 Azure PowerShell 命令來部署範本規格：

    New-AzResourceGroupDeployment `
  -TemplateSpecId $templateSpecVersionResourceId `
  -roleAssignmentPrincipalId $userObjectId

  1. 透過執行下列 Azure CLI 命令來取得範本規格版本的資源識別碼：

    id=$(az ts show \
 --name ToyCosmosDBAccount \
 --resource-group "<rgn>[sandbox resource group name]</rgn>" \
 --version "2.0" \
 --query "id")

  2. 在 Visual Studio Code 終端機中，使用這個 Azure CLI 命令來部署範本規格：

    az deployment group create \
 --template-spec $id \
 --parameters roleAssignmentPrincipalId="d68d19b3-d7ef-4ae9-9ee4-90695a4e417d"

部署可能需要一或兩分鐘才能完成。

檢查部署

  1. 在瀏覽器中，返回 Azure 入口網站。 移至您的資源群組。

  2. 在 [部署] 旁，選取 [2 個成功]。

    Screenshot of the Azure portal interface for the resource group overview, with the deployments section showing that two succeeded.

  3. 選取最新部署。

    Screenshot of the Azure portal interface for the deployments, with two deployments listed.

  4. 選取 [部署詳細資料] 以將其展開。 確認部署了 Azure Cosmos DB 角色型存取控制的資源。

    Screenshot of the Azure portal interface for the specific deployment, with the Azure Cosmos DB resources listed.