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

  • Artigo

APLICA-SE A: NoSQL

Neste artigo, mostramos como utilizar a portal do Azure para configurar a distribuição global do Azure Cosmos DB e, em seguida, ligar com 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 com 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, é recomendado adicionar regiões com base nos pares de regiões descritos no artigo Replicação entre regiões no Azure: Continuidade do negócio e recuperação após desastre .

Ligar a uma região preferencial com 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 localizações preferenciais. Se o pedido falhar, o cliente irá efetuar a ativação pós-falha da lista para a região seguinte.

O SDK tentará apenas ler a partir das regiões especificadas em localizações preferenciais. Assim, por exemplo, se a conta do Azure Cosmos DB estiver disponível em quatro regiões, mas o cliente apenas especificar duas regiões de leitura (sem escrita) no PreferredLocations, não serão apresentadas leituras fora da região de leitura que não esteja especificada no 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 escrita.

A aplicação pode verificar o ponto final de escrita atual e ler o ponto final escolhido pelo SDK ao verificar duas propriedades e WriteEndpointReadEndpoint, disponíveis na versão 1.8 e superior do SDK. Se a PreferredLocations propriedade não estiver definida, todos os pedidos serão servidos a partir da região de escrita atual.

Se não especificar as localizações preferenciais mas tiver utilizado o setCurrentLocation método , o SDK preenche automaticamente as localizações preferenciais com base na região atual em que o cliente está a ser executado. O SDK ordena as regiões com base na proximidade de uma região à região atual.

SDK .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 da cadeia são formatados de acordo com a coluna nome da região na página Regiões do Azure , sem espaços antes ou depois do primeiro e último caráter, respetivamente.

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 estiver a utilizar o SDK .NET V2, utilize a PreferredLocations propriedade 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);

Em alternativa, pode utilizar a SetCurrentLocation propriedade e permitir que o SDK escolha a localização 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

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.

Segue-se 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 Python

O código seguinte mostra como definir localizações preferenciais com o SDK python:

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 seguinte mostra como definir localizações preferenciais com o SDK Java:

SDK Java V4 (Maven com.azure::azure-cosmos) API Async


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

Pode definir a lista regional preferencial com 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 base de dados tiver sido disponibilizada em várias regiões, os clientes podem consultar a sua disponibilidade ao efetuar um pedido GET neste 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 outros pedidos só de leitura (por exemplo, consultas) podem ir para qualquer ponto final à 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 escrita for alterada após a fase de deteção inicial do cliente, as escritas subsequentes na região de escrita 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.

Passos seguintes

Neste tutorial, fez o seguinte:

  • Configurar a distribuição global com o portal do Azure
  • Configurar a distribuição global com 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

Está a tentar planear a capacidade de uma migração para o Azure Cosmos DB? Pode utilizar informações sobre o cluster de bases de dados existentes para o planeamento de capacidade.