Configurare e usare Collegamento ad Azure Synapse per Azure Cosmos DB

  • Articolo

SI APPLICA A: NoSQL MongoDB Gremlin

Collegamento ad Azure Synapse per Azure Cosmos DB è una funzionalità HTAP (Hybrid Transactional and Analytical Processing) nativa del cloud che consente di eseguire analisi quasi in tempo reale su dati operativi in Azure Cosmos DB. Collegamento a Synapse crea una stretta integrazione tra Azure Cosmos DB e Azure Synapse Analytics.

Collegamento ad Azure Synapse è disponibile per gli account API SQL di Azure Cosmos DB o API di Azure Cosmos DB per Mongo DB. Ed è disponibile in anteprima per l'API Gremlin, con attivazione tramite comandi dell'interfaccia della riga di comando. Per eseguire query analitiche con Collegamento ad Azure Synapse per Azure Cosmos DB, seguire questa procedura:

È anche possibile consultare il modulo di formazione su come configurare Collegamento ad Azure Synapse per Azure Cosmos DB.

Il primo passaggio per usare Collegamento a Synapse consiste nell'abilitarlo per l'account del database Azure Cosmos DB.

Nota

Se si vogliono usare chiavi gestite dal cliente con Collegamento ad Azure Synapse, è necessario configurare l'identità gestita dell'account nei criteri di accesso di Azure Key Vault prima di abilitare Collegamento a Synapse nell'account. Per altre informazioni, vedere come configurare le chiavi gestite dal cliente usando le identità gestite dell'account Azure Cosmos DB.

Nota

Se si vuole usare lo schema di massima fedeltà per gli account API per NoSQL, non è possibile usare il portale di Azure per abilitare Collegamento a Synapse. Questa opzione non può essere cambiata dopo l'abilitazione di Collegamento a Synapse nell'account e per impostarla è necessario usare l'interfaccia della riga di comando di Azure o PowerShell. Per altre informazioni, vedere la documentazione sulla rappresentazione dello schema dell'archivio analitico.

Nota

Per abilitare Collegamento a Synapse a livello di account, è necessario il ruolo Collaboratore. Inoltre, per abilitare Collegamento a Synapse in contenitori o raccolte, è necessario almeno il ruolo Operatore.

Azure portal

  1. Accedere al portale di Azure.

  2. Creare un nuovo account Azure o selezionare un account di Azure Cosmos DB esistente.

  3. Passare all'account Azure Cosmos DB e aprire Collegamento ad Azure Synapse in Integrazioni nel riquadro sinistro.

  4. Seleziona Abilita. Il completamento di questo processo può richiedere da 1 a 5 minuti.

    Screenshot showing how to enable Synapse Link feature.

  5. L'account è ora abilitato per l'uso di Collegamento a Synapse. Vedere quindi come creare contenitori abilitati per l'archivio analitico per iniziare automaticamente a replicare i dati operativi dall'archivio transazionale all'archivio analitico.

Nota

L'attivazione di Collegamento a Synapse non attiva automaticamente l'archivio analitico. Dopo aver abilitato Collegamento a Synapse nell'account di Cosmos DB, abilitare l'archivio analitico nei contenitori per iniziare a usare Collegamento a Synapse.

Nota

È anche possibile abilitare Collegamento a Synapse per l'account usando Power BI e il riquadro Collegamento a Synapse nella sezione Integrazioni del menu di spostamento sinistro.

Strumenti da riga di comando

Abilitare Collegamento a Synapse nell'API Azure Cosmos DB per l'account NoSQL o MongoDB usando l'interfaccia della riga di comando di Azure o PowerShell.

Interfaccia della riga di comando di Azure

Usare --enable-analytical-storage true per operazioni di creazione o aggiornamento. È anche necessario scegliere il tipo di schema di rappresentazione. Per gli account API per NoSQL è possibile usare --analytical-storage-schema-type con i valori FullFidelity o WellDefined. Per gli account API per MongoDB, usare sempre --analytical-storage-schema-type FullFidelity.

Collegamento a Synapse per l'API Gremlin è ora disponibile in anteprima. È possibile abilitare Collegamento a Synapse nei grafici nuovi o esistenti usando l'interfaccia della riga di comando di Azure. Usare il comando dell'interfaccia della riga di comando seguente per abilitare Collegamento a Synapse per l'account API Gremlin:

az cosmosdb create --capabilities EnableGremlin --name MyCosmosDBGremlinDatabaseAccount --resource-group MyResourceGroup --enable-analytical-storage true

Per gli account API Gremlin esistenti, sostituire create con update.

PowerShell

Usare EnableAnalyticalStorage true per operazioni di creazione o aggiornamento. È anche necessario scegliere il tipo di schema di rappresentazione. Per gli account API per NoSQL è possibile usare --analytical-storage-schema-type con i valori FullFidelity o WellDefined. Per gli account API per MongoDB, usare sempre -AnalyticalStorageSchemaType FullFidelity.

Modello di Azure Resource Manager

Il modello di Azure Resource Manager crea un account Azure Cosmos DB per l'API SQL abilitato per Collegamento a Synapse. Questo modello crea un account dell'API (SQL) Core in un'area con un contenitore configurato con il TTL dei dati analitici abilitato e un'opzione per usare la velocità effettiva manuale o con scalabilità automatica. Per distribuire questo modello, fare clic su Distribuisci in Azure nella pagina README.

Abilitare Collegamento ad Azure Synapse per i contenitori

Il secondo passaggio consiste nell'abilitare Collegamento a Synapse per i contenitori o le raccolte. A questo scopo, impostare la proprietà analytical TTL su -1 per la conservazione infinita o su un numero intero positivo, ovvero il numero di secondi di conservazione nell'archivio analitico. Questa impostazione può essere cambiata in seguito. Per altre informazioni, vedere l'articolo sui valori di TTL supportati per i dati analitici.

Quando si abilita Collegamento ad Azure Synapse nei contenitori dell'API SQL esistenti, tenere presente quanto segue:

  • Lo stesso isolamento delle prestazioni del processo di sincronizzazione automatica dell'archivio analitico si applica alla sincronizzazione iniziale e non si verifica alcun impatto sulle prestazioni del carico di lavoro OLTP.
  • La sincronizzazione iniziale di un contenitore con il tempo totale dell'archivio analitico varia a seconda del volume di dati e della complessità dei documenti. Questo processo può richiedere da pochi secondi a diversi giorni. Usare il portale di Azure per monitorare lo stato di avanzamento della migrazione.
  • Anche la velocità effettiva del contenitore o dell'account del database influisce sul tempo totale della sincronizzazione iniziale. Anche se le UR/s non vengono usate in questa migrazione, il totale di UR/s disponibile influisce sulle prestazioni del processo. È possibile aumentare temporaneamente le UR disponibili dell'ambiente per velocizzare il processo.
  • Non sarà possibile eseguire query sull'archivio analitico di un contenitore esistente mentre Collegamento a Synapse è abilitato in tale contenitore. Il carico di lavoro OLTP non è interessato ed è possibile continuare a leggere i dati normalmente. I dati inseriti dopo l'inizio della sincronizzazione iniziale verranno uniti nell'archivio analitico dal normale processo di sincronizzazione automatica dell'archivio analitico.

Nota

È ora possibile abilitare Collegamento a Synapse nelle raccolte di API MongoDB esistenti usando l'interfaccia della riga di comando di Azure o PowerShell.

Azure portal

Nuovo contenitore

  1. Accedere al portale di Azure o a Azure Cosmos DB Explorer.

  2. Passare all'account Azure Cosmos DB e aprire la scheda Esplora dati.

  3. Selezionare Nuovo contenitore e immettere un nome per il database, il contenitore, la chiave di partizione e i dettagli relativi alla velocità effettiva. Attivare l'opzione Analytical store (Archivio analitico). Dopo aver abilitato l'archivio analitico, viene creato un contenitore con la proprietà analytical TTL impostata sul valore predefinito -1 (conservazione infinita). Questo archivio analitico conserva tutte le versioni cronologiche dei record che è possibile cambiare in seguito.

    Turn on analytical store for Azure Cosmos DB container

  4. Se in precedenza Collegamento a Synapse non è stato abilitato per questo account, verrà chiesto di farlo perché è un prerequisito per creare un contenitore abilitato per l'archivio analitico. Se richiesto, selezionare Enable Synapse Link (Abilita Collegamento a Synapse). Il completamento di questo processo può richiedere da 1 a 5 minuti.

  5. Selezionare OK per creare un contenitore di Azure Cosmos DB abilitato per l'archivio analitico.

  6. Dopo aver creato il contenitore, verificare che l'archivio analitico sia stato abilitato facendo clic su Impostazioni sotto Documenti in Esplora dati e controllare se l'opzione Durata (TTL) dell'archivio analitico è attivata.

Contenitore esistente

  1. Accedere al portale di Azure o a Azure Cosmos DB Explorer.

  2. Passare all'account Azure Cosmos DB e aprire la scheda Collegamento ad Azure Synapse.

  3. Nella sezione Abilitare Collegamento ad Azure Synapse per i contenitori selezionare il contenitore.

    Screenshot showing how to turn on analytical store for an Azure Cosmos DB existing container.

  4. Dopo aver abilitato il contenitore, verificare che l'archivio analitico sia stato abilitato facendo clic su Impostazioni sotto Documenti in Esplora dati e controllare se l'opzione Durata (TTL) dell'archivio analitico è attivata.

Nota

È anche possibile abilitare Collegamento a Synapse per l'account usando Power BI e il riquadro Collegamento a Synapse nella sezione Integrazioni del menu di spostamento sinistro.

Strumenti da riga di comando

Interfaccia della riga di comando di Azure

Le opzioni seguenti abilitano Collegamento a Synapse in un contenitore tramite l'interfaccia della riga di comando di Azure impostando la proprietà --analytical-storage-ttl.

Collegamento a Synapse per l'API Gremlin è ora disponibile in anteprima. È possibile abilitare Collegamento a Synapse nei grafici nuovi o esistenti usando l'interfaccia della riga di comando di Azure. Usare il comando dell'interfaccia della riga di comando seguente per abilitare Collegamento a Synapse per i grafici dell'API Gremlin:

az cosmosdb gremlin graph create --g MyResourceGroup --a MyCosmosDBGremlinDatabaseAccount --d MyGremlinDB --n MyGraph --analytical-storage-ttl –1

Per i grafici esistenti, sostituire create con update.

PowerShell

Le opzioni seguenti abilitano Collegamento a Synapse in un contenitore tramite l'interfaccia della riga di comando di Azure impostando la proprietà -AnalyticalStorageTtl.

SDK per Azure Cosmos DB - Solo API SQL

.NET SDK

Il codice .NET seguente crea un contenitore abilitato per Collegamento a Synapse impostando la proprietà AnalyticalStoreTimeToLiveInSeconds. Per aggiornare un contenitore esistente, usare il metodo Container.ReplaceContainerAsync.

// Create a container with a partition key, and analytical TTL configured to -1 (infinite retention)
ContainerProperties properties = new ContainerProperties()
{
    Id = "myContainerId",
    PartitionKeyPath = "/id",
    AnalyticalStoreTimeToLiveInSeconds = -1,
};
CosmosClient cosmosClient = new CosmosClient("myConnectionString");
await cosmosClient.GetDatabase("myDatabase").CreateContainerAsync(properties);

Java v4 SDK

Il codice Java seguente crea un contenitore abilitato per Collegamento a Synapse impostando la proprietà setAnalyticalStoreTimeToLiveInSeconds. Per aggiornare un contenitore esistente, usare la classe container.replace.

// Create a container with a partition key and  analytical TTL configured to  -1 (infinite retention) 
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");

containerProperties.setAnalyticalStoreTimeToLiveInSeconds(-1);

container = database.createContainerIfNotExists(containerProperties, 400).block().getContainer();

Python V4 SDK

Il codice Python seguente crea un contenitore abilitato per Collegamento a Synapse impostando la proprietà analytical_storage_ttl. Per aggiornare un contenitore esistente, usare il metodo replace_container.

# Client
client = cosmos_client.CosmosClient(HOST,  KEY )

# Database client
try:
    db = client.create_database(DATABASE)

except exceptions.CosmosResourceExistsError:
    db = client.get_database_client(DATABASE)

# Creating the container with analytical store enabled
try:
    container = db.create_container(
        id=CONTAINER,
        partition_key=PartitionKey(path='/id', kind='Hash'),analytical_storage_ttl=-1
    )
    properties = container.read()
    print('Container with id \'{0}\' created'.format(container.id))
    print('Partition Key - \'{0}\''.format(properties['partitionKey']))

except exceptions.CosmosResourceExistsError:
    print('A container with already exists')

Connettersi a un'area di lavoro di Synapse

Usare le istruzioni riportate in Connettersi a Collegamento ad Azure Synapse per accedere a un database Azure Cosmos DB da Azure Synapse Analytics Studio con Collegamento ad Azure Synapse.

Eseguire query sull'archivio analitico usando Azure Synapse Analytics

Eseguire query sull'archivio analitico usando Apache Spark per Azure Synapse Analytics

Usare le istruzioni riportate nell'articolo Eseguire query sull'archivio analitico di Azure Cosmos DB usando Spark 3 per eseguire query con Synapse Spark 3. Questo articolo include alcuni esempi su come interagire con l'archivio analitico dai movimenti di Synapse. Questi movimenti sono visibili quando si fa clic con il pulsante destro del mouse su un contenitore. Con i movimenti è possibile generare rapidamente il codice e modificarlo in base alle esigenze. Sono inoltre perfetti per l'individuazione dei dati con un singolo clic.

Per l'integrazione di Spark 2, usare l'istruzione riportata nell'articolo Eseguire query sull'archivio analitico di Azure Cosmos DB query usando Spark 2.

Eseguire query sull'archivio analitico usando un pool SQL serverless in Azure Synapse Analytics

Il pool SQL serverless consente di eseguire query e analizzare i dati nei contenitori di Azure Cosmos DB abilitati con Collegamento ad Azure Synapse. È possibile analizzare i dati near real-time senza effetti sulle prestazioni dei carichi di lavoro transazionali. Offre una sintassi T-SQL familiare per eseguire query sui dati dell'archivio analitico e la connettività integrata a un'ampia gamma di strumenti di query di BI e ad hoc tramite l'interfaccia T-SQL. Per altre informazioni, vedere l'articolo Eseguire query sull'archivio analitico usando un pool SQL serverless.

Usare un pool SQL serverless per analizzare e visualizzare i dati in Power BI

È possibile usare l'esperienza di BI integrata nel portale di Azure Cosmos DB per creare dashboard di BI usando Collegamento a Synapse con pochi clic. Per altre informazioni, vedere come creare dashboard di BI usando Collegamento a Synapse. Questa esperienza integrata creerà semplici viste T-SQL nei pool SQL serverless di Synapse per i contenitori di Azure Cosmos DB. È possibile creare dashboard di BI su queste viste, che eseguiranno query sui contenitori di Azure Cosmos DB in tempo reale, usando DirectQuery, rispecchiando le modifiche più recenti apportate ai dati. Non vi è alcun impatto sulle prestazioni o sui costi per i carichi di lavoro transazionali e nessuna complessità nella gestione delle pipeline ETL.

Per usare viste T-SQL avanzate con join tra i contenitori o creare dashboard di Power BI in modalità di importazione, vedere Usare un pool SQL serverless per analizzare i dati di Azure Cosmos DB con Collegamento a Synapse.

Migliorare le prestazioni con le procedure consigliate

Partizionamento personalizzato

Il partizionamento personalizzato consente di partizionare i dati dell'archivio analitico nei campi comunemente usati come filtri nelle query analitiche, con un conseguente miglioramento delle prestazioni delle query. Per altre informazioni, vedere gli articoli Introduzione al partizionamento personalizzato e Come configurare il partizionamento personalizzato.

Usare queste procedure consigliate obbligatorie per le query su SQL serverless.

È possibile trovare esempi per iniziare a usare Collegamento ad Azure Synapse in GitHub. Questi esempi presentano soluzioni end-to-end con scenari IoT e Retail. È anche possibile trovare gli esempi corrispondenti ad Azure Cosmos DB for MongoDB nello stesso repository nella cartella MongoDB.

Passaggi successivi

Per altre informazioni, vedere la documentazione seguente: