Início Rápido: Criar um Azure Cosmos DB e um contêiner usando um modelo do Resource Manager

Artigo
08/15/2024

APLICA-SE A: NoSQL

O Azure Cosmos DB é o banco de dados NoSQL rápido da Microsoft com APIs abertas para qualquer escala. É possível usar o Azure Cosmos DB para criar e consultar rapidamente bancos de dados de chave/valor, de documentos e de grafo. Sem um cartão de crédito ou uma assinatura do Azure, você pode configurar uma conta gratuita do Try do Azure Cosmos DB. Este guia de início rápido tem como foco o processo de implantação de um modelo do ARM (modelo do Azure Resource Manager) para criar um banco de dados do Azure Cosmos DB e um contêiner nesse banco de dados. Posteriormente, você poderá armazenar dados nesse contêiner.

Um Modelo do Azure Resource Manager é um arquivo JSON (JavaScript Object Notation) que define a infraestrutura e a configuração do seu projeto. O modelo usa a sintaxe declarativa. Você descreve a implantação pretendida sem escrever a sequência de comandos de programação para criar a implantação.

Se seu ambiente atender aos pré-requisitos e você estiver familiarizado com o uso de modelos ARM, selecione o botão Implantar no Azure. O modelo será aberto no portal do Azure.

Pré-requisitos

Uma assinatura do Azure ou uma conta de avaliação gratuita do Azure Cosmos DB

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.
Você pode experimentar o Azure Cosmos DB gratuitamente, sem uma assinatura do Azure e sem compromisso. Como alternativa, você pode criar uma conta de camada gratuita do Azure Cosmos DB, com as primeiras 1.000 RU/s e 25 GB de armazenamento gratuitos. Você também pode usar o emulador do Azure Cosmos DB com o URI https://localhost:8081. Quanto à chave a ser usada com o emulador, confira Autenticação de solicitações.

Examinar o modelo

