Configurar a distribuição global do Azure Cosmos DB usando a API do SQLSet up Azure Cosmos DB global distribution using the SQL API

Neste artigo, mostraremos como usar o Portal do Azure para configurar a distribuição global do Azure Cosmos DB e, depois, conectar-se usando a API do SQL.In this article, we show how to use the Azure portal to setup Azure Cosmos DB global distribution and then connect using the SQL API.

Este artigo aborda as seguintes tarefas:This article covers the following tasks:

  • Configurar a distribuição global usando o Portal do AzureConfigure global distribution using the Azure portal
  • Configurar a distribuição global usando as APIs do SQLConfigure global distribution using the SQL APIs

Adicionar regiões de banco de dados globais usando o Portal do AzureAdd global database regions using the Azure portal

O Azure Cosmos DB está disponível em todas as regiões do Azure pelo mundo.Azure Cosmos DB is available in all Azure regions worldwide. 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).After selecting the default consistency level for your database account, you can associate one or more regions (depending on your choice of default consistency level and global distribution needs).

  1. No Portal do Azure, na barra esquerda, clique em BD Cosmos do Azure.In the Azure portal, in the left bar, click Azure Cosmos DB.

  2. Na página do Azure Cosmos DB, selecione a conta do banco de dados a ser modificada.In the Azure Cosmos DB page, select the database account to modify.

  3. Na página da conta, clique em Replicar dados globalmente no menu.In the account page, click Replicate data globally from the 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.In the Replicate data globally page, select the regions to add or remove by clicking regions in the map, and then click Save. 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.There is a cost to adding regions, see the pricing page or the Distribute data globally with Azure Cosmos DB article for more information.

    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.Once you add a second region, the Manual Failover option is enabled on the Replicate data globally page in the portal. Você pode usar essa opção para testar o processo de failover ou alterar a região de gravação principal.You can use this option to test the failover process or change the primary write region. 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.Once you add a third region, the Failover Priorities option is enabled on the same page so that you can change the failover order for reads.

Selecionar regiões de bancos de dados globaisSelecting global database regions

