Partilhar via

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

  • Artigo

APLICA-SE A: NoSQL

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

Este artigo abrange as seguintes tarefas:

  • Configurar a distribuição global com o portal do Azure
  • Configurar a distribuição global usando a API para NoSQLs

Adicionar regiões de base de dados globais com o Portal do Azure

O Azure Cosmos DB está disponível em todas as regiões do Azure em todo o mundo. Depois de selecionar o nível de consistência predefinido para a sua conta de base de dados, pode associar uma ou mais regiões (dependendo da sua escolha do nível de consistência predefinido e das suas necessidades de distribuição global).

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

  2. Na página Azure Cosmos DB, selecione a conta de base de dados a modificar.

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

  4. Na página Replicar dados globalmente, selecione as regiões a adicionar ou remover, clicando em regiões do mapa e, em seguida, clique em Guardar. Existe um custo para a adição de regiões, consulte a página de preços ou o artigo Distribuir dados globalmente com o Azure Cosmos DB para obter mais informações.

    Clicar em regiões do mapa para adicioná-las ou removê-las

Depois de adicionar uma segunda região, a opção Ativação Pós-falha Manual fica ativada na página Replicar dados globalmente no portal. Pode utilizar esta opção para testar o processo de ativação pós-falha ou alterar a região de escrita principal. Depois de adicionar uma terceira região, a opção Prioridades da Ativação Pós-falha fica ativada na mesma página, para que possa alterar a ordem de ativação pós-falha para as leituras.

Selecionar regiões globais de bases de dados

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

  1. Proporcionar acesso de latência baixa aos dados pelos utilizadores finais, independentemente da respetiva localização em todo o mundo
  2. Adicionar resiliência regional para continuidade empresarial e recuperação após desastre (BCDR)

Para proporcionar latência baixa aos utilizadores finais, recomenda-se que implemente a aplicação e o Azure Cosmos DB nas regiões que correspondem àquelas onde os utilizadores da aplicação estão localizados.

Para BCDR, é recomendável adicionar regiões com base nos pares de regiões descritos no artigo Replicação entre regiões no Azure: continuidade de negócios e recuperação de desastres.

Conectando-se a uma região preferencial usando a API para NoSQL

Para tirar o máximo partido da distribuição global, as aplicações cliente podem especificar a lista de preferência ordenada de regiões a utilizar nas operações de documentos. Com base na configuração da conta do Azure Cosmos DB, disponibilidade regional atual e lista de preferência especificada, o SDK SQL selecionará o ponto final ideal para efetuar operações de escrita e leitura.

Esta lista de preferência é especificada ao inicializar uma ligação com os SDKs SQL. Os SDKs aceitam um parâmetro PreferredLocations opcional que é uma lista ordenada de regiões do Azure.

O SDK enviará automaticamente todas as escritas para a região de escrita atual. Todas as leituras serão enviadas para a primeira região disponível na lista de locais preferidos. Se a solicitação falhar, o cliente fará o faildown da lista para a próxima região.

O SDK só tentará ler a partir das regiões especificadas nos locais preferidos. Assim, por exemplo, 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 gravação) dentro do PreferredLocations, nenhuma leitura será atendida fora da região de leitura não especificada em PreferredLocations. Se as regiões de leitura especificadas na PreferredLocations lista não estiverem disponíveis, as leituras serão servidas fora da região de gravação.

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

Se você não especificar os locais preferenciais, mas usar o setCurrentLocation método, o SDK preencherá automaticamente os locais preferidos 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 com a região atual.

SDK do .NET

O SDK pode ser utilizado sem quaisquer alterações de código. Neste caso, o SDK direciona automaticamente as leituras e as escritas para a região de escrita atual.

Na versão 1.8 e posterior do SDK .NET, o parâmetro ConnectionPolicy do construtor DocumentClient tem uma propriedade denominada Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Esta propriedade é do tipo de Coleção <string> 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 ou depois do primeiro e do último caractere, respectivamente.

Os pontos finais de escrita e leitura atuais estão disponíveis em DocumentClient.WriteEndpoint e DocumentClient.ReadEndpoint, respetivamente.

Nota

Os URLs para os pontos finais não devem ser considerados como constantes de longa duração. O serviço pode atualizá-los em qualquer momento. O SDK processa esta alteração automaticamente.

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

// 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 SetCurrentLocation propriedade e deixar o SDK escolher o local preferido 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

Nota

Os URLs para os pontos finais não devem ser considerados como constantes de longa duração. O serviço pode atualizá-los em qualquer momento. O SDK processará esta alteração automaticamente.

Abaixo está 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 } });

Python SDK

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

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

Java V4 SDK

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

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


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 Spark 3

Você pode 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

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

O serviço devolverá uma lista de regiões e os URIs de ponto final correspondentes do Azure Cosmos DB para as réplicas. A região de escrita atual será indicada na resposta. Em seguida, o cliente pode selecionar o ponto final adequado para obter todos os pedidos da API REST da seguinte forma.

Resposta de exemplo

{
    "_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
}
  • Todos os pedidos PUT, POST e DELETE têm de ir para o URI de escrita indicado
  • Todos os GETs e outras solicitações somente leitura (por exemplo, consultas) podem ir para qualquer ponto de extremidade da escolha do cliente

Os pedidos de escrita para regiões só de leitura falharão com o código de erro HTTP 403 ("Proibido").

Se a região de gravação mudar após a 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"). Em seguida, o cliente deve obter novamente a lista de regiões para obter a região de escrita atualizada.

Já está, isto conclui este tutorial. Pode saber como gerir a consistência da sua conta replicada globalmente ao ler Níveis de consistência no Azure Cosmos DB. Para obter mais informações sobre como funciona a replicação de base de dados global no Azure Cosmos DB, veja Distribuir dados globalmente com o Azure Cosmos DB.

Próximos passos

Neste tutorial, fez o seguinte:

  • Configurar a distribuição global com o portal do Azure
  • Configurar a distribuição global usando a API para NoSQLs

Agora, pode avançar para o próximo tutorial para saber como desenvolver localmente com o emulador local do Azure Cosmos DB.

Desenvolver localmente com o emulador

Tentando fazer o planejamento de capacidade para uma migração para o Azure Cosmos DB? Você pode usar informações sobre seu cluster de banco de dados existente para planejamento de capacidade.