Configurare e usare Collegamento ad Azure Synapse per Azure Cosmos DB
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.
Importante
Il mirroring in Microsoft Fabric è ora disponibile in anteprima per l'API NoSql. Questa funzionalità offre tutte le funzionalità del Collegamento ad Azure Synapse con prestazioni analitiche migliori, la possibilità di unificare il patrimonio di dati con Fabric OneLake e di aprire l'accesso ai dati in OneLake con formato Delta Parquet. Se si sta valutando il Collegamento ad Azure Synapse, è consigliabile provare a eseguire il mirroring per valutare l'idoneità complessiva per l'organizzazione. Per iniziare a eseguire il mirroring, fare clic qui.
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:
- Abilitare Collegamento ad Azure Synapse per gli account Azure Cosmos DB
- Abilitare Collegamento ad Azure Synapse per i contenitori
- Connettere un database Azure Cosmos DB a un'area di lavoro di Azure Synapse
- Eseguire query sull'archivio analitico usando Azure Synapse Analytics
- Migliorare le prestazioni con le procedure consigliate
- Usare il pool SQL serverless di Azure Synapse per analizzare e visualizzare i dati in Power BI
È anche possibile consultare il modulo di formazione su come configurare Collegamento ad Azure Synapse per Azure Cosmos DB.
Abilitare Collegamento ad Azure Synapse per gli account 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. È necessario almeno Operatore per abilitare Collegamento a Synapse nei contenitori o nelle raccolte.
Portale di Azure
Accedere al portale di Azure.
Creare un nuovo account Azure o selezionare un account di Azure Cosmos DB esistente.
Passare all'account Azure Cosmos DB e aprire Collegamento ad Azure Synapse in Integrazioni nel riquadro sinistro.
Seleziona Abilita. Il completamento di questo processo può richiedere da 1 a 5 minuti.
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
.
- Creare un nuovo account Azure Cosmos DB con Collegamento a Synapse abilitato
- Aggiornare un account Azure Cosmos DB per abilitare Collegamento a Synapse
Usare l'interfaccia della riga di comando di Azure per abilitare Collegamento ad Azure Synapse per l'account API Gremlin.
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
.
- Creare un nuovo account Azure Cosmos DB con Collegamento a Synapse abilitato
- Aggiornare un account Azure Cosmos DB per abilitare Collegamento a Synapse
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
Accedere al portale di Azure o a Azure Cosmos DB Explorer.
Passare all'account Azure Cosmos DB e aprire la scheda Esplora dati.
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.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.
Selezionare OK per creare un contenitore di Azure Cosmos DB abilitato per l'archivio analitico.
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
Accedere al portale di Azure o a Azure Cosmos DB Explorer.
Passare all'account Azure Cosmos DB e aprire la scheda Collegamento ad Azure Synapse.
Nella sezione Abilitare Collegamento ad Azure Synapse per i contenitori selezionare il contenitore.
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
.
- Creare o aggiornare una raccolta MongoDB di Azure Cosmos DB
- Creare o aggiornare un contenitore di API SQL di Azure Cosmos DB
Usare l'interfaccia della riga di comando di Azure per abilitare Collegamento ad Azure Synapse per l'account API Graph
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
.
- Creare o aggiornare una raccolta MongoDB di Azure Cosmos DB
- Creare o aggiornare un contenitore di API SQL di Azure Cosmos DB
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
.
CosmosClient cosmosClient = new CosmosClient(
accountEndpoint: "<nosql-account-endpoint>",
tokenCredential: new DefaultAzureCredential()
);
// 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,
};
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.
Procedura consigliata relative a Synapse SQL serverless con Collegamento ad Azure Synapse per Cosmos DB
Usare queste procedure consigliate obbligatorie per le query su SQL serverless.
Introduzione a Collegamento ad Azure Synapse - Esempi
È 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:
- Consultare il modulo di formazione su come configurare Collegamento ad Azure Synapse per Azure Cosmos DB.
- Panoramica dell'archivio analitico di Azure Cosmos DB.
- Domande frequenti su Collegamento ad Azure Synapse per Azure Cosmos DB.
- Apache Spark in Azure Synapse Analytics.
- Supporto del pool SQL serverless in Azure Synapse Analytics.