Usare il routing dipendente dai dati per indirizzare una query a un database appropriato

2025-06-16

Routing dipendente dai dati è la possibilità di usare i dati in una query per instradare la richiesta a un database appropriato. Il routing dipendente dai dati costituisce un criterio fondamentale quando si lavora con i database partizionati. È possibile usare il contesto della richiesta per instradarla, soprattutto se la chiave di sharding non fa parte della query. Ogni query o transazione specifica in un'applicazione che usa il routing dipendente dai dati può accedere a un unico database per richiesta. Per gli strumenti elastici del database SQL di Azure, questo routing viene eseguito con la ShardMapManager classe (Java, .NET).

Per l'applicazione non è necessario rilevare le diverse stringhe di connessione o i percorsi dei database associati a diverse sezioni di dati nell'ambiente partizionato. Al contrario, i database di scalabilità orizzontale con gestione mappe partizioni apre le connessioni ai database corretti quando necessario, in base ai dati nella mappa partizioni e al valore della chiave di partizionamento orizzontale che rappresenta la destinazione della richiesta dell'applicazione. La chiave è in genere customer_id, tenant_id, date_key o un altro identificatore specifico che costituisce un parametro fondamentale della richiesta del database.

Per altre informazioni, vedere all'aumento del numero di istanze di SQL Server con il routing dipendente dai dati.

Scaricare la libreria client

Per eseguire il download:

Per la versione Java della libreria, vedere il repository centrale Maven.
Per la versione .NET della libreria, vedere NuGet.

Usare ShardMapManager in un'applicazione di routing dipendente dai dati

Le applicazioni devono creare un'istanza di ShardMapManager durante l'inizializzazione, tramite la chiamata dal factory GetSQLShardMapManager (Java, .NET). In questo esempio vengono inizializzati sia un oggetto ShardMapManager che un oggetto specifico ShardMap che contiene. Questo esempio illustra i metodi GetSqlShardMapManager e GetRangeShardMap (Java o .NET).

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

Usare credenziali con i privilegi più bassi possibile per ottenere la mappa partizioni

Se un'applicazione non gestisce direttamente la mappa partizioni, le credenziali usate nel metodo factory devono disporre solo di autorizzazioni di sola lettura per il database della mappa globale partizioni. Queste credenziali sono in genere diverse da quelle usate per aprire connessioni al gestore delle mappe partizioni. Vedere anche Credenziali usate per accedere alla libreria client dei database elastici.

Chiamare il metodo OpenConnectionForKey

Il ShardMap.OpenConnectionForKey metodo (Java, .NET) restituisce una connessione pronta per l'emissione di comandi al database appropriato in base al valore del key parametro . Le informazioni sullo shard vengono memorizzate nella cache nell'applicazione da ShardMapManager, pertanto queste richieste non comportano in genere una ricerca nel database Global Shard Map.

// Syntax:
public Connection openConnectionForKey(Object key, String connectionString, ConnectionOptions options)

// Syntax:
public SqlConnection OpenConnectionForKey<TKey>(TKey key, string connectionString, ConnectionOptions options)

Il key parametro viene usato come chiave di ricerca nella mappa partizioni per determinare il database appropriato per la richiesta.
connectionString viene usato per passare solo le credenziali dell'utente alla connessione desiderata. In questo connectionString non è incluso alcun nome di database o nome del server perché il metodo determina il database e il server usando .ShardMap
L'oggetto connectionOptions (Java, .NET) deve essere impostato su ConnectionOptions.Validate in un ambiente in cui le mappe di shard possono cambiare e le righe possono essere trasferite ad altri database in seguito a operazioni di suddivisione o unione. Tale convalida prevede una breve query sulla mappa locale partizioni nel database di destinazione (non sulla mappa globale partizioni) prima che la connessione venga fornita all'applicazione.

In caso di esito negativo della convalida in base alla mappa partizioni locale (che indica che la cache non è corretta), il gestore delle mappe partizioni esegue una query sulla mappa partizioni globale per ottenere il nuovo valore corretto per la ricerca, aggiornare la cache e ottenere e restituire la connessione al database appropriato.

Usare ConnectionOptions.None solo quando le modifiche al mapping delle partizioni non sono previste mentre un'applicazione è online. In tal caso, i valori memorizzati nella cache possono essere considerati sempre corretti e la chiamata di convalida round trip aggiuntiva al database di destinazione può essere tranquillamente ignorata. Ciò riduce il traffico del database. Può connectionOptions anche essere impostato tramite un valore in un file di configurazione per indicare se le modifiche di partizionamento orizzontale sono previste o meno durante un periodo di tempo.

In questo esempio viene usato il valore di una chiave CustomerIDinteger usando un ShardMap oggetto denominato 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();
}

Il OpenConnectionForKey metodo restituisce una nuova connessione già aperta al database corretto. Le connessioni utilizzate in questo modo usufruiscono comunque del pool di connessioni.

Il OpenConnectionForKeyAsync metodo (Java, .NET) è disponibile anche se l'applicazione usa la programmazione asincrona.

Integrazione con la gestione degli errori temporanei

Una procedura consigliata nello sviluppo di applicazioni di accesso ai dati nel cloud consiste nel garantire che gli errori temporanei vengano rilevati dall'app e che le operazioni vengano ripetute più volte prima di generare un errore. La gestione degli errori temporanei per le applicazioni cloud è illustrata negli articoli in proposito relativi a Java e .NET.

La gestione degli errori temporanei può coesistere naturalmente con il modello di routing dipendente dai dati. Il requisito principale consiste nel ripetere l'intera richiesta di accesso ai dati, incluso il blocco using che ha ottenuto la connessione di routing dipendente dai dati. L'esempio precedente potrebbe essere riscritto come segue.

Esempio: routing dipendente dai dati con gestione degli errori temporanei

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");
    }
});

I pacchetti necessari per implementare la gestione degli errori temporanei vengono scaricati automaticamente quando si compila l'applicazione esempio dei database elastici.

Coerenza delle transazioni

Le proprietà transazionali sono garantite per tutte le operazioni locali rispetto a una partizione. Ad esempio, le transazioni inviate tramite il routing dipendente dai dati vengono eseguite nell'ambito della partizione di destinazione per la connessione. Al momento, non sono disponibili funzionalità per l'inserimento di più connessioni in una transazione e pertanto non esistono garanzie transazionale per le operazioni eseguite tra partizioni.

Passo successivo

Uso della classe RecoveryManager per risolvere i problemi di mapping delle partizioni

Se non si usano gli strumenti di database elastici, vedere la Guida introduttiva. In caso di domande, usare la pagina Microsoft Q&A per il database SQL, mentre è possibile inserire le richieste di nuove funzionalità, aggiungere nuove idee o votare quelle esistenti nel forum relativo al feedback sul database SQL.