Tutorial: Configurar a distribuição global usando o Azure Cosmos DB for NoSQL
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).
No Portal do Azure, na barra esquerda, clique em BD Cosmos do Azure.
Na página do Azure Cosmos DB, selecione a conta do banco de dados a ser modificada.
Na página da conta, clique em Replicar dados globalmente no menu.
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.
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:
- Fornecimento de acesso a dados de baixa latência para os usuários finais, independentemente de onde estejam localizados em todo o mundo
- 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 sã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);
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,
credential,
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);
ConnectionPolicy connectionPolicy = new ConnectionPolicy();
connectionPolicy.SetCurrentLocation("West US 2"); /
// initialize connection
DocumentClient docClient = new DocumentClient(
accountEndPoint,
credential,
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, aadCredentials: tokenCredential, 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, credential=token_credential, connectionPolicy)
SDK do Java v4
O código a seguir mostra como definir locais preferenciais usando o SDK do Java:
ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");
CosmosAsyncClient client =
new CosmosClientBuilder()
.endpoint(HOST)
.credential(tokenCredential)
.preferredRegions(preferredRegions)
.contentResponseOnWriteEnabled(true)
.buildAsyncClient();
Conector do Spark 3
Você pode definir a lista regional preferida usando a spark.cosmos.preferredRegionsList
configuração, por exemplo:
val sparkConnectorConfig = Map(
"spark.cosmos.accountEndpoint" -> cosmosEndpoint,
"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 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.
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