Gerenciar uma conta do Azure CosmosManage an Azure Cosmos account

Este artigo descreve como gerenciar várias tarefas em uma conta do Azure Cosmos usando o portal do Azure, o Azure PowerShell, a CLI do Azure e modelos do Azure Resource Manager.This article describes how to manage various tasks on an Azure Cosmos account using the Azure portal, Azure PowerShell, Azure CLI, and Azure Resource Manager templates.

Criar uma contaCreate an account

Portal do AzureAzure portal

  1. Entre no Portal do Azure.Sign in to the Azure portal.

  2. Selecione Criar um recurso > Bancos de dados > Azure Cosmos DB.Select Create a resource > Databases > Azure Cosmos DB.

    O painel Bancos de Dados do portal do Azure

  3. Na página Criar Conta do Azure Cosmos DB, insira as configurações básicas da nova conta do Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    ConfiguraçãoSetting ValorValue DESCRIÇÃODescription
    AssinaturaSubscription Nome da assinaturaSubscription name Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Grupo de recursosResource Group Nome do grupo de recursosResource group name Selecione um grupo de recursos ou selecione Criar novo, então insira um nome exclusivo para o novo grupo de recursos.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nome da contaAccount Name Insira um nome exclusivoEnter a unique name Insira um nome para identificar a conta do Azure Cosmos.Enter a name to identify your Azure Cosmos account. Como documents.Azure.com é acrescentado à ID que você fornece para criar o URI, use uma ID exclusiva.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    A ID pode conter apenas letras minúsculas, números e o caractere de hífen (-).The ID can only contain lowercase letters, numbers, and the hyphen (-) character. Ela deve ter entre 3 e 31 caracteres.It must be between 3-31 characters in length.
    APIAPI Núcleo (SQL)Core (SQL) A API determina o tipo de conta a ser criada.The API determines the type of account to create. O Azure Cosmos DB fornece cinco APIs: Núcleo (SQL) e MongoDB para dados de documento, Gremlin para dados de grafo, Tabela do Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. No momento, você deve criar uma conta separada para cada API.Currently, you must create a separate account for each API.

    Selecione Núcleo (SQL) para criar uma consulta e um banco de dados de documento usando a sintaxe SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    Saiba mais sobre a API do SQL.Learn more about the SQL API.
    Local padrãoLocation Selecione a região mais próxima de seus usuáriosSelect the region closest to your users Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.Use the location that is closest to your users to give them the fastest access to the data.

    A página da nova conta do Azure Cosmos DB

  4. Selecione Examinar + criar.Select Review + create. Você pode ignorar as seções Rede e Marcas.You can skip the Network and Tags sections.

  5. Examine as configurações da conta e selecione Criar.Review the account settings, and then select Create. São necessários alguns minutos para criar a conta.It takes a few minutes to create the account. Aguarde até que a página do portal exiba Sua implantação está concluída.Wait for the portal page to display Your deployment is complete.

    O painel Notificações do portal do Azure

  6. Selecione Ir para recurso para ir para a página da conta do Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    A página da conta do Azure Cosmos DB

Azure CLIAzure CLI

# Create an account
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname' # must be lower case.

az cosmosdb create \
   --name $accountName \
   --resource-group $resourceGroupName \
   --kind GlobalDocumentDB \
   --default-consistency-level Session \
   --locations regionName=WestUS failoverPriority=0 isZoneRedundant=False \
   --locations regionName=EastUS failoverPriority=1 isZoneRedundant=False \
   --enable-multiple-write-locations true

PowerShell do AzureAzure PowerShell

# Create an Azure Cosmos account for Core (SQL) API
$resourceGroupName = "myResourceGroup"
$location = "West US"
$accountName = "mycosmosaccount" # must be lower case.

$locations = @(
    @{ "locationName"="West US"; "failoverPriority"=0 },
    @{ "locationName"="East US"; "failoverPriority"=1 }
)

$consistencyPolicy = @{
    "defaultConsistencyLevel"="BoundedStaleness";
    "maxIntervalInSeconds"=300;
    "maxStalenessPrefix"=100000
}

$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$locations;
    "consistencyPolicy"=$consistencyPolicy;
    "enableMultipleWriteLocations"="true"
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Location $location `
    -Name $accountName -PropertyObject $CosmosDBProperties

Modelo do Azure Resource ManagerAzure Resource Manager template

Este modelo do Azure Resource Manager criará uma conta do Azure Cosmos para qualquer API compatível configurada com duas regiões e as opções para selecionar o nível de consistência, o failover automático e vários mestres.This Azure Resource Manager template will create an Azure Cosmos account for any supported API configured with two regions and options to select consistency level, automatic failover, and multi-master. Para implantar esse modelo, clique em Implantar no Azure na página do arquivo Leiame, Criar uma conta do Azure CosmosTo deploy this template, click on Deploy to Azure on the readme page, Create Azure Cosmos account

Adicionar ou remover regiões de sua conta de banco de dadosAdd/remove regions from your database account

Portal do AzureAzure portal

  1. Entre no Portal do Azure.Sign in to Azure portal.

  2. Vá até sua conta do Azure Cosmos e abra o menu Replicar dados globalmente.Go to your Azure Cosmos account, and open the Replicate data globally menu.

  3. Para adicionar regiões, selecione os hexágonos no mapa com o rótulo + que corresponde às regiões desejadas.To add regions, select the hexagons on the map with the + label that corresponds to your desired region(s). Como alternativa, para adicionar uma região, escolha a opção +Adicionar região e escolha uma região no menu suspenso.Alternatively, to add a region, select the + Add region option and choose a region from the drop-down menu.

  4. Para remover regiões, desmarque uma ou mais regiões do mapa marcando os hexágonos azuis com marcas de seleção.To remove regions, clear one or more regions from the map by selecting the blue hexagons with check marks. Ou escolha o ícone de "cesto de lixo" (🗑) ao lado da região no canto direito.Or select the "wastebasket" (🗑) icon next to the region on the right side.

  5. Para salvar suas alterações, escolha OK.To save your changes, select OK.

    Adicionar ou remover o menu de regiões

Em um modo de gravação de região única, não é possível remover a região de gravação.In a single-region write mode, you cannot remove the write region. Você deverá realizar o failover para uma região diferente antes de excluir a região de gravação atual.You must fail over to a different region before you can delete the current write region.

Em um modo de gravação de várias regiões, você poderá adicionar ou remover qualquer região, se você tiver pelo menos uma região.In a multi-region write mode, you can add or remove any region, if you have at least one region.

Azure CLIAzure CLI

$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

# Create an account with 1 region
az cosmosdb create --name $accountName --resource-group $resourceGroupName --locations regionName=westus failoverPriority=0 isZoneRedundant=False

# Add a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName --locations regionName=westus failoverPriority=0 isZoneRedundant=False --locations regionName=EastUS failoverPriority=1 isZoneRedundant=False

# Remove a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName --locations regionName=westus failoverPriority=0 isZoneRedundant=False

PowerShell do AzureAzure PowerShell

# Create an account with 1 region
$resourceGroupName = "myResourceGroup"
$location = "West US"
$accountName = "mycosmosaccount" # must be lower case.

$locations = @( @{ "locationName"="West US"; "failoverPriority"=0 } )
$consistencyPolicy = @{ "defaultConsistencyLevel"="Session" }
$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$locations;
    "consistencyPolicy"=$consistencyPolicy
}
New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Location $location `
    -Name $accountName -PropertyObject $CosmosDBProperties

# Add a region
$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Name $accountName

$locations = @( 
    @{ "locationName"="West US"; "failoverPriority"=0 },
    @{ "locationName"="East Us"; "failoverPriority"=1 } 
)

$account.Properties.locations = $locations
$CosmosDBProperties = $account.Properties

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

# Azure Resource Manager does not wait on the resource update
Write-Host "Confirm region added before continuing..."

# Remove a region
$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Name $accountName

$locations = @( @{ "locationName"="West US"; "failoverPriority"=0 } )

$account.Properties.locations = $locations
$CosmosDBProperties = $account.Properties

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

Configurar várias regiões de gravaçãoConfigure multiple write-regions

Portal do AzureAzure portal

Abra a guia Replicar Dados Globalmente e selecione Habilitar para habilitar gravações de várias regiões.Open the Replicate Data Globally tab and select Enable to enable multi-region writes. Depois que você habilitar gravações de várias regiões, todas as regiões de leitura que você tiver na conta no momento se tornarão regiões de leitura e gravação.After you enable multi-region writes, all the read regions that you currently have on the account will become read and write regions.

Observação

Depois de habilitar gravações de várias regiões, você não poderá desabilitá-las.After you enable multi-region writes, you cannot disable it.

Captura de tela da configuração de vários mestres da conta do Azure Cosmos

Contate o alias askcosmosdb@microsoft.com em caso de outras dúvidas sobre esse recurso.Please reach out to the askcosmosdb@microsoft.com alias for additional questions about this feature.

Azure CLIAzure CLI

$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'
az cosmosdb update --name $accountName --resource-group $resourceGroupName --enable-multiple-write-locations true

PowerShell do AzureAzure PowerShell

# Update an Azure Cosmos account from single to multi-master

$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Name $accountName

$account.Properties.enableMultipleWriteLocations = "true"
$CosmosDBProperties = $account.Properties

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

modelo do Resource ManagerResource Manager template

Uma conta pode ser migrada de mestre único para vários mestres com a implantação do modelo do Resource Manager usado para criar a conta e a configuração enableMultipleWriteLocations: true.An account can be migrated from single-master to multi-master by deploying the Resource Manager template used to create the account and setting enableMultipleWriteLocations: true. O modelo do Azure Resource Manager a seguir é um modelo mínimo possível que implantará uma conta do Azure Cosmos para a API do SQL com uma única região e vários mestres habilitados.The following Azure Resource Manager template is a bare minimum template that will deploy an Azure Cosmos account for SQL API with a single region and multi-master enabled.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "name": {
            "type": "String"
        },
        "location": {
            "type": "String",
            "defaultValue": "[resourceGroup().location]"
        }
    },
    "resources": [
        {
            "type": "Microsoft.DocumentDb/databaseAccounts",
            "kind": "GlobalDocumentDB",
            "name": "[parameters('name')]",
            "apiVersion": "2015-04-08",
            "location": "[parameters('location')]",
            "tags": {},
            "properties": {
                "databaseAccountOfferType": "Standard",
                "consistencyPolicy": { "defaultConsistencyLevel": "Session" },
                "locations": [
                    {
                        "locationName": "[parameters('location')]",
                        "failoverPriority": 0
                    }
                ],
                "enableMultipleWriteLocations": true
            }
        }
    ]
}

Habilitar failover automático a conta do Azure CosmosEnable automatic failover for your Azure Cosmos account

A opção Failover automático permite que o Azure Cosmos DB faça failover para a região com a prioridade mais alta de failover sem nenhuma ação do usuário, caso uma região fique indisponível.The Automatic failover option allows Azure Cosmos DB to failover to the region with the highest failover priority with no user action should a region become unavailable. Quando o failover automático estiver habilitado, a prioridade de região poderá ser modificada.When automatic failover is enabled, region priority can be modified. A conta precisa ter duas ou mais regiões para habilitar o failover automático.Account must have two or more regions to enable automatic failover.

Portal do AzureAzure portal

  1. Na sua conta do Azure Cosmos, abra o painel Replicar dados globalmente.From your Azure Cosmos account, open the Replicate data globally pane.

  2. Escolha Failover Automático na parte superior do painel.At the top of the pane, select Automatic Failover.

    Menu Replicar dados globalmente

  3. No painel Failover Automático, verifique se a opção Habilitar Failover Automático está definida como ATIVADO.On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. Clique em Salvar.Select Save.

    Menu do portal Failover automático

Azure CLIAzure CLI

# Enable automatic failover on an existing account
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

az cosmosdb update --name $accountName --resource-group $resourceGroupName --enable-automatic-failover true

PowerShell do AzureAzure PowerShell

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"

$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName

$account.Properties.enableAutomaticFailover="true";
$CosmosDBProperties = $account.Properties;

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

Definir prioridades de failover para a conta do Azure CosmosSet failover priorities for your Azure Cosmos account

Depois que uma conta do Cosmos for configurada para failover automático, a prioridade de failover para regiões poderá ser alterada.After a Cosmos account is configured for automatic failover, the failover priority for regions can be changed.

Importante

Não é possível modificar a região de gravação (prioridade de failover igual a zero) quando a conta está configurada para failover automático.You cannot modify the write region (failover priority of zero) when the account is configured for automatic failover. Para alterar a região de gravação, é necessário desabilitar o failover automático e fazer um failover manual.To change the write region, you must disable automatic failover and do a manual failover.

Portal do AzureAzure portal

  1. Na sua conta do Azure Cosmos, abra o painel Replicar dados globalmente.From your Azure Cosmos account, open the Replicate data globally pane.

  2. Escolha Failover Automático na parte superior do painel.At the top of the pane, select Automatic Failover.

    Menu Replicar dados globalmente

  3. No painel Failover Automático, verifique se a opção Habilitar Failover Automático está definida como ATIVADO.On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. Para modificar a prioridade de failover, arraste as regiões de leitura nos três pontos à esquerda da linha que aparecem quando o mouse é passado sobre ela.To modify the failover priority, drag the read regions via the three dots on the left side of the row that appear when you hover over them.

  5. Clique em Salvar.Select Save.

    Menu do portal Failover automático

Azure CLIAzure CLI

# Assume region order is initially eastus=0 westus=1 southeastasia=2 on account creation
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

az cosmosdb failover-priority-change --name $accountName --resource-group $resourceGroupName --failover-policies eastus=0 southeastasia=1 westus=2

PowerShell do AzureAzure PowerShell

# Assume account currently has regions with priority: West US = 0, East US = 1, Southeast Asia = 2
$resourceGroupName = "myResourceGroup"
$accountName = "myaccountname"

$failoverPolicies = @(
    @{ "locationName"="West US"; "failoverPriority"=0 },
    @{ "locationName"="Southeast Asia"; "failoverPriority"=1 },
    @{ "locationName"="East US"; "failoverPriority"=2 }
)

Invoke-AzResourceAction -Action failoverPriorityChange `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" `
    -ResourceGroupName $resourceGroupName -Name $accountName -Parameters $failoverPolicies

Fazer um failover manual em uma conta do Azure CosmosPerform manual failover on an Azure Cosmos account

Importante

A conta do Azure Cosmos precisa ser configurada para failover manual para essa operação ser bem-sucedida.The Azure Cosmos account must be configured for manual failover for this operation to succeed.

O processo de execução de um failover manual envolve a alteração da região de gravação da conta (prioridade de failover = 0) para outra região configurada para a conta.The process for performing a manual failover involves changing the account's write region (failover priority = 0) to another region configured for the account.

Observação

As contas de vários mestres não podem ter um failover manual.Multi-master accounts cannot be manually failed over. Para aplicativos que usam o SDK do Azure Cosmos, o SDK detectará quando uma região ficar indisponível e, em seguida, fará o redirecionamento automático para a próxima região mais perto se a API de hospedagem múltipla estiver sendo usada no SDK.For applications using the Azure Cosmos SDK, the SDK will detect when a region becomes unavailable, then redirect automatically to the next closest region if using multi-homing API in the SDK.

Portal do AzureAzure portal

  1. Vá até sua conta do Azure Cosmos e abra o menu Replicar dados globalmente.Go to your Azure Cosmos account, and open the Replicate data globally menu.

  2. Na parte superior do menu, escolha Failover Manual.At the top of the menu, select Manual Failover.

    Menu Replicar dados globalmente

  3. No menu Failover Manual, escolha a nova região de gravação.On the Manual Failover menu, select your new write region. Marque a caixa de seleção para indicar que você entende que essa opção alterará sua região de gravação.Select the check box to indicate that you understand this option changes your write region.

  4. Para disparar o failover, escolha OK.To trigger the failover, select OK.

    Menu do portal de failover manual

Azure CLIAzure CLI

# Assume account currently has regions with priority: eastus=0 westus=1
# Change the priority order to trigger a failover of the write region
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

az cosmosdb update --name $accountName --resource-group $resourceGroupName --locations regionName=westus failoverPriority=0 isZoneRedundant=False --locations regionName=eastus failoverPriority=1 isZoneRedundant=False

PowerShell do AzureAzure PowerShell

# Assume account currently has regions with priority: West US = 0, East US = 1
# Change the priority order to trigger a failover of the write region
$resourceGroupName = "myResourceGroup"
$accountName = "myaccountname"

$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName

$locations = @(
    @{ "locationName"="East US"; "failoverPriority"=0 },
    @{ "locationName"="West US"; "failoverPriority"=1 }
)

$account.Properties.locations=$locations;
$CosmosDBProperties = $account.Properties;

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

Próximas etapasNext steps

Para obter mais informações e exemplos sobre como gerenciar a conta do Azure Cosmos, bem como o banco de dados e contêineres, leia os seguintes artigos:For more information and examples on how to manage the Azure Cosmos account as well as database and containers, read the following articles: