Tutorial: configurar a distribuição global do Azure Cosmos DB usando a API do NoSQL

  • Artigo

APLICA-SE A: NoSQL

Neste artigo, mostraremos como usar o portal do Azure para configurar a distribuição global do Azure Cosmos DB e depois se conectar usando a API do NoSQL.

Este artigo aborda as seguintes tarefas:

  • Configurar a distribuição global usando o Portal do Azure
  • Configurar a distribuição global usando a API de NoSQLs

Adicionar regiões de banco de dados globais usando o Portal do Azure

O Azure Cosmos DB está disponível em todas as regiões do Azure pelo mundo. Após a seleção do nível de consistência padrão para sua conta de banco de dados, você pode associar uma ou mais regiões (dependendo da sua escolha do nível de consistência padrão e das necessidades de distribuição global).

  1. No Portal do Azure, na barra esquerda, clique em BD Cosmos do Azure.

  2. Na página do Azure Cosmos DB, selecione a conta do banco de dados a ser modificada.

  3. Na página da conta, clique em Replicar dados globalmente no menu.

  4. Na página Replicar dados globalmente, clicando nas regiões no mapa, selecione aquelas a serem adicionadas ou removidas e clique em Salvar. Há um custo para adicionar regiões. Veja a página de preços ou o artigo Distribuir dados globalmente com o Azure Cosmos DB para obter mais informações.

    Clicar nas regiões no mapa para adicioná-las ou removê-las

Depois de adicionar uma segunda região, a opção Failover Manual é habilitada na página Replicar dados globalmente no portal. Você pode usar essa opção para testar o processo de failover ou alterar a região de gravação principal. Depois de adicionar uma terceira região, a opção Prioridades de Failover é habilitada na mesma página para que você possa alterar a ordem de failover das leituras.

Selecionar regiões de bancos de dados globais

Há dois cenários comuns para configurar duas ou mais regiões:

  1. Fornecimento de acesso a dados de baixa latência para os usuários finais, independentemente de onde estejam localizados em todo o mundo
  2. Adição de resiliência regional para continuidade dos negócios e recuperação de desastres (BCDR)

Para oferecer baixa latência para os usuários finais, é recomendável implantar o aplicativo e o Azure Cosmos DB nas regiões que correspondem aos locais em que os usuários do aplicativo estão localizados.

Para o BCDR, é recomendável adicionar regiões com base nos pares de regiões descritos no artigo Continuidade dos negócios e recuperação de desastre (BCDR): Regiões Emparelhadas do Azure.

Conectar-se a uma região preferencial usando a API do NoSQL

Para aproveitar a distribuição global, os aplicativos cliente podem especificar a lista de preferências ordenadas de regiões a serem usadas para executar operações de documento. Com base na configuração da conta do Azure Cosmos DB, na disponibilidade regional atual e na lista de preferências especificada, o ponto de extremidade mais adequado será escolhido pelo SDK do SQL para executar operações de gravação e leitura.

Essa lista de preferências é especificada ao inicializar uma conexão usando os SDKs do SQL. Os SDKs aceitam um parâmetro opcional PreferredLocations, que é uma lista ordenada de regiões do Azure.

O SDK enviará automaticamente todas as gravações para a região de gravação atual. Todas as leituras serão enviadas para a primeira região disponível na lista de locais preferenciais. Se a solicitação falhar, o cliente não fará o envio para a próxima região da lista.

O SDK tentará fazer a leitura apenas das regiões especificadas nos locais preferenciais. Assim, se a conta do Azure Cosmos DB estiver disponível em quatro regiões, mas o cliente especificar apenas duas regiões de leitura (não de gravação) em PreferredLocations, não será feita nenhuma leitura nas regiões não especificadas em PreferredLocations. Se as regiões de leitura especificadas na lista PreferredLocations não estiverem disponíveis, as leituras serão feitas na região de gravação.

O aplicativo pode verificar o ponto de extremidade de gravação e o ponto de extremidade de leitura atuais escolhidos pelo SDK marcando duas propriedades, WriteEndpoint e ReadEndpoint, disponíveis no SDK versão 1.8 e posterior. Se a propriedade PreferredLocations não estiver definida, todas as solicitações serão atendidas na região de gravação atual.

Se você não especificar os locais preferenciais, mas tiver usado o método setCurrentLocation, o SDK preencherá automaticamente os locais preferenciais com base na região atual em que o cliente está sendo executado. O SDK ordena as regiões com base na proximidade de uma região à região atual.

SDK .NET

O SDK pode ser usado sem qualquer mudança de código. Nesse caso, o SDK direciona automaticamente as leituras e gravações para a região de gravação atual.

Na versão 1.8 e posteriores do SDK para .NET, o parâmetro ConnectionPolicy do construtor DocumentClient tem uma propriedade chamada Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Essa propriedade é do tipo <string> de Coleção e deve conter uma lista de nomes de região. Os valores de cadeia de caracteres são formatados de acordo com a coluna de nome da região na página Regiões do Azure, sem espaços antes do primeiro caractere nem depois do último.

Os pontos de extremidade atuais de gravação e leitura estão disponíveis em DocumentClient.WriteEndpoint e DocumentClient.ReadEndpoint, respectivamente.

Observação

As URLs para os pontos de extremidade não devem ser consideradas como constantes de vida longa. O serviço pode atualizá-las a qualquer momento. O SDK lida com essa alteração automaticamente.

Se você estiver usando o SDK do .NET V2, use a propriedade PreferredLocations para definir a região preferencial.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

//Setting read region selection preference
connectionPolicy.PreferredLocations.Add(LocationNames.WestUS); // first preference
connectionPolicy.PreferredLocations.Add(LocationNames.EastUS); // second preference
connectionPolicy.PreferredLocations.Add(LocationNames.NorthEurope); // third preference

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    accountKey,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

Como alternativa, você pode usar a propriedade SetCurrentLocation e permitir que o SDK escolha o local preferencial com base na proximidade.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

connectionPolicy.SetCurrentLocation("West US 2"); /

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    accountKey,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

Node.js/JavaScript

Observação

As URLs para os pontos de extremidade não devem ser consideradas como constantes de vida longa. O serviço pode atualizá-las a qualquer momento. O SDK tratará dessa mudança automaticamente.

Veja abaixo um exemplo de código para Node.js/JavaScript.

// Setting read region selection preference, in the following order -
// 1 - West US
// 2 - East US
// 3 - North Europe
const preferredLocations = ['West US', 'East US', 'North Europe'];

// initialize the connection
const client = new CosmosClient{ endpoint, key, connectionPolicy: { preferredLocations } });

SDK do Python

O código a seguir mostra como definir locais preferenciais usando o SDK do Python:

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, {'masterKey': MASTER_KEY}, connectionPolicy)

SDK do Java v4

O código a seguir mostra como definir locais preferenciais usando o SDK do Java:

API assíncrona do SDK do Java V4 (Maven com.azure::azure-cosmos)


ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

Conector do Spark 3

É possível definir a lista regional preferida usando a spark.cosmos.preferredRegionsListconfiguração, por exemplo:

val sparkConnectorConfig = Map(
  "spark.cosmos.accountEndpoint" -> cosmosEndpoint,
  "spark.cosmos.accountKey" -> cosmosMasterKey,
  "spark.cosmos.preferredRegionsList" -> "[West US, East US, North Europe]"
  // other settings
)

REST

Assim que uma conta de banco de dados tiver sido disponibilizada em várias regiões, os clientes poderão consultar a disponibilidade dela executando uma solicitação GET neste URI: https://{databaseaccount}.documents.azure.com/

O serviço retornará uma lista de regiões e seus URIs de pontos de extremidade do Azure Cosmos DB correspondentes para as réplicas. A região de gravação atual será indicada na resposta. O cliente pode selecionar o ponto de extremidade apropriado para todas as solicitações adicionais de API REST como se segue.

Exemplo de resposta

{
    "_dbs": "//dbs/",
    "media": "//media/",
    "writableLocations": [
        {
            "Name": "West US",
            "DatabaseAccountEndpoint": "https://globaldbexample-westus.documents.azure.com:443/"
        }
    ],
    "readableLocations": [
        {
            "Name": "East US",
            "DatabaseAccountEndpoint": "https://globaldbexample-eastus.documents.azure.com:443/"
        }
    ],
    "MaxMediaStorageUsageInMB": 2048,
    "MediaStorageUsageInMB": 0,
    "ConsistencyPolicy": {
        "defaultConsistencyLevel": "Session",
        "maxStalenessPrefix": 100,
        "maxIntervalInSeconds": 5
    },
    "addresses": "//addresses/",
    "id": "globaldbexample",
    "_rid": "globaldbexample.documents.azure.com",
    "_self": "",
    "_ts": 0,
    "_etag": null
}
  • Todas as solicitações All PUT, POST e DELETE devem ir para o URI de gravação indicado
  • Todas as solicitações GET e outras somente leitura (por exemplo: consultas) podem ir para qualquer ponto de extremidade de escolha do cliente

As solicitações de gravação para regiões somente leitura falharão com o código de erro 403 de HTTP ("Proibido").

Se a região de gravação mudar depois da fase de descoberta inicial do cliente, as gravações subsequentes na região de gravação anterior falharão com o código de erro HTTP 403 ("Proibido"). O cliente deve obter (GET) a lista de regiões novamente para que a região de gravação seja atualizada.

Assim, concluímos este tutorial. Aprenda a gerenciar a consistência de sua conta globalmente replicada lendo Níveis de consistência no Azure Cosmos DB. E para saber mais sobre como a replicação de banco de dados global funciona no Azure Cosmos DB, veja Distribuir dados globalmente com o Azure Cosmos DB.

Próximas etapas

Neste tutorial, você fez o seguinte:

  • Configurar a distribuição global usando o Portal do Azure
  • Configurar a distribuição global usando a API de NoSQLs

Agora você pode prosseguir para o próximo tutorial e aprender a desenvolver localmente usando o emulador local do Azure Cosmos DB.

Desenvolver localmente com o emulador

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.