Diagnosticar e solucionar problemas de disponibilidade dos SDKs do Azure Cosmos DB em ambientes multirregionais
APLICA-SE A: 
NoSQL
Este artigo descreve o comportamento da versão mais recente dos SDKs do Azure Cosmos DB quando você vê um problema de conectividade com uma região específica ou quando ocorre um failover de região.
Todos os SDKs do Azure Cosmos DB oferecem uma opção para personalizar a preferência regional. As seguintes propriedades são usadas em diferentes SDKs:
- A propriedade ConnectionPolicy.PreferredLocations no SDK do .NET V2.
- As propriedades CosmosClientOptions.ApplicationRegion ou CosmosClientOptions.ApplicationPreferredRegions no SDK do .NET V3.
- O método CosmosClientBuilder.preferredRegions no Java V4 SDK.
- O parâmetro CosmosClient.preferred_locations no Python SDK.
- O parâmetro CosmosClientOptions.ConnectionPolicy.preferredLocations no JS SDK.
Quando o SDK é inicializado com uma configuração que especifica a preferência regional, ele primeiro obterá as informações da conta, incluindo as regiões disponíveis, do ponto de extremidade global. Em seguida, ele aplicará uma interseção entre a preferência regional configurada e as regiões disponíveis da conta e usará a ordem na preferência regional para priorizar o resultado.
Se a configuração de preferência regional contiver regiões que não são uma região disponível na conta, os valores serão ignorados. Se essas regiões inválidas forem adicionadas posteriormente à conta, o SDK as usará se elas forem mais altas na configuração de preferência.
| Tipo de conta | Leituras | Escritas |
|---|---|---|
| Região de gravação única | Região preferida com a ordem mais alta | Região primária |
| Várias regiões de gravação | Região preferida com a ordem mais alta | Região preferida com a ordem mais alta |
Se você não definir uma região preferencial, o cliente SDK assumirá como padrão a região primária:
| Tipo de conta | Leituras | Escritas |
|---|---|---|
| Região de gravação única | Região primária | Região primária |
| Várias regiões de gravação | Região primária | Região primária |
Nota
Região primária refere-se à primeira região na lista de regiões de conta do Azure Cosmos DB. Se os valores especificados como preferência regional não corresponderem a nenhuma região existente do Azure, eles serão ignorados. Se eles corresponderem a uma região existente, mas a conta não for replicada para ela, o cliente se conectará à próxima região preferida correspondente ou à região primária.
Aviso
A lógica de failover e disponibilidade descrita neste documento pode ser desabilitada na configuração do cliente, o que não é aconselhado, a menos que o próprio aplicativo do usuário manipule erros de disponibilidade. Este objetivo pode ser atingido através das seguintes medidas:
- Definindo a propriedade ConnectionPolicy.EnableEndpointDiscovery no SDK do .NET V2 como false.
- Definindo a propriedade CosmosClientOptions.LimitToEndpoint no SDK do .NET V3 como true.
- Definindo o método CosmosClientBuilder.endpointDiscoveryEnabled no Java V4 SDK como false.
- Definindo o parâmetro CosmosClient.enable_endpoint_discovery no Python SDK como false.
- Definindo o parâmetro CosmosClientOptions.ConnectionPolicy.enableEndpointDiscovery no JS SDK como false.
Em circunstâncias normais, o cliente SDK se conectará à região preferencial (se uma preferência regional for definida) ou à região primária (se nenhuma preferência for definida), e as operações serão limitadas a essa região, a menos que ocorra qualquer um dos cenários abaixo.
Nesses casos, o cliente que usa o SDK do Azure Cosmos DB expõe logs e inclui as informações de repetição como parte das informações de diagnóstico da operação:
- A propriedade RequestDiagnosticsString em respostas no SDK do .NET V2.
- A propriedade Diagnostics em respostas e exceções no SDK do .NET V3.
- O método getDiagnostics() nas respostas e exceções no SDK Java V4.
Ao determinar a próxima região em ordem de preferência, o cliente SDK usará a lista de regiões da conta, priorizando as regiões preferidas (se houver).
Para obter um detalhe abrangente sobre as garantias de SLA durante esses eventos, consulte os SLAs para disponibilidade.
Remover uma região da conta
Quando você remove uma região de uma conta do Azure Cosmos DB, qualquer cliente SDK que usa ativamente a conta detetará a remoção da região por meio de um código de resposta de back-end. Em seguida, o cliente marca o ponto de extremidade regional como indisponível. O cliente tenta novamente a operação atual e todas as operações futuras são permanentemente encaminhadas para a próxima região em ordem de preferência. Caso a lista de preferências tenha apenas uma entrada (ou estivesse vazia), mas a conta tenha outras regiões disponíveis, ela será encaminhada para a próxima região na lista de contas.
Adicionar uma região a uma conta
A cada 5 minutos, o cliente SDK do Azure Cosmos DB lê a configuração da conta e atualiza as regiões que conhece.
Se você remover uma região e depois adicioná-la novamente à conta, se a região adicionada tiver uma ordem de preferência regional mais alta na configuração do SDK do que a região conectada atual, o SDK voltará a usar essa região permanentemente. Depois que a região adicionada é detetada, todas as solicitações futuras são direcionadas para ela.
Se você configurar o cliente para se conectar preferencialmente a uma região que a conta do Azure Cosmos DB não tem, a região preferencial será ignorada. Se você adicionar essa região posteriormente, o cliente a detetará e alternará permanentemente para essa região.
Failover da região de gravação em uma única conta de região de gravação
Se você iniciar um failover da região de gravação atual, a próxima solicitação de gravação falhará com uma resposta de back-end conhecida. Quando essa resposta for detetada, o cliente consultará a conta para saber a nova região de gravação e continuará a tentar novamente a operação atual e rotear permanentemente todas as operações de gravação futuras para a nova região.
Interrupção regional
Se a conta for uma única região de gravação e a interrupção regional ocorrer durante uma operação de gravação, o comportamento será semelhante a um failover manual. Para solicitações de leitura ou contas de várias regiões de gravação, o comportamento é semelhante à remoção de uma região.
Garantia de consistência da sessão
Ao usar a consistência da sessão, o cliente precisa garantir que possa ler suas próprias gravações. Em contas de região de gravação única em que a preferência de região de leitura é diferente da região de gravação, pode haver casos em que o usuário emite uma gravação e, em seguida, faz uma leitura de uma região local, a região local ainda não recebeu a replicação de dados (restrição de velocidade de luz). Nesses casos, o SDK recebe uma falha específica do serviço na operação de leitura e tenta novamente a leitura na região primária para garantir a consistência da sessão. Para contas com várias regiões de gravação, a mesma semântica de sessão se aplica, mas como há várias regiões de gravação disponíveis, novas tentativas são emitidas usando a lista de regiões preferenciais ou a ordem de regiões da conta.
Problemas transitórios de conectividade no protocolo TCP
Em cenários em que o cliente SDK do Azure Cosmos DB está configurado para usar o protocolo TCP, para uma determinada solicitação, pode haver situações em que as condições de rede estão afetando temporariamente a comunicação com um ponto de extremidade específico. Essas condições de rede temporárias podem aparecer como tempos limite de TCP e erros de serviço indisponível (HTTP 503). Se possível, o cliente tentará novamente a solicitação localmente no mesmo ponto de extremidade por alguns segundos.
Se o usuário configurou uma lista de regiões preferenciais com mais de uma região e o cliente esgotou todas as tentativas locais, ele pode tentar repetir essa única operação na próxima região da lista de preferências. As operações de gravação só podem ser repetidas em outra região se a conta do Azure Cosmos DB tiver várias regiões de gravação habilitadas, enquanto as operações de leitura podem ser repetidas em qualquer região disponível.
Próximos passos
- Analise os SLAs de disponibilidade.
- Usar o SDK do .NET mais recente
- Use o Java SDK mais recente
- Use o SDK Python mais recente
- Usar o SDK do nó mais recente