O modelo usado neste início rápido é proveniente dos Modelos de Início Rápido do Azure.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.26.54.24096",
      "templateHash": "7578513359154607542"
    }
  },
  "parameters": {
    "accountName": {
      "type": "string",
      "defaultValue": "[format('sql-{0}', uniqueString(resourceGroup().id))]",
      "metadata": {
        "description": "Azure Cosmos DB account name, max length 44 characters"
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for the Azure Cosmos DB account."
      }
    },
    "primaryRegion": {
      "type": "string",
      "metadata": {
        "description": "The primary region for the Azure Cosmos DB account."
      }
    },
    "secondaryRegion": {
      "type": "string",
      "metadata": {
        "description": "The secondary region for the Azure Cosmos DB account."
      }
    },
    "defaultConsistencyLevel": {
      "type": "string",
      "defaultValue": "Session",
      "allowedValues": [
        "Eventual",
        "ConsistentPrefix",
        "Session",
        "BoundedStaleness",
        "Strong"
      ],
      "metadata": {
        "description": "The default consistency level of the Cosmos DB account."
      }
    },
    "maxStalenessPrefix": {
      "type": "int",
      "defaultValue": 100000,
      "minValue": 10,
      "maxValue": 2147483647,
      "metadata": {
        "description": "Max stale requests. Required for BoundedStaleness. Valid ranges, Single Region: 10 to 2147483647. Multi Region: 100000 to 2147483647."
      }
    },
    "maxIntervalInSeconds": {
      "type": "int",
      "defaultValue": 300,
      "minValue": 5,
      "maxValue": 86400,
      "metadata": {
        "description": "Max lag time (minutes). Required for BoundedStaleness. Valid ranges, Single Region: 5 to 84600. Multi Region: 300 to 86400."
      }
    },
    "systemManagedFailover": {
      "type": "bool",
      "defaultValue": true,
      "allowedValues": [
        true,
        false
      ],
      "metadata": {
        "description": "Enable system managed failover for regions"
      }
    },
    "databaseName": {
      "type": "string",
      "defaultValue": "myDatabase",
      "metadata": {
        "description": "The name for the database"
      }
    },
    "containerName": {
      "type": "string",
      "defaultValue": "myContainer",
      "metadata": {
        "description": "The name for the container"
      }
    },
    "throughput": {
      "type": "int",
      "defaultValue": 400,
      "minValue": 400,
      "maxValue": 1000000,
      "metadata": {
        "description": "The throughput for the container"
      }
    }
  },
  "variables": {
    "consistencyPolicy": {
      "Eventual": {
        "defaultConsistencyLevel": "Eventual"
      },
      "ConsistentPrefix": {
        "defaultConsistencyLevel": "ConsistentPrefix"
      },
      "Session": {
        "defaultConsistencyLevel": "Session"
      },
      "BoundedStaleness": {
        "defaultConsistencyLevel": "BoundedStaleness",
        "maxStalenessPrefix": "[parameters('maxStalenessPrefix')]",
        "maxIntervalInSeconds": "[parameters('maxIntervalInSeconds')]"
      },
      "Strong": {
        "defaultConsistencyLevel": "Strong"
      }
    },
    "locations": [
      {
        "locationName": "[parameters('primaryRegion')]",
        "failoverPriority": 0,
        "isZoneRedundant": false
      },
      {
        "locationName": "[parameters('secondaryRegion')]",
        "failoverPriority": 1,
        "isZoneRedundant": false
      }
    ]
  },
  "resources": [
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "apiVersion": "2024-02-15-preview",
      "name": "[toLower(parameters('accountName'))]",
      "location": "[parameters('location')]",
      "kind": "GlobalDocumentDB",
      "properties": {
        "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
        "locations": "[variables('locations')]",
        "databaseAccountOfferType": "Standard",
        "enableAutomaticFailover": "[parameters('systemManagedFailover')]",
        "disableKeyBasedMetadataWriteAccess": true
      }
    },
    {
      "type": "Microsoft.DocumentDB/databaseAccounts/sqlDatabases",
      "apiVersion": "2024-02-15-preview",
      "name": "[format('{0}/{1}', toLower(parameters('accountName')), parameters('databaseName'))]",
      "properties": {
        "resource": {
          "id": "[parameters('databaseName')]"
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.DocumentDB/databaseAccounts', toLower(parameters('accountName')))]"
      ]
    },
    {
      "type": "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers",
      "apiVersion": "2024-02-15-preview",
      "name": "[format('{0}/{1}/{2}', toLower(parameters('accountName')), parameters('databaseName'), parameters('containerName'))]",
      "properties": {
        "resource": {
          "id": "[parameters('containerName')]",
          "partitionKey": {
            "paths": [
              "/myPartitionKey"
            ],
            "kind": "Hash"
          },
          "indexingPolicy": {
            "indexingMode": "consistent",
            "includedPaths": [
              {
                "path": "/*"
              }
            ],
            "excludedPaths": [
              {
                "path": "/myPathToNotIndex/*"
              },
              {
                "path": "/_etag/?"
              }
            ],
            "compositeIndexes": [
              [
                {
                  "path": "/name",
                  "order": "ascending"
                },
                {
                  "path": "/age",
                  "order": "descending"
                }
              ]
            ],
            "spatialIndexes": [
              {
                "path": "/location/*",
                "types": [
                  "Point",
                  "Polygon",
                  "MultiPolygon",
                  "LineString"
                ]
              }
            ]
          },
          "defaultTtl": 86400,
          "uniqueKeyPolicy": {
            "uniqueKeys": [
              {
                "paths": [
                  "/phoneNumber"
                ]
              }
            ]
          }
        },
        "options": {
          "throughput": "[parameters('throughput')]"
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.DocumentDB/databaseAccounts/sqlDatabases', toLower(parameters('accountName')), parameters('databaseName'))]"
      ]
    }
  ],
  "outputs": {
    "location": {
      "type": "string",
      "value": "[parameters('location')]"
    },
    "name": {
      "type": "string",
      "value": "[parameters('databaseName')]"
    },
    "resourceGroupName": {
      "type": "string",
      "value": "[resourceGroup().name]"
    },
    "resourceId": {
      "type": "string",
      "value": "[resourceId('Microsoft.DocumentDB/databaseAccounts/sqlDatabases', toLower(parameters('accountName')), parameters('databaseName'))]"
    }
  }
}

Há três recursos do Azure definidos no modelo:

Microsoft.DocumentDB/databaseAccounts: crie uma conta do Azure Cosmos DB.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases: crie um banco de dados do Azure Cosmos DB.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers: crie um contêiner do Azure Cosmos DB.

Importante

O provedor do Azure Resource Manager, Microsoft.DocumentDB/databaseAccounts, manteve o mesmo nome por muitos anos. Isso garante que os modelos escritos há anos ainda sejam compatíveis com o mesmo provedor, mesmo que o nome do serviço e dos subserviços tenha evoluído.

Mais exemplos de modelos do Azure Cosmos DB podem ser encontrados na galeria de modelos de início rápido.

Implantar o modelo

Selecione a imagem a seguir para entrar no Azure e abrir um modelo. O modelo cria uma conta, um banco de dados e um contêiner do Azure Cosmos DB.
Selecione ou insira os seguintes valores.

A menos que seja especificado, use os valores padrão para criar os recursos do Azure Cosmos DB.
- Assinatura: selecione uma assinatura do Azure.
- Grupo de recursos: selecione Criar novo, insira um nome exclusivo para o grupo de recursos e, em seguida, clique em OK.
- Local: selecione um local. Por exemplo, Centro dos EUA.
- Nome da Conta: insira um nome para a conta do Azure Cosmos DB. Deve ser globalmente exclusivo.
- Localização: insira uma localização em que deseja criar sua conta do Azure Cosmos DB. A conta do Azure Cosmos pode estar na mesma localização do grupo de recursos.
- Região Primária: a região da réplica primária para a conta do Azure Cosmos DB.
- Região secundária: a região da réplica secundária para a conta do Azure Cosmos DB.
- Nível de Consistência Padrão: o nível de consistência padrão para a conta do Azure Cosmos DB.
- Prefixo máximo de desatualização: máximo de solicitações obsoletas. Exigido para BoundedStaleness.
- Intervalo máximo em segundos: tempo de retardo máximo. Exigido para BoundedStaleness.
- Nome do Banco de Dados: o nome do banco de dados do Azure Cosmos DB.
- Nome do Contêiner: o nome do contêiner do Azure Cosmos DB.
- Taxa de Transferência: a taxa de transferência do contêiner, cujo valor mínimo é de 400 RU/s.
- Concordo com os termos e condições declarados acima: selecione.
Selecione Comprar. Depois que a conta do Azure Cosmos DB for implantada com sucesso, você receberá uma notificação:

O portal do Azure é usado para implantar o modelo. Além do portal do Azure, você também pode usar o Azure PowerShell, a CLI do Azure e a API REST. Para saber mais sobre outros métodos de implantação, confira Implantar modelos.

Validar a implantação

Você pode usar o portal do Azure para verificar a conta, o banco de dados e o contêiner do Azure Cosmos DB ou usar o script da CLI do Azure ou do Azure PowerShell a seguir para listar o segredo criado.

CLI
PowerShell

echo "Enter your Azure Cosmos DB account name:" &&
read cosmosAccountName &&
echo "Enter the resource group where the Azure Cosmos DB account exists:" &&
read resourcegroupName &&
az cosmosdb show -g $resourcegroupName -n $cosmosAccountName

$resourceGroupName = Read-Host -Prompt "Enter the resource group name where your Azure Cosmos DB account exists"
(Get-AzResource -ResourceType "Microsoft.DocumentDB/databaseAccounts" -ResourceGroupName $resourceGroupName).Name
 Write-Host "Press [ENTER] to continue..."

Limpar os recursos

Se planejar continuar trabalhando com os tutoriais e inícios rápidos subsequentes, deixe esses recursos onde estão. Quando o grupo de recursos não for mais necessário, exclua-o, o que excluirá a conta do Azure Cosmos DB e os recursos relacionados. Para excluir o grupo de recursos usando a CLI do Azure ou o Azure PowerShell:

CLI
PowerShell

echo "Enter the Resource Group name:" &&
read resourceGroupName &&
az group delete --name $resourceGroupName &&
echo "Press [ENTER] to continue ..."

$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
Remove-AzResourceGroup -Name $resourceGroupName
Write-Host "Press [ENTER] to continue..."

Próximas etapas

Neste guia de início rápido, você criou uma conta, um banco de dados e um contêiner do Azure Cosmos DB usando um modelo do ARM e validou a implantação. Para saber mais sobre o Azure Cosmos DB e o Azure Resource Manager, continue com os artigos abaixo.

Leia uma Visão geral do Azure Cosmos DB
Saiba mais sobre o Azure Resource Manager
Obtenha outros Modelos do Azure Resource Manager para o Azure Cosmos DB
Tentando fazer um planejamento de capacidade para uma migração para o Microsoft Azure Cosmos DB? Você pode usar informações sobre o cluster de banco de dados existente para fazer isso.
- Se você sabe apenas o número de vCores e servidores no cluster de banco de dados existente, leia sobre como estimar unidades de solicitação com vCores ou vCPUs
- Se souber as taxas de solicitação típicas da carga de trabalho do banco de dados atual, leia sobre como estimar unidades de solicitação usando o planejador de capacidade do Azure Cosmos DB

Compartilhar via