Há dois cenários comuns para configurar duas ou mais regiões:There are two common scenarios for configuring two or more regions:

  1. Fornecimento de acesso a dados de baixa latência para os usuários finais, independentemente de onde estejam localizados em todo o mundoDelivering low-latency access to data to end users no matter where they are located around the globe
  2. Adição de resiliência regional para continuidade dos negócios e recuperação de desastre (BCDR)Adding regional resiliency for business continuity and disaster recovery (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.For delivering low-latency to end users, it is recommended that you deploy both the application and Azure Cosmos DB in the regions that correspond to where the application's users are located.

Para o BCDR, é recomendável adicionar regiões com base nos pares de regiões descritos no artigo BCDR (continuidade dos negócios e recuperação de desastres): Regiões combinadas do Azure.For BCDR, it is recommended to add regions based on the region pairs described in the Business continuity and disaster recovery (BCDR): Azure Paired Regions article.

Conectar-se a uma região preferencial usando a API do SQLConnecting to a preferred region using the SQL API

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.In order to take advantage of global distribution, client applications can specify the ordered preference list of regions to be used to perform document operations. Isso pode ser feito definindo a política de conexão.This can be done by setting the connection policy. 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.Based on the Azure Cosmos DB account configuration, current regional availability and the preference list specified, the most optimal endpoint will be chosen by the SQL SDK to perform write and read operations.

Essa lista de preferências é especificada ao inicializar uma conexão usando os SDKs do SQL.This preference list is specified when initializing a connection using the SQL SDKs. Os SDKs aceitam um parâmetro opcional "PreferredLocations", que é uma lista ordenada de regiões do Azure.The SDKs accept an optional parameter "PreferredLocations" that is an ordered list of Azure regions.

O SDK enviará automaticamente todas as gravações para a região de gravação atual.The SDK will automatically send all writes to the current write region.

Todas as leituras serão enviadas para a primeira região disponível na lista PreferredLocations.All reads will be sent to the first available region in the PreferredLocations list. Se a solicitação falhar, o cliente não fará o envio para a próxima região da lista, e assim por diante.If the request fails, the client will fail down the list to the next region, and so on.

Os SDKs tentarão ler apenas das regiões especificadas em PreferredLocations.The SDKs will only attempt to read from the regions specified in PreferredLocations. Desse modo, se a Conta do Banco de Dados estiver disponível em quatro regiões, por exemplo, mas o cliente especificar apenas duas regiões de leitura (não gravação) em PreferredLocations, nenhuma leitura será atendida fora da região de leitura que não esteja especificada em PreferredLocations.So, for example, if the Database Account is available in four regions, but the client only specifies two read(non-write) regions for PreferredLocations, then no reads will be served out of the read region that is not specified in PreferredLocations. Se as regiões de leitura especificadas em PreferredLocations não estiverem disponíveis, as leituras serão atendidas fora da região de gravação.If the read regions specified in the PreferredLocations are not available, reads will be served out of write region.

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 superiores.The application can verify the current write endpoint and read endpoint chosen by the SDK by checking two properties, WriteEndpoint and ReadEndpoint, available in SDK version 1.8 and above.

Se a propriedade PreferredLocations não estiver definida, todas as solicitações serão atendidas na região de gravação atual.If the PreferredLocations property is not set, all requests will be served from the current write region.

SDK .NET.NET SDK

O SDK pode ser usado sem qualquer mudança de código.The SDK can be used without any code changes. Nesse caso, o SDK direciona automaticamente as leituras e gravações para a região de gravação atual.In this case, the SDK automatically directs both reads and writes to the current write region.

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.In version 1.8 and later of the .NET SDK, the ConnectionPolicy parameter for the DocumentClient constructor has a property called Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Essa propriedade é do tipo <string> de Coleção e deve conter uma lista de nomes de região.This property is of type Collection <string> and should contain a list of region names. Os valores de cadeia de caracteres são formatados de acordo com a coluna Nome da Região na página Regiões do Azure, sem espaços antes nem depois do primeiro e do último caractere, respectivamente.The string values are formatted per the Region Name column on the Azure Regions page, with no spaces before or after the first and last character respectively.

Os pontos de extremidade atuais de gravação e leitura estão disponíveis em DocumentClient.WriteEndpoint e DocumentClient.ReadEndpoint, respectivamente.The current write and read endpoints are available in DocumentClient.WriteEndpoint and DocumentClient.ReadEndpoint respectively.

Observação

As URLs para os pontos de extremidade não devem ser consideradas como constantes de vida longa.The URLs for the endpoints should not be considered as long-lived constants. O serviço pode atualizá-las a qualquer momento.The service may update these at any point. O SDK lida com essa alteração automaticamente.The SDK handles this change automatically.

// 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);

Node.js/JavaScriptNode.js/JavaScript

O SDK pode ser usado sem qualquer mudança de código.The SDK can be used without any code changes. Nesse caso, o SDK direcionará automaticamente as leituras e gravações para a região de gravação atual.In this case, the SDK will automatically direct both reads and writes to the current write region.

Na versão 1.8 e posteriores de cada SDK, o parâmetro ConnectionPolicy do construtor DocumentClient tem uma nova propriedade chamada DocumentClient.ConnectionPolicy.PreferredLocations.In version 1.8 and later of each SDK, the ConnectionPolicy parameter for the DocumentClient constructor a new property called DocumentClient.ConnectionPolicy.PreferredLocations. Esse parâmetro é uma matriz de cadeias de caracteres que usa uma lista de nomes de região.This is parameter is an array of strings that takes a list of region names. Os nomes são formatados de acordo com a coluna Nome da Região na página Regiões do Azure.The names are formatted per the Region Name column in the Azure Regions page. Você também pode usar as constantes predefinidas no objeto de conveniência AzureDocuments.RegionsYou can also use the predefined constants in the convenience object AzureDocuments.Regions

Os pontos de extremidade atuais de gravação e leitura estão disponíveis em DocumentClient.getWriteEndpoint e DocumentClient.getReadEndpoint, respectivamente.The current write and read endpoints are available in DocumentClient.getWriteEndpoint and DocumentClient.getReadEndpoint respectively.

Observação

As URLs para os pontos de extremidade não devem ser consideradas como constantes de vida longa.The URLs for the endpoints should not be considered as long-lived constants. O serviço pode atualizá-las a qualquer momento.The service may update these at any point. O SDK tratará dessa mudança automaticamente.The SDK will handle this change automatically.

Veja abaixo um exemplo de código para Node.js/JavaScript.Below is a code example for Node.js/Javascript.

// Creating a ConnectionPolicy object
var connectionPolicy = new DocumentBase.ConnectionPolicy();

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

// initialize the connection
var client = new DocumentDBClient(host, { masterKey: masterKey }, connectionPolicy);

SDK do PythonPython SDK

O código a seguir mostra como definir locais preferenciais usando o SDK do Python:The following code shows how to set preferred locations by using the Python SDK:


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

SDK do Java V2Java V2 SDK

O código a seguir mostra como definir locais preferenciais usando o SDK do Java:The following code shows how to set preferred locations by using the Java SDK:

ConnectionPolicy policy = new ConnectionPolicy();
policy.setUsingMultipleWriteLocations(true);
policy.setPreferredLocations(Arrays.asList("East US", "West US", "Canada Central"));
AsyncDocumentClient client =
        new AsyncDocumentClient.Builder()
                .withMasterKeyOrResourceToken(this.accountKey)
                .withServiceEndpoint(this.accountEndpoint)
                .withConnectionPolicy(policy)
                .build();

RESTREST

Assim 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 no URI a seguir.Once a database account has been made available in multiple regions, clients can query its availability by performing a GET request on the following 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.The service will return a list of regions and their corresponding Azure Cosmos DB endpoint URIs for the replicas. A região de gravação atual será indicada na resposta.The current write region will be indicated in the response. O cliente pode selecionar o ponto de extremidade apropriado para todas as solicitações adicionais de API REST como se segue.The client can then select the appropriate endpoint for all further REST API requests as follows.

Exemplo de respostaExample response

{
    "_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 indicadoAll PUT, POST and DELETE requests must go to the indicated write URI
  • Todas as solicitações GET e outras somente leitura (por exemplo: consultas) podem ir para qualquer ponto de extremidade de escolha do clienteAll GETs and other read-only requests (for example queries) may go to any endpoint of the client’s choice

As solicitações de gravação para regiões somente leitura falharão com o código de erro 403 de HTTP ("Proibido").Write requests to read-only regions will fail with HTTP error code 403 ("Forbidden").

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").If the write region changes after the client’s initial discovery phase, subsequent writes to the previous write region will fail with HTTP error code 403 ("Forbidden"). O cliente deve obter (GET) a lista de regiões novamente para que a região de gravação seja atualizada.The client should then GET the list of regions again to get the updated write region.

Assim, concluímos este tutorial.That's it, that completes this tutorial. Aprenda a gerenciar a consistência de sua conta globalmente replicada lendo Níveis de consistência no Azure Cosmos DB.You can learn how to manage the consistency of your globally replicated account by reading Consistency levels in 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.And for more information about how global database replication works in Azure Cosmos DB, see Distribute data globally with Azure Cosmos DB.

Próximas etapasNext steps

Neste tutorial, você fez o seguinte:In this tutorial, you've done the following:

  • Configurar a distribuição global usando o Portal do AzureConfigure global distribution using the Azure portal
  • Configurar a distribuição global usando as APIs do SQLConfigure global distribution using the SQL APIs

Agora você pode prosseguir para o próximo tutorial e aprender a desenvolver localmente usando o emulador local do Azure Cosmos DB.You can now proceed to the next tutorial to learn how to develop locally using the Azure Cosmos DB local emulator.