Usare Azure Cosmos DB per l'output JSON dell'analisi di flussoTarget Azure Cosmos DB for JSON output from Stream Analytics

L'analisi di flusso può usare Azure Cosmos DB per l'output JSON, consentendo l'esecuzione di query di archiviazione dei dati e a bassa latenza su dati JSON non strutturati.Stream Analytics can target Azure Cosmos DB for JSON output, enabling data archiving and low-latency queries on unstructured JSON data. Questo documento descrive alcune procedure consigliate per l'implementazione di questa configurazione.This document covers some best practices for implementing this configuration.

Se non si ha familiarità con Cosmos DB, vedere l'articolo che descrive il percorso di apprendimento di Azure Cosmos DB per un’introduzione.For those who are unfamiliar with Cosmos DB, take a look at Azure Cosmos DB’s learning path to get started.

Nota

Ad oggi, Analisi di flusso di Azure supporta la connessione a Cosmos DB solo tramite l'API DocumentDB (SQL).At this time, Azure Stream Analytics only supports connection to CosmosDB using DocumentDB (SQL) API. Altre API di Azure Cosmos DB non sono ancora supportate.Other Azure Cosmos DB APIs are not yet supported. Se Analisi di flusso di Azure punta agli account Azure Cosmos DB creati con altre API, i dati potrebbero non essere archiviati correttamente.If you point Azure Stream Analytics to the Azure Cosmos DB accounts created with other APIs, the data might not be properly stored.

Nozioni di base di Cosmos DB come destinazione di outputBasics of Cosmos DB as an output target

L'output di Azure Cosmos DB nell'analisi di flusso consente la scrittura dei risultati di elaborazione del flusso come output JSON nelle raccolte di Cosmos DB.The Azure Cosmos DB output in Stream Analytics enables writing your stream processing results as JSON output into your Cosmos DB collection(s). Analisi di flusso non crea raccolte nel database, ma ne richiede la creazione anticipata da parte dell'utente.Stream Analytics does not create collections in your database, instead requiring you to create them upfront. In questo modo, i costi di fatturazione delle raccolte di Cosmos DB sono trasparenti per l'utente ed è possibile ottimizzare direttamente le prestazioni, la coerenza e la capacità delle raccolte usando le API di Cosmos DB.This is so that the billing costs of Cosmos DB collections are transparent to you, and so that you can tune the performance, consistency and capacity of your collections directly using the Cosmos DB APIs. È consigliabile usare un database di Cosmos DB per ogni processo di streaming, per separare in modo logico le raccolte per un processo di streaming.We recommend using one Cosmos DB Database per streaming job to logically separate your collections for a streaming job.

Di seguito sono descritte alcune delle opzioni per le raccolte di Cosmos DB.Some of the Cosmos DB collection options are detailed below.

Ottimizzare coerenza, disponibilità e latenzaTune consistency, availability, and latency

In base ai requisiti dell'applicazione, Cosmos DB consente di ottimizzare il database e le raccolte e di bilanciare coerenza, disponibilità e latenza.To match your application requirements, Cosmos DB allows you to fine tune the database and collections and make trade-offs between consistency, availability and latency. A seconda dei livelli di coerenza di lettura richiesti dello scenario rispetto alla latenza di lettura e scrittura, è possibile scegliere un livello di coerenza per l'account del database.Depending on what levels of read consistency your scenario needs against read and write latency, you can choose a consistency level on your database account. Per impostazione predefinita, Cosmos DB consente anche l'indicizzazione sincrona per ogni operazione CRUD nella raccolta.Also by default, Cosmos DB enables synchronous indexing on each CRUD operation to your collection. Si tratta di un'altra opzione utile per controllare le prestazioni di lettura/scrittura di Cosmos DB.This is another useful option to control the write/read performance in Cosmos DB. Per altre informazioni su questo argomento, vedere l'articolo relativo a come modificare i livelli di coerenza del database e delle query .For further information on this topic, review the change your database and query consistency levels article.

Upsert di Analisi di flussoUpserts from Stream Analytics

L'integrazione dell'analisi di flusso con Cosmos DB consente di inserire o aggiornare i record nella raccolta di Cosmos DB in base a una determinata colonna ID documento.Stream Analytics integration with Cosmos DB allows you to insert or update records in your Cosmos DB collection based on a given Document ID column. Questa implementazione è detta anche upsert.This is also referred to as an Upsert.

Analisi di flusso usa un approccio upsert ottimistico in cui gli aggiornamenti vengono eseguiti solo quando l'inserimento non riesce a causa di un conflitto di ID documento.Stream Analytics utilizes an optimistic Upsert approach, where updates are only done when insert fails due to a Document ID conflict. Questo aggiornamento viene eseguito da Analisi di flusso come PATCH, consentendo aggiornamenti parziali al documento, ad esempio l'aggiunta di nuove proprietà o la sostituzione di una proprietà esistente eseguita in modo incrementale.This update is performed by Stream Analytics as a PATCH, so it enables partial updates to the document, i.e. addition of new properties or replacing an existing property is performed incrementally. Le modifiche ai valori delle proprietà di matrice nel documento JSON comporta la sovrascrittura dell'intera matrice, ovvero non viene eseguito il merge della matrice.Note that changes in the values of array properties in your JSON document result in the entire array getting overwritten, i.e. the array is not merged.

Partizionamento dei dati in Cosmos DBData partitioning in Cosmos DB

Le raccolte partizionate di Cosmos DB sono l'approccio consigliato per il partizionamento dei dati.Cosmos DB partitioned collections are the recommended approach for partitioning your data.

Per le raccolte Cosmos DB singole, l'analisi di flusso consente di partizionare i dati in base ai modelli di query e alle esigenze dell'applicazione in termini di prestazioni.For single Cosmos DB collections, Stream Analytics still allows you to partition your data based on both the query patterns and performance needs of your application. Ogni raccolta può contenere fino a 10 GB di dati (massimo) e attualmente non è possibile aumentare una raccolta o eseguirne l'overflow.Each collection may contain up to 10GB of data (maximum) and currently there is no way to scale up (or overflow) a collection. Per la scalabilità orizzontale, Analisi di flusso consente di scrivere in più raccolte con un determinato prefisso. Vedere i dettagli di utilizzo di seguito.For scaling out, Stream Analytics allows you to write to multiple collections with a given prefix (see usage details below). Per partizionare i record di output, Analisi di flusso usa la strategia coerente del resolver di partizionamento hash basata sulla colonna PartitionKey indicata dall'utente.Stream Analytics uses the consistent Hash Partition Resolver strategy based on the user provided PartitionKey column to partition its output records. Il numero di raccolte con il prefisso specificato all'avvio del processo di streaming viene usato come conteggio delle partizioni di output in cui il processo scrive in parallelo (raccolte di Cosmos DB = partizioni di output).The number of collections with the given prefix at the streaming job’s start time is used as the output partition count, to which the job writes to in parallel (Cosmos DB Collections = Output Partitions). Per una singola raccolta con indicizzazione differita che esegue solo inserimenti, è prevedibile una velocità effettiva di scrittura di 0,4 MB/s.For a single collection with lazy indexing doing only inserts, about 0.4 MB/s write throughput can be expected. L'uso di più raccolte può consentire di ottenere una maggiore capacità e una velocità effettiva più elevata.Using multiple collections can allow you to achieve higher throughput and increased capacity.

Se si prevede di aumentare il numero di partizioni in futuro, potrebbe essere necessario arrestare il processo, ripartizionare i dati dalle raccolte esistenti in nuove raccolte e quindi riavviare il processo di Analisi di flusso.If you intend to increase the partition count in the future, you may need to stop your job, repartition the data from your existing collections into new collections and then restart the Stream Analytics job. Altre informazioni sull'uso di PartitionResolver e sul ripartizionamento, con codice di esempio, saranno incluse in un post di approfondimento.More details on using PartitionResolver and re-partitioning along with sample code, will be included in a follow-up post. Anche l'articolo Partizionamento e scalabilità in Cosmos DB include informazioni dettagliate sull'argomento.The article Partitioning and scaling in Cosmos DB also provides details on this.

Impostazioni di Cosmos DB per l'output JSONCosmos DB settings for JSON output

La creazione di Cosmos DB come output nell'analisi di flusso genera una richiesta di informazioni, come illustrato di seguito.Creating Cosmos DB as an output in Stream Analytics generates a prompt for information as seen below. Questa sezione fornisce una spiegazione della definizione delle proprietà.This section provides an explanation of the properties definition.

Raccolta partizionataPartitioned Collection Più raccolte a partizione singolaMultiple “Single Partition” collections
documentdb analisi di flusso schermata di output documentdb analisi di flusso schermata di output

Nota

Lo scenario con più raccolte a partizione singola richiede una chiave di partizione ed è una configurazione supportata.The Multiple “Single Partition” collections scenario requires a partition key and is a supported configuration.

  • Alias di output : alias per fare riferimento a questo output nella query ASA.Output Alias – An alias to refer this output in your ASA query
  • Nome account: nome o URI endpoint dell'account Cosmos DB.Account Name – The name or endpoint URI of the Cosmos DB account.
  • Chiave account : chiave di accesso condiviso per l'account Cosmos DB.Account Key – The shared access key for the Cosmos DB account.
  • Database: nome del database Cosmos DB.Database – The Cosmos DB database name.
  • Modello del nome di raccolta: nome della raccolta o modello per le raccolte da usare.Collection Name Pattern – The collection name or their pattern for the collections to be used. Il formato del nome di raccolta può essere costruito utilizzando il token {partizione} facoltativo, dove le partizioni iniziano da 0.The collection name format can be constructed using the optional {partition} token, where partitions start from 0. Di seguito sono riportati input di esempio validi:Following are sample valid inputs:
    1) MyCollection: deve essere presente una raccolta denominata "MyCollection".1) MyCollection – One collection named “MyCollection” must exist.
    2) MyCollection{partizione}: devono essere presenti le raccolte "MyCollection0", "MyCollection1", "MyCollection2" e così via.2) MyCollection{partition} – Such collections must exist– "MyCollection0”, “MyCollection1”, “MyCollection2” and so on.
  • Chiave di partizione: valore facoltativo.Partition Key – Optional. È necessario solo se si usa un token {partition} nel modello del nome di raccolta.This is only needed if you are using a {partition} token in your collection name pattern. Il nome del campo negli eventi di output utilizzato per specificare la chiave per il partizionamento di output nelle raccolte.The name of the field in output events used to specify the key for partitioning output across collections. Per l'output di una singola raccolta si può usare qualsiasi colonna di output arbitraria, ad esempio PartitionId.For single collection output, any arbitrary output column can be used e.g. PartitionId.
  • ID documento : valore facoltativo.Document ID – Optional. Il nome del campo negli eventi di output usato per specificare la chiave primaria su cui si basano le operazioni di inserimento o aggiornamento.The name of the field in output events used to specify the primary key on which insert or update operations are based.