Utilize o encaminhamento dependente de dados para encaminhar uma consulta para uma base de dados apropriadaUse data-dependent routing to route a query to an appropriate database

APLICA-SE A: Base de Dados Azure SQL

O encaminhamento dependente de dados é a capacidade de utilizar os dados numa consulta para encaminhar o pedido para uma base de dados apropriada.Data-dependent routing is the ability to use the data in a query to route the request to an appropriate database. O encaminhamento dependente de dados é um padrão fundamental quando se trabalha com bases de dados de fragmentos.Data-dependent routing is a fundamental pattern when working with sharded databases. O contexto do pedido também pode ser utilizado para encaminhar o pedido, especialmente se a chave de fragmentos não fizer parte da consulta.The request context may also be used to route the request, especially if the sharding key is not part of the query. Cada consulta ou transação específica de uma aplicação utilizando o encaminhamento dependente de dados é restrita ao acesso a uma base de dados por pedido.Each specific query or transaction in an application using data-dependent routing is restricted to accessing one database per request. Para as ferramentas elásticas Azure SQL Database, este encaminhamento é realizado com a classe ShardMapManager (Java, .NET).For the Azure SQL Database elastic tools, this routing is accomplished with the ShardMapManager (Java, .NET) class.

A aplicação não necessita de rastrear várias cadeias de ligação ou localizações DB associadas a diferentes fatias de dados no ambiente desosseado.The application does not need to track various connection strings or DB locations associated with different slices of data in the sharded environment. Em vez disso, o Shard Map Manager abre ligações às bases de dados corretas quando necessário, com base nos dados do mapa de fragmentos e no valor da chave de fragmentos que é o alvo do pedido da aplicação.Instead, the Shard Map Manager opens connections to the correct databases when needed, based on the data in the shard map and the value of the sharding key that is the target of the application’s request. A chave é tipicamente a customer_id, tenant_id, date_key, ou algum outro identificador específico que é um parâmetro fundamental do pedido de base de dados.The key is typically the customer_id, tenant_id, date_key, or some other specific identifier that is a fundamental parameter of the database request.

Para obter mais informações, consulte o Servidor SQL de Escala com Data-Dependent Encaminhamento.For more information, see Scaling Out SQL Server with Data-Dependent Routing.

Descarregue a biblioteca do clienteDownload the client library

Para baixar:To download:

Utilizando um ShardMapManager numa aplicação de encaminhamento dependente de dadosUsing a ShardMapManager in a data-dependent routing application

As aplicações devem instantaneamente o ShardMapManager durante a inicialização, utilizando a chamada de fábrica GetSQLShardMapManager (Java, .NET).Applications should instantiate the ShardMapManager during initialization, using the factory call GetSQLShardMapManager (Java, .NET). Neste exemplo, tanto um ShardMapManager como um ShardMap específico que contém são inicializados.In this example, both a ShardMapManager and a specific ShardMap that it contains are initialized. Este exemplo mostra os métodos GetSqlShardMapManager e GetRangeShardMap(Java, .NET).This example shows the GetSqlShardMapManager and GetRangeShardMap (Java, .NET) methods.

ShardMapManager smm = ShardMapManagerFactory.getSqlShardMapManager(connectionString, ShardMapManagerLoadPolicy.Lazy);
RangeShardMap<int> rangeShardMap = smm.getRangeShardMap(Configuration.getRangeShardMapName(), ShardKeyType.Int32);
ShardMapManager smm = ShardMapManagerFactory.GetSqlShardMapManager(smmConnectionString, ShardMapManagerLoadPolicy.Lazy);
RangeShardMap<int> customerShardMap = smm.GetRangeShardMap<int>("customerMap"); 

Use as credenciais de privilégio mais baixas possíveis para obter o mapa de fragmentosUse lowest privilege credentials possible for getting the shard map

Se uma aplicação não estiver a manipular o mapa de fragmentos em si, as credenciais utilizadas no método de fábrica devem ter permissões apenas de leitura na base de dados Global Shard Map.If an application is not manipulating the shard map itself, the credentials used in the factory method should have read-only permissions on the Global Shard Map database. Estas credenciais são tipicamente diferentes das credenciais usadas para abrir ligações ao gestor de mapas de fragmentos.These credentials are typically different from credentials used to open connections to the shard map manager. Consulte também credenciais utilizadas para aceder à biblioteca de clientes Elastic Database.See also Credentials used to access the Elastic Database client library.

Ligue para o método OpenConnectionForKeyCall the OpenConnectionForKey method

O método ShardMap.OpenConnectionForKey (Java, .NET)devolve uma ligação pronta para emitir comandos na base de dados apropriada com base no valor do parâmetro chave.The ShardMap.OpenConnectionForKey method (Java, .NET) returns a connection ready for issuing commands to the appropriate database based on the value of the key parameter. As informações shard estão em cache na aplicação pelo ShardMapManager, pelo que estes pedidos não envolvem normalmente uma procura de base de dados contra a base de dados Global Shard Map.Shard information is cached in the application by the ShardMapManager, so these requests do not typically involve a database lookup against the Global Shard Map database.

// Syntax:
public Connection openConnectionForKey(Object key, String connectionString, ConnectionOptions options)
// Syntax:
public SqlConnection OpenConnectionForKey<TKey>(TKey key, string connectionString, ConnectionOptions options)
  • O parâmetro-chave é usado como uma chave de procura no mapa de fragmentos para determinar a base de dados apropriada para o pedido.The key parameter is used as a lookup key into the shard map to determine the appropriate database for the request.
  • A ligaçãoStragem é utilizada apenas para passar as credenciais do utilizador para a ligação desejada.The connectionString is used to pass only the user credentials for the desired connection. Nenhum nome de base de dados ou nome do servidor está incluído nesta ligaçãoDese o método determina a base de dados e o servidor utilizando o ShardMap.No database name or server name is included in this connectionString since the method determines the database and server using the ShardMap.
  • As opções de conexão (Java, .NET) devem ser definidas para ConnectionOptions.Valide se um ambiente onde mapas de fragmentos podem mudar e as linhas podem mover-se para outras bases de dados como resultado de operações de divisão ou fusão.The connectionOptions (Java, .NET) should be set to ConnectionOptions.Validate if an environment where shard maps may change and rows may move to other databases as a result of split or merge operations. Esta validação envolve uma breve consulta ao mapa de fragmentos local na base de dados-alvo (não ao mapa global de fragmentos) antes de a ligação ser entregue à aplicação.This validation involves a brief query to the local shard map on the target database (not to the global shard map) before the connection is delivered to the application.

Se a validação contra o mapa de fragmentos local falhar (indicando que a cache está incorreta), o Shard Map Manager consulta o mapa global de fragmentos para obter o novo valor correto para a procura, atualizar a cache e obter e devolver a ligação de base de dados apropriada.If the validation against the local shard map fails (indicating that the cache is incorrect), the Shard Map Manager queries the global shard map to obtain the new correct value for the lookup, update the cache, and obtain and return the appropriate database connection.

Use Opções de Ligação.Nenhuma só quando não são esperadas alterações de mapeamento de fragmentos enquanto uma aplicação estiver online.Use ConnectionOptions.None only when shard mapping changes are not expected while an application is online. Nesse caso, os valores em cache podem ser assumidos como sempre corretos, e a chamada extra de validação de ida e volta para a base de dados-alvo pode ser ignorada com segurança.In that case, the cached values can be assumed to always be correct, and the extra round-trip validation call to the target database can be safely skipped. Isso reduz o tráfego de bases de dados.That reduces database traffic. As perguntas de ligação também podem ser definidas através de um valor num ficheiro de configuração para indicar se são ou não esperadas alterações de fragmentos durante um período de tempo.The connectionOptions may also be set via a value in a configuration file to indicate whether sharding changes are expected or not during a period of time.

Este exemplo utiliza o valor de uma chave de número inteiro CustomerID, utilizando um objeto ShardMap denominado clienteShardMap.This example uses the value of an integer key CustomerID, using a ShardMap object named customerShardMap.

int customerId = 12345;
int productId = 4321;
// Looks up the key in the shard map and opens a connection to the shard
try (Connection conn = shardMap.openConnectionForKey(customerId, Configuration.getCredentialsConnectionString())) {
    // Create a simple command that will insert or update the customer information
    PreparedStatement ps = conn.prepareStatement("UPDATE Sales.Customer SET PersonID = ? WHERE CustomerID = ?");

    ps.setInt(1, productId);
    ps.setInt(2, customerId);
    ps.executeUpdate();
} catch (SQLException e) {
    e.printStackTrace();
}
int customerId = 12345;
int newPersonId = 4321;

// Connect to the shard for that customer ID. No need to call a SqlConnection
// constructor followed by the Open method.
using (SqlConnection conn = customerShardMap.OpenConnectionForKey(customerId, Configuration.GetCredentialsConnectionString(), ConnectionOptions.Validate))
{
    // Execute a simple command.
    SqlCommand cmd = conn.CreateCommand();
    cmd.CommandText = @"UPDATE Sales.Customer
                        SET PersonID = @newPersonID WHERE CustomerID = @customerID";

    cmd.Parameters.AddWithValue("@customerID", customerId);cmd.Parameters.AddWithValue("@newPersonID", newPersonId);
    cmd.ExecuteNonQuery();
}  

O método OpenConnectionForKey devolve uma nova ligação já aberta à base de dados correta.The OpenConnectionForKey method returns a new already-open connection to the correct database. As ligações utilizadas desta forma ainda aproveitam ao máximo a ligação.Connections utilized in this way still take full advantage of connection pooling.

O método OpenConnectionForKeyAsync (Java, .NET)também está disponível se a sua aplicação utilizar a programação assíncronus.The OpenConnectionForKeyAsync method (Java, .NET) is also available if your application makes use asynchronous programming.

Integração com o tratamento transitório de falhasIntegrating with transient fault handling

Uma das melhores práticas no desenvolvimento de aplicações de acesso a dados na nuvem é garantir que as falhas transitórias são apanhadas pela app, e que as operações são novamente experimentadas várias vezes antes de lançar um erro.A best practice in developing data access applications in the cloud is to ensure that transient faults are caught by the app, and that the operations are retried several times before throwing an error. O tratamento transitório de falhas para aplicações em nuvem é discutido no Tratamento transitório de falhas(Java, .NET).Transient fault handling for cloud applications is discussed at Transient Fault Handling (Java, .NET).

O manuseamento de falhas transitórias pode coexistir naturalmente com o padrão de encaminhamento Data-Dependent.Transient fault handling can coexist naturally with the Data-Dependent Routing pattern. O requisito-chave é voltar a tentar todo o pedido de acesso aos dados, incluindo o bloco de utilização que obteve a ligação de encaminhamento dependente de dados.The key requirement is to retry the entire data access request including the using block that obtained the data-dependent routing connection. O exemplo anterior pode ser reescrito da seguinte forma.The preceding example could be rewritten as follows.

Exemplo - encaminhamento dependente de dados com tratamento de falhas transitóriasExample - data-dependent routing with transient fault handling

int customerId = 12345;
int productId = 4321;
try {
    SqlDatabaseUtils.getSqlRetryPolicy().executeAction(() -> {
        // Looks up the key in the shard map and opens a connection to the shard
        try (Connection conn = shardMap.openConnectionForKey(customerId, Configuration.getCredentialsConnectionString())) {
            // Create a simple command that will insert or update the customer information
            PreparedStatement ps = conn.prepareStatement("UPDATE Sales.Customer SET PersonID = ? WHERE CustomerID = ?");

            ps.setInt(1, productId);
            ps.setInt(2, customerId);
            ps.executeUpdate();
        } catch (SQLException e) {
            e.printStackTrace();
        }
    });
} catch (Exception e) {
    throw new StoreException(e.getMessage(), e);
}
int customerId = 12345;
int newPersonId = 4321;

Configuration.SqlRetryPolicy.ExecuteAction(() -> {

    // Connect to the shard for a customer ID.
    using (SqlConnection conn = customerShardMap.OpenConnectionForKey(customerId, Configuration.GetCredentialsConnectionString(), ConnectionOptions.Validate))
    {
        // Execute a simple command
        SqlCommand cmd = conn.CreateCommand();

        cmd.CommandText = @"UPDATE Sales.Customer
                            SET PersonID = @newPersonID
                            WHERE CustomerID = @customerID";

        cmd.Parameters.AddWithValue("@customerID", customerId);
        cmd.Parameters.AddWithValue("@newPersonID", newPersonId);
        cmd.ExecuteNonQuery();

        Console.WriteLine("Update completed");
    }
});

Os pacotes necessários para implementar o manuseamento de falhas transitórias são descarregados automaticamente quando se constrói a aplicação de amostra de base de dados elástica.Packages necessary to implement transient fault handling are downloaded automatically when you build the elastic database sample application.

Consistência transacionalTransactional consistency

As propriedades transacionais são garantidas para todas as operações locais a um fragmento.Transactional properties are guaranteed for all operations local to a shard. Por exemplo, as transações submetidas através de encaminhamento dependente de dados executam no âmbito do fragmento-alvo para a ligação.For example, transactions submitted through data-dependent routing execute within the scope of the target shard for the connection. Neste momento, não existem capacidades para a inscrição de múltiplas ligações numa transação, pelo que não existem garantias transacionais para operações realizadas em fragmentos.At this time, there are no capabilities provided for enlisting multiple connections into a transaction, and therefore there are no transactional guarantees for operations performed across shards.

Passos seguintesNext steps

Para desprender um fragmento, ou para voltar a colocar um fragmento, consulte utilizar a classe RecoveryManager para corrigir problemas de mapa de fragmentos.To detach a shard, or to reattach a shard, see Using the RecoveryManager class to fix shard map problems.

Recursos adicionaisAdditional resources

Ainda não está a usar ferramentas elásticas de base de dados?Not using elastic database tools yet? Consulte o nosso Guia de Início.Check out our Getting Started Guide. Para obter perguntas, contacte-nos no Microsoft Q&Página de perguntas para base de dados SQL e para pedidos de funcionalidades, por favor adicione-as ao fórum de feedback da Base de Dados SQL.For questions, please reach out to us on the Microsoft Q&A question page for SQL Database and for feature requests, please add them to the SQL Database feedback forum.