Uso del supporto del feed delle modifiche in Azure Cosmos DBWorking with the change feed support in Azure Cosmos DB

Azure Cosmos DB è un database con replica a livello globale rapido e flessibile, ideale per le applicazioni IoT, di videogiochi, del settore della vendita al dettaglio e di registrazioni di operazioni.Azure Cosmos DB is a fast and flexible globally replicated database, well-suited for IoT, gaming, retail, and operational logging applications. Uno schema progettuale comune in queste applicazioni prevede l'uso delle modifiche ai dati per avviare azioni aggiuntive.A common design pattern in these applications is to use changes to the data to kick off additional actions. Queste azioni aggiuntive possono essere una delle seguenti:These additional actions could be any of the following:

  • Attivazione di una notifica o di una chiamata a un'API quando un documento viene inserito o modificato.Triggering a notification or a call to an API when a document is inserted or modified.
  • Elaborazione di flussi per IoT o esecuzione di analisi.Stream processing for IoT or performing analytics.
  • Spostamento dei dati aggiuntivi tramite sincronizzazione con una cache, un motore di ricerca o un data warehouse oppure tramite archiviazione dei dati nella risorsa di archiviazione offline sicura.Additional data movement by synchronizing with a cache, search engine, or data warehouse, or archiving data to cold storage.

Il supporto del feed di modifiche in Azure Cosmos DB consente di creare soluzioni efficienti e scalabili per ognuno di questi modelli, come illustrato nell'immagine seguente:The change feed support in Azure Cosmos DB enables you to build efficient and scalable solutions for each of these patterns, as shown in the following image:

Uso del feed delle modifiche di Azure Cosmos DB per agevolare le analisi in tempo reale e gli scenari di calcolo guidati dagli eventi

Nota

Il supporto del feed di modifiche viene fornito per tutti i modelli di dati e contenitori in Azure Cosmos DB.Change feed support is provided for all data models and containers in Azure Cosmos DB. Il feed di modifiche tuttavia viene letto usando il client SQL e serializza gli elementi in formato JSON.However, the change feed is read using the SQL client and serializes items into JSON format. A causa della formattazione JSON, nei client MongoDB i documenti in formato JSON non corrisponderanno al feed di modifiche in formato JSON.Because of the JSON formatting, MongoDB clients will experience a mismatch between BSON formatted documents and the JSON formatted change feed.

Nel video seguente Andrew Liu, Program Manager di Azure Cosmos DB, illustra il funzionamento del feed di modifiche in Azure Cosmos DB.In the following video, Azure Cosmos DB Program Manager Andrew Liu demonstrates how the Azure Cosmos DB change feed works.

Funzionamento del feed di modificheHow does change feed work?

Il supporto del feed di modifiche in Azure Cosmos DB è in ascolto di eventuali modifiche in una raccolta di Azure Cosmos DB.Change feed support in Azure Cosmos DB works by listening to an Azure Cosmos DB collection for any changes. Restituisce quindi l'elenco di documenti cambiati nell'ordine in cui sono stati modificati.It then outputs the sorted list of documents that were changed in the order in which they were modified. Le modifiche sono persistenti, possono essere elaborate in modo asincrono e incrementale e l'output può essere distribuito a uno o più consumer per l'elaborazione parallela.The changes are persisted, can be processed asynchronously and incrementally, and the output can be distributed across one or more consumers for parallel processing.

È possibile leggere il feed di modifiche in tre modi diversi, come verrà illustrato più avanti in questo articolo:You can read the change feed in three different ways, as discussed later in this article:

Il feed di modifiche è disponibile per ogni intervallo di chiavi di partizioni nella raccolta dei documenti ed è quindi possibile distribuirlo a uno o più consumer per l'elaborazione parallela, come illustrato nell'immagine seguente.The change feed is available for each partition key range within the document collection, and thus can be distributed across one or more consumers for parallel processing as shown in the following image.

Elaborazione distribuita del feed delle modifiche di Azure Cosmos DB

Informazioni aggiuntive:Additional details:

  • Il feed di modifiche è abilitato per impostazione predefinita per tutti gli account.Change feed is enabled by default for all accounts.
  • È possibile usare la velocità effettiva con provisioning nell'area di scrittura o in qualsiasi area di lettura per leggere dal feed di modifiche, proprio come ogni altra operazione di Azure Cosmos DB.You can use your provisioned throughput in your write region or any read region to read from the change feed, just like any other Azure Cosmos DB operation.
  • Il feed delle modifiche include le operazioni di aggiunte e aggiornamenti eseguite sui documenti all'interno della raccolta.The change feed includes inserts and update operations made to documents within the collection. È possibile acquisire le eliminazioni impostando un flag "eliminazione temporanea" all'interno dei documenti al posto delle eliminazioni.You can capture deletes by setting a "soft-delete" flag within your documents in place of deletes. In alternativa, è possibile impostare un periodo di scadenza delimitato per i documenti tramite la funzionalità TTL, ad esempio 24 ore, e usare il valore di tale proprietà per acquisire le eliminazioni.Alternatively, you can set a finite expiration period for your documents via the TTL capability, for example, 24 hours and use the value of that property to capture deletes. Con questa soluzione è necessario elaborare le modifiche in un intervallo di tempo minore rispetto al periodo di scadenza TTL.With this solution, you have to process changes within a shorter time interval than the TTL expiration period.
  • Ogni modifica apportata a un documento viene visualizzata una sola volta nel feed delle modifiche e i client gestiscono la logica di checkpoint.Each change to a document appears exactly once in the change feed, and clients manage their checkpointing logic. La libreria del processore del feed delle modifiche fornisce funzionalità di checkpoint automatici e semantica di tipo "at least once".The change feed processor library provides automatic checkpointing and "at least once" semantics.
  • Solo la modifica più recente per un determinato documento viene inclusa nel registro modifiche.Only the most recent change for a given document is included in the change log. Le modifiche intermedie potrebbero non essere disponibili.Intermediate changes may not be available.
  • Il feed delle modifiche è ordinato in base all'ordine di modifica in ciascun valore di chiave della partizione.The change feed is sorted by order of modification within each partition key value. Non esiste alcun ordine garantito tra i valori partition-key.There is no guaranteed order across partition-key values.
  • Le modifiche possono essere sincronizzate da qualsiasi punto nel tempo, in altre parole non è previsto un periodo di conservazione fisso per cui sono disponibili le modifiche.Changes can be synchronized from any point-in-time, that is, there is no fixed data retention period for which changes are available.
  • Le modifiche sono disponibili in blocchi di intervalli di chiavi di partizione.Changes are available in chunks of partition key ranges. Questa funzionalità consente di apportare modifiche da raccolte di grandi dimensioni per poi elaborarle in parallelo da più consumer/server.This capability allows changes from large collections to be processed in parallel by multiple consumers/servers.
  • Le applicazioni possono richiedere più feed di modifiche alla volta nella stessa raccolta.Applications can request multiple change feeds simultaneously on the same collection.
  • È possibile usare ChangeFeedOptions.StartTime per fornire un punto di partenza iniziale, ad esempio per trovare il token di continuazione corrispondente a un'ora specificata.ChangeFeedOptions.StartTime can be used to provide an initial starting point, for example, to find the continuation token corresponding to given clock time. Se si specifica ContinuationToken, questo avrà priorità rispetto ai valori di StartTime e StartFromBeginning.The ContinuationToken, if specified, wins over the StartTime and StartFromBeginning values. La precisione di ChangeFeedOptions.StartTime è circa di 5 secondi.The precision of ChangeFeedOptions.StartTime is ~5 secs.

Casi d'uso e scenariUse cases and scenarios

Il feed di modifiche consente di elaborare con efficienza set di dati di grandi dimensioni con volumi elevati di scritture e rappresenta un'alternativa alla query di un intero set di dati per identificare le modifiche.The change feed enables efficient processing of large datasets with a high volume of writes, and offers an alternative to querying an entire dataset to identify what has changed.

Ad esempio, con un feed di modifiche è possibile eseguire in modo efficiente le operazioni seguenti:For example, with a change feed, you can perform the following tasks efficiently:

  • Aggiornare una cache, un indice di ricerca o un data warehouse con i dati archiviati in Azure Cosmos DB.Update a cache, search index, or a data warehouse with data stored in Azure Cosmos DB.
  • Implementare la suddivisione in livelli e l'archiviazione a livello di applicazione, in altre parole archiviare i dati più usati ("hot data") in Azure Cosmos DB e trasferire quelli meno usati ("cold data") in Archivio BLOB di Azure o Azure Data Lake Store.Implement application-level data tiering and archival, that is, store "hot data" in Azure Cosmos DB, and age out "cold data" to Azure Blob Storage or Azure Data Lake Store.
  • Effettuare migrazioni senza alcun tempo di inattività a un altro account Azure Cosmos DB con uno schema di partizionamento differente.Perform zero down-time migrations to another Azure Cosmos DB account with a different partitioning scheme.
  • Implementare pipeline lambda in Azure con Azure Cosmos DB.Implement lambda pipelines on Azure with Azure Cosmos DB. Azure Cosmos DB offre una soluzione di database scalabile che può gestire sia l'inserimento che le query e implementare architetture lambda con costo totale di proprietà ridotto.Azure Cosmos DB provides a scalable database solution that can handle both ingestion and query, and implement lambda architectures with low TCO.
  • Ricevere e archiviare i dati di eventi da dispositivi, sensori, infrastrutture e applicazioni, per poi elaborarli in tempo reale con analisi di flusso di Azure, Apache Storm o Apache Spark.Receive and store event data from devices, sensors, infrastructure, and applications, and process these events in real time with Azure Stream Analytics, Apache Storm, or Apache Spark.

L'immagine seguente illustra come le pipeline lambda che eseguono sia inserimenti che query con Azure Cosmos DB possono usare il supporto del feed di modifiche:The following image shows how lambda pipelines that both ingest and query using Azure Cosmos DB can use change feed support:

Pipeline lambda basate su Azure Cosmos DB per l'inserimento e le query

Nelle app Web e per dispositivi mobili senza server è anche possibile tenere traccia di eventi come le modifiche al profilo, alle preferenze o alle località dei clienti per attivare determinate azioni come l'invio di notifiche push ai dispositivi tramite Funzioni di Azure.Also, within your serverless web and mobile apps, you can track events such as changes to your customer's profile, preferences, or location to trigger certain actions like sending push notifications to their devices using Azure Functions. Se si usa Azure Cosmos DB per creare un gioco, è ad esempio possibile usare il feed delle modifiche per implementare classifiche in tempo reale in base ai punteggi delle partite completate.If you're using Azure Cosmos DB to build a game, you can, for example, use change feed to implement real-time leaderboards based on scores from completed games.

Uso di Funzioni di AzureUsing Azure Functions

Se si usa Funzioni di Azure, il modo più semplice per connettersi a un feed di modifiche di Azure Cosmos DB consiste nell'aggiungere un trigger di Azure Cosmos DB all'app Funzioni di Azure.If you're using Azure Functions, the simplest way to connect to an Azure Cosmos DB change feed is to add an Azure Cosmos DB trigger to your Azure Functions app. Quando si crea un trigger di Azure Cosmos DB in un'app Funzioni di Azure, si seleziona la raccolta di Azure Cosmos DB a cui connettersi e la funzione viene attivata quando viene apportata una modifica alla raccolta.When you create an Azure Cosmos DB trigger in an Azure Functions app, you select the Azure Cosmos DB collection to connect to, and the function is triggered whenever a change to the collection is made.

I trigger possono essere creati nel portale di Funzioni di Azure, nel portale di Azure Cosmos DB o a livello di codice.Triggers can be created in the Azure Functions portal, in the Azure Cosmos DB portal, or programmatically. Per altre informazioni, vedere Azure Cosmos DB: elaborazione di database senza server con Funzioni di Azure.For more information, see Azure Cosmos DB: Serverless database computing using Azure Functions.

Uso dell'SDKUsing the SDK

SQL SDK per Azure Cosmos DB offre tutta la potenza necessaria per leggere e gestire un feed di modifiche,The SQL SDK for Azure Cosmos DB gives you all the power to read and manage a change feed. con tutte le responsabilità che ne derivano.But with great power comes lots of responsibilities, too. Se è necessario gestire checkpoint e numeri di sequenza di documenti e avere un controllo granulare sulle chiavi di partizione, usare l'SDK può essere l'approccio ideale.If you want to manage checkpoints, deal with document sequence numbers, and have granular control over partition keys, then using the SDK may be the right approach.

Questa sezione illustra come usare SQL SDK per lavorare con un feed di modifiche.This section walks through how to use the SQL SDK to work with a change feed.

  1. Iniziare leggendo le risorse seguenti da appconfig.Start by reading the following resources from appconfig. Le istruzioni per recuperare l'endpoint e la chiave di autorizzazione sono disponibili in Aggiornare la stringa di connessione.Instructions on retrieving the endpoint and authorization key are available in Update your connection string.

    DocumentClient client;
    string DatabaseName = ConfigurationManager.AppSettings["database"];
    string CollectionName = ConfigurationManager.AppSettings["collection"];
    string endpointUrl = ConfigurationManager.AppSettings["endpoint"];
    string authorizationKey = ConfigurationManager.AppSettings["authKey"];
    
  2. Creare il client come illustrato di seguito:Create the client as follows:

    using (client = new DocumentClient(new Uri(endpointUrl), authorizationKey,
    new ConnectionPolicy { ConnectionMode = ConnectionMode.Direct, ConnectionProtocol = Protocol.Tcp }))
    {
    }
    
  3. Ottenere gli intervalli di chiavi di partizione:Get the partition key ranges:

    FeedResponse pkRangesResponse = await client.ReadPartitionKeyRangeFeedAsync(
        collectionUri,
        new FeedOptions
            {RequestContinuation = pkRangesResponseContinuation });
    
    partitionKeyRanges.AddRange(pkRangesResponse);
    pkRangesResponseContinuation = pkRangesResponse.ResponseContinuation;
    
  4. Chiamare ExecuteNextAsync per ogni intervallo di chiavi di partizione:Call ExecuteNextAsync for every partition key range:

    foreach (PartitionKeyRange pkRange in partitionKeyRanges){
        string continuation = null;
        checkpoints.TryGetValue(pkRange.Id, out continuation);
        IDocumentQuery<Document> query = client.CreateDocumentChangeFeedQuery(
            collectionUri,
            new ChangeFeedOptions
            {
                PartitionKeyRangeId = pkRange.Id,
                StartFromBeginning = true,
                RequestContinuation = continuation,
                MaxItemCount = -1,
                // Set reading time: only show change feed results modified since StartTime
                StartTime = DateTime.Now - TimeSpan.FromSeconds(30)
            });
        while (query.HasMoreResults)
            {
                FeedResponse<dynamic> readChangesResponse = query.ExecuteNextAsync<dynamic>().Result;
    
                foreach (dynamic changedDocument in readChangesResponse)
                    {
                         Console.WriteLine("document: {0}", changedDocument);
                    }
                checkpoints[pkRange.Id] = readChangesResponse.ResponseContinuation;
            }
    }
    

Nota

Invece di ChangeFeedOptions.PartitionKeyRangeId, è possibile usare ChangeFeedOptions.PartitionKey per specificare una singola chiave di partizione per cui ottenere un feed di modifiche.Instead of ChangeFeedOptions.PartitionKeyRangeId, you can use ChangeFeedOptions.PartitionKey to specify a single partition key for which to get a change feed. Ad esempio, PartitionKey = new PartitionKey("D8CFA2FD-486A-4F3E-8EA6-F3AA94E5BD44").For example, PartitionKey = new PartitionKey("D8CFA2FD-486A-4F3E-8EA6-F3AA94E5BD44").

Se si hanno più lettori, è possibile usare ChangeFeedOptions per distribuire il carico delle letture in thread diversi o in client diversi.If you have multiple readers, you can use ChangeFeedOptions to distribute read load to different threads or different clients.

Con queste poche righe di codice è possibile iniziare a leggere il feed di modifiche.And that's it, with these few lines of code you can start reading the change feed. È possibile ottenere il codice completo usato in questo articolo dal repository GitHub.You can get the complete code used in this article from the GitHub repo.

Nel codice del passaggio 4 ResponseContinuation nell'ultima riga ha l'ultimo numero di sequenza logico (LSN) del documento, che verrà usato la volta successiva in cui si leggeranno nuovi documenti dopo questo numero di sequenza.In the code in step 4 above, the ResponseContinuation in the last line has the last logical sequence number (LSN) of the document, which you will use the next time you read new documents after this sequence number. Usando il valore StartTime di ChangeFeedOption è possibile ampliare il campo di ricerca per ottenere i documenti.By using the StartTime of the ChangeFeedOption you can widen your net to get the documents. Se quindi ResponseContinuation è null, ma StartTime risale indietro nel tempo, si otterranno tutti i documenti modificati dopo StartTime.So, if your ResponseContinuation is null, but your StartTime goes back in time then you will get all the documents that changed since the StartTime. Se invece per ResponseContinuation viene specificato un valore, il sistema restituirà tutti i documenti dopo tale LSN.But, if your ResponseContinuation has a value then system will get you all the documents since that LSN.

La matrice di checkpoint quindi conserva solo l'ultimo numero di sequenza per ogni partizione,So, your checkpoint array is just keeping the LSN for each partition. ma se non si vogliono gestire le partizioni, i checkpoint, l'ultimo numero di sequenza, l'ora di inizio e così via, l'opzione più semplice consiste nell'usare la libreria del processore dei feed di modifiche.But if you don’t want to deal with the partitions, checkpoints, LSN, start time, etc. the simpler option is to use the change feed processor library.

Uso della libreria del processore dei feed di modificheUsing the change feed processor library

La libreria del processore dei feed di modifiche di Azure Cosmos DB consente di distribuire facilmente l'elaborazione degli eventi in più consumer.The Azure Cosmos DB change feed processor library can help you easily distribute event processing across multiple consumers. Questa libreria semplifica la lettura delle modifiche nelle partizioni e in più thread che operano in parallelo.This library simplifies reading changes across partitions and multiple threads working in parallel.

Il vantaggio principale della libreria del processore dei feed di modifiche è che non è necessario gestire ogni partizione e token di continuazione né eseguire il poll manuale di ogni raccolta.The main benefit of change feed processor library is that you don’t have to manage each partition and continuation token and you don’t have to poll each collection manually.

La libreria del processore dei feed di modifiche semplifica la lettura delle modifiche nelle partizioni e in più thread che operano in parallelo.The change feed processor library simplifies reading changes across partitions and multiple threads working in parallel. Gestisce automaticamente la lettura delle modifiche nelle partizioni usando un meccanismo di lease.It automatically manages reading changes across partitions using a lease mechanism. Come si può osservare nell'immagine seguente, se si avviano due client che usano la libreria del processore dei feed di modifiche, il lavoro viene diviso tra di essi.As you can see in the following image, if you start two clients that are using the change feed processor library, they divide the work among themselves. Se si aumenta ancora il numero di client, il lavoro viene ulteriormente diviso tra di essi.As you continue to increase the clients, they keep dividing the work among themselves.

Elaborazione distribuita del feed delle modifiche di Azure Cosmos DB

Il client a sinistra è stato avviato per primo e ha iniziato a monitorare tutte le partizioni, quindi è stato avviato il secondo client e infine il primo ha assegnato alcuni lease al secondo client.The left client was started first and it started monitoring all the partitions, then the second client was started, and then the first let go of some of the leases to second client. Come si può notare, questo è il modo migliore per distribuire il lavoro tra computer e client diversi.As you can see this is the nice way to distribute the work between different machines and clients.

Si noti che, se si hanno due funzioni di Azure senza server che monitorano la stessa raccolta e usano lo stesso lease, le due funzioni possono ottenere documenti diversi a seconda di come la libreria del processore decide di elaborare le partizioni.Note that if you have two serverless Azure funtions monitoring the same collection and using the same lease then the two functions may get different documents depending upon how the processor library decides to processs the partitions.

Informazioni sulla libreria del processore dei feed di modificheUnderstanding the change feed processor library

L'implementazione della libreria del processore dei feed di modifiche prevede quattro componenti principali, ovvero la raccolta monitorata, la raccolta di lease, l'host del processore e i consumer.There are four main components of implementing the change feed processor library: the monitored collection, the lease collection, the processor host, and the consumers.

Avviso

La creazione di una raccolta ha implicazioni a livello di prezzi, poiché si sta riservando velocità effettiva per l'applicazione per comunicare con Azure Cosmos DB.Creating a collection has pricing implications, as you are reserving throughput for the application to communicate with Azure Cosmos DB. Per altre informazioni, visitare la pagina dei prezzi.For more details, please visit the pricing page

Raccolta monitorata: la raccolta monitorata include i dati da cui viene generato il feed di modifiche.Monitored Collection: The monitored collection is the data from which the change feed is generated. Eventuali inserimenti e modifiche alla raccolta monitorata vengono riflessi nel feed di modifiche della raccolta.Any inserts and changes to the monitored collection are reflected in the change feed of the collection.

Raccolta di lease: la raccolta di lease coordina l'elaborazione dei feed di modifiche in più processi di lavoro.Lease Collection: The lease collection coordinates processing the change feed across multiple workers. Una raccolta separata viene usata per archiviare i lease con un lease per partizione.A separate collection is used to store the leases with one lease per partition. È consigliabile archiviare questa raccolta di lease in un account diverso, con un'area di scrittura più vicina alla posizione in cui è in esecuzione il processore dei feed di modifiche.It is advantageous to store this lease collection on a different account with the write region closer to where the change feed processor is running. Un oggetto lease contiene gli attributi seguenti:A lease object contains the following attributes:

  • Owner: specifica l'host proprietario del lease.Owner: Specifies the host that owns the lease
  • Continuation: specifica la posizione (token di continuazione) nel feed di modifiche per una partizione specifica.Continuation: Specifies the position (continuation token) in the change feed for a particular partition
  • Timestamp: data dell'ultimo aggiornamento del lease. Il timestamp può essere usato per verificare se il lease viene considerato scaduto.Timestamp: Last time lease was updated; the timestamp can be used to check whether the lease is considered expired

Host del processore: ogni host determina il numero di partizioni da elaborare in base al numero di istanze di host con lease attivi.Processor Host: Each host determines how many partitions to process based on how many other instances of hosts have active leases.

  1. Quando un host viene avviato, acquisisce lease per bilanciare il carico di lavoro in tutti gli host.When a host starts up, it acquires leases to balance the workload across all hosts. Un host rinnova periodicamente i lease, in modo che i lease rimangano attivi.A host periodically renews leases, so leases remain active.
  2. Un host imposta come checkpoint il token di continuazione più recente sul rispettivo lease per ogni lettura.A host checkpoints the last continuation token to its lease for each read. Per garantire la sicurezza della concorrenza, un host verifica il valore ETag per ogni aggiornamento di lease.To ensure concurrency safety, a host checks the ETag for each lease update. Sono supportate anche altre strategie per i checkpoint.Other checkpoint strategies are also supported.
  3. All'arresto, un host rilascia tutti i lease ma mantiene le informazioni sulla continuazione, in modo che sia possibile riprendere la lettura dal checkpoint archiviato in un secondo momento.Upon shutdown, a host releases all leases but keeps the continuation information, so it can resume reading from the stored checkpoint later.

Il numero di host non può attualmente essere superiore al numero di partizioni (lease).At this time the number of hosts cannot be greater than the number of partitions (leases).

Consumer: i consumer, o processi di lavoro, sono thread che eseguono l'elaborazione del feed di modifiche avviata da ogni host.Consumers: Consumers, or workers, are threads that perform the change feed processing initiated by each host. Ogni host di processori può includere più consumer.Each processor host can have multiple consumers. Ogni consumer legge il feed di modifiche dalla partizione a cui è assegnato e invia notifiche al rispettivo host in caso di modifiche e di lease scaduti.Each consumer reads the change feed from the partition it is assigned to and notifies its host of changes and expired leases.

Per una migliore comprensione dell'interazione tra i quattro elementi del processore dei feed di modifiche, è consigliabile esaminare un esempio nel diagramma seguente.To further understand how these four elements of change feed processor work together, let's look at an example in the following diagram. La raccolta monitorata archivia i documenti e usa il valore "city" come chiave di partizione.The monitored collection stores documents and uses the "city" as the partition key. Come si può notare, la partizione blu contiene i documenti con il campo "city" compreso tra "A-E" e così via.We see that the blue partition contains documents with the "city" field from "A-E" and so on. Sono disponibili due host, ognuno con due consumer che leggono dalle quattro partizioni in parallelo.There are two hosts, each with two consumers reading from the four partitions in parallel. Le frecce mostrano i consumer che leggono da un punto specifico nel feed di modifiche.The arrows show the consumers reading from a specific spot in the change feed. Nella prima partizione il colore blu scuro rappresenta le modifiche non lette, mentre il colore blu chiaro rappresenta le modifiche già lette nel feed di modifiche.In the first partition, the darker blue represents unread changes while the light blue represents the already read changes on the change feed. Gli host usano la raccolta di lease per archiviare un valore di tipo "continuation" per tenere traccia della posizione di lettura corrente per ogni consumer.The hosts use the lease collection to store a "continuation" value to keep track of the current reading position for each consumer.

Uso dell'host del processore del feed delle modifiche di Azure Cosmos DB

Uso della libreria del processore dei feed di modificheWorking with the change feed processor library

Prima di installare il pacchetto NuGet del processore dei feed di modifiche, installare quanto segue:Before installing change feed processor NuGet package, first install:

  • Microsoft.Azure.DocumentDB, versione più recente.Microsoft.Azure.DocumentDB, latest version.
  • Newtonsoft.Json, versione più recenteNewtonsoft.Json, latest version

Installare quindi il pacchetto Nuget Microsoft.Azure.DocumentDB.ChangeFeedProcessor e includerlo come riferimento.Then install the Microsoft.Azure.DocumentDB.ChangeFeedProcessor Nuget package and include it as a reference.

Per implementare la libreria del processore dei feed di modifiche, è necessario seguire questa procedura:To implement the change feed processor library you have to do following:

  1. Implementare un oggetto DocumentFeedObserver, che implementa IChangeFeedObserver.Implement a DocumentFeedObserver object, which implements IChangeFeedObserver.

    using System;
    using System.Collections.Generic;
    using System.Threading;
    using System.Threading.Tasks;
    using Microsoft.Azure.Documents;
    using Microsoft.Azure.Documents.ChangeFeedProcessor.FeedProcessing;
    using Microsoft.Azure.Documents.Client;
    
    /// <summary>
    /// This class implements the IChangeFeedObserver interface and is used to observe 
    /// changes on change feed. ChangeFeedEventHost will create as many instances of 
    /// this class as needed. 
    /// </summary>
    public class DocumentFeedObserver : IChangeFeedObserver
    {
    private static int totalDocs = 0;
    
        /// <summary>
        /// Initializes a new instance of the <see cref="DocumentFeedObserver" /> class.
        /// Saves input DocumentClient and DocumentCollectionInfo parameters to class fields
        /// </summary>
        /// <param name="client"> Client connected to destination collection </param>
        /// <param name="destCollInfo"> Destination collection information </param>
        public DocumentFeedObserver()
        {
    
        }
    
        /// <summary>
        /// Called when change feed observer is opened; 
        /// this function prints out observer partition key id. 
        /// </summary>
        /// <param name="context">The context specifying partition for this observer, etc.</param>
        /// <returns>A Task to allow asynchronous execution</returns>
        public Task OpenAsync(IChangeFeedObserverContext context)
        {
            Console.ForegroundColor = ConsoleColor.Magenta;
            Console.WriteLine("Observer opened for partition Key Range: {0}", context.PartitionKeyRangeId);
            return Task.CompletedTask;
        }
    
        /// <summary>
        /// Called when change feed observer is closed; 
        /// this function prints out observer partition key id and reason for shut down. 
        /// </summary>
        /// <param name="context">The context specifying partition for this observer, etc.</param>
        /// <param name="reason">Specifies the reason the observer is closed.</param>
        /// <returns>A Task to allow asynchronous execution</returns>
        public Task CloseAsync(IChangeFeedObserverContext context, ChangeFeedObserverCloseReason reason)
        {
            Console.ForegroundColor = ConsoleColor.Cyan;
            Console.WriteLine("Observer closed, {0}", context.PartitionKeyRangeId);
            Console.WriteLine("Reason for shutdown, {0}", reason);
            return Task.CompletedTask;
        }
    
        public Task ProcessChangesAsync(IChangeFeedObserverContext context, IReadOnlyList<Document> docs, CancellationToken cancellationToken)
        {
            Console.ForegroundColor = ConsoleColor.Green;
            Console.WriteLine("Change feed: PartitionId {0} total {1} doc(s)", context.PartitionKeyRangeId, Interlocked.Add(ref totalDocs, docs.Count));
            foreach (Document doc in docs)
            {
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine(doc.Id.ToString());
            }
    
            return Task.CompletedTask;
        }
    }
    
  2. Implementare un oggetto DocumentFeedObserverFactory, che implementa IChangeFeedObserverFactory.Implement a DocumentFeedObserverFactory, which implements a IChangeFeedObserverFactory.

     using Microsoft.Azure.Documents.ChangeFeedProcessor.FeedProcessing;
    
    /// <summary>
    /// Factory class to create instance of document feed observer. 
    /// </summary>
    public class DocumentFeedObserverFactory : IChangeFeedObserverFactory
    {
        /// <summary>
        /// Initializes a new instance of the <see cref="DocumentFeedObserverFactory" /> class.
        /// Saves input DocumentClient and DocumentCollectionInfo parameters to class fields
        /// </summary>
        public DocumentFeedObserverFactory()
        {
        }
    
        /// <summary>
        /// Creates document observer instance with client and destination collection information
        /// </summary>
        /// <returns>DocumentFeedObserver with client and destination collection information</returns>
        public IChangeFeedObserver CreateObserver()
        {
            DocumentFeedObserver newObserver = new DocumentFeedObserver();
            return newObserver as IChangeFeedObserver;
        }
    }
    
  3. Definire CancellationTokenSource e ChangeFeedProcessorBuilderDefine CancellationTokenSource and ChangeFeedProcessorBuilder

    private readonly CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
    private readonly ChangeFeedProcessorBuilder builder = new ChangeFeedProcessorBuilder();
    
  4. Compilare ChangeFeedProcessorBuilder dopo avere definito gli oggetti pertinentibuild the ChangeFeedProcessorBuilder after defining the relevant objects

            string hostName = Guid.NewGuid().ToString();
    
            // monitored collection info 
            DocumentCollectionInfo documentCollectionInfo = new DocumentCollectionInfo
            {
                Uri = new Uri(this.monitoredUri),
                MasterKey = this.monitoredSecretKey,
                DatabaseName = this.monitoredDbName,
                CollectionName = this.monitoredCollectionName
            };
    
            DocumentCollectionInfo leaseCollectionInfo = new DocumentCollectionInfo
                {
                    Uri = new Uri(this.leaseUri),
                    MasterKey = this.leaseSecretKey,
                    DatabaseName = this.leaseDbName,
                    CollectionName = this.leaseCollectionName
                };
            DocumentFeedObserverFactory docObserverFactory = new DocumentFeedObserverFactory();
            ChangeFeedOptions feedOptions = new ChangeFeedOptions();
    
            /* ie customize StartFromBeginning so change feed reads from beginning
                can customize MaxItemCount, PartitonKeyRangeId, RequestContinuation, SessionToken and StartFromBeginning
            */
    
            feedOptions.StartFromBeginning = true;
    
            ChangeFeedProcessorOptions feedProcessorOptions = new ChangeFeedProcessorOptions();
    
            // ie. customizing lease renewal interval to 15 seconds
            // can customize LeaseRenewInterval, LeaseAcquireInterval, LeaseExpirationInterval, FeedPollDelay 
            feedProcessorOptions.LeaseRenewInterval = TimeSpan.FromSeconds(15);
    
            this.builder
                .WithHostName(hostName)
                .WithFeedCollection(documentCollectionInfo)
                .WithLeaseCollection(leaseCollectionInfo)
                .WithProcessorOptions (feedProcessorOptions)
                .WithObserverFactory(new DocumentFeedObserverFactory());               
                //.WithObserver<DocumentFeedObserver>();  If no factory then just pass an observer
    
            var result =  await this.builder.BuildAsync();
            await result.StartAsync();
            Console.Read();
            await result.StopAsync();    
    

La procedura è terminata.That’s it. Dopo questi passaggi i documenti inizieranno a essere inclusi nel metodo DocumentFeedObserver.ProcessChangesAsync.After these few steps documents will start showing up into the DocumentFeedObserver.ProcessChangesAsync method.

Il codice sopra indicato è a scopo illustrativo per mostrare un tipo diverso di oggetti e la loro interazione.Above code is for illustration purpose to show different kind of objects and their interaction. È necessario definire le variabili appropriate e avviarle manualmente con i valori corretti.You have to define proper variables and initiate them with correct values. È possibile ottenere il codice completo usato in questo articolo dal repository GitHub.You can get the complete code used in this article from the GitHub repo.

Nota

Non si dovrebbe mai avere una chiave master nel codice o nel file di configurazione, come mostrato nel codice sopra indicato.You should never have a master key in your code or in config file as shown in above code. Vedere come usare Key Vault per recuperare le chiavi.Please see how to use Key-Vault to retrive the keys.

Domande frequentiFAQ

Quali sono i diversi modi per leggere i feed di modifiche e quando si utilizza ogni metodoWhat are the different ways you can read Change Feed? and when to use each method?

Sono disponibili tre opzioni per leggere i feed di modifiche:There are three options for you to read change feed:

  • Uso dell'SDKUsing Azure Cosmos DB SQL API .NET SDK

    Con questo metodo si ottiene un basso livello di controllo sul feed di modifiche.By using this method, you get low level of control on change feed. È possibile gestire il checkpoint, accedere a una chiave di partizione specifica e così via. Se si hanno più lettori, è possibile usare ChangeFeedOptions per distribuire il carico delle letture in thread diversi o in client diversi.You can manage the checkpoint, you can access a particular partition key etc. If you have multiple readers, you can use ChangeFeedOptions to distribute read load to different threads or different clients. ..

  • Uso della libreria del processore dei feed di modifiche di Azure Cosmos DBUsing the Azure Cosmos DB change feed processor library

    Se si desidera nascondere buona parte della complessità del feed di modifiche, è possibile utilizzare la libreria del processore dei feed di modifiche.If you want to outsource lot of complexity of change feed then you can use change feed processor library. Questa libreria nasconde buona parte della complessità pur lasciando il controllo completo sui feed di modifiche.This library hides lot of complexity, but still gives you complete control on change feed. La libreria segue un criterio osservatore in cui la funzione di elaborazione viene chiamata dall'SDK.This library follows an observer pattern, your processing function is called by the SDK.

    Se il feed di modifiche è caratterizzato da una velocità effettiva elevata, è possibile creare più istanze client per leggere il feed di modifiche.If you have a high throughput change feed, you can instantiate multiple clients to read the change feed. Poiché si sta usando la "libreria del processore dei feed di modifiche", il carico verrà diviso automaticamente tra diversi client.Because you are using “change feed processor library”, it will automatically divide the load among different clients. Non è necessario eseguire alcuna operazione.You do not have to do anything. Tutte le complessità vengono gestite dall'SDK.All the complexity is handled by SDK. Tuttavia, se si desidera avere un bilanciamento del carico proprio, è possibile implementare IParitionLoadBalancingStrategy per applicare una strategia di partizionamento personalizzata.However, if you want to have your own load balancer, then you can implement IParitionLoadBalancingStrategy for custom partition strategy. Implementare IPartitionProcessor per elaborare in modalità personalizzata le modifiche in una partizione.Implement IPartitionProcessor – for custom processing changes on a partition. Tuttavia, con l'SDK, è possibile elaborare un intervallo di partizioni, ma se si desidera elaborare una chiave di partizione specifica, è necessario utilizzare SDK per l'API SQL.However, with SDK, you can process a partition range but if you want to process a particular partition key then you have to use SDK for SQL API.

  • Uso di Funzioni di AzureUsing Azure Functions

    L'ultima opzione di Funzioni di Azure è l'opzione più semplice.The last option Azure Function is the simplest option. Si consiglia di usare questa opzione.We recommend using this option. Quando si crea un trigger di Azure Cosmos DB in un'app per le funzioni di Azure, si sceglie la raccolta di Azure Cosmos DB a cui connettersi e la funzione viene attivata quando viene apportata una modifica alla raccolta.When you create an Azure Cosmos DB trigger in an Azure Functions app, you select the Azure Cosmos DB collection to connect to and the function is triggered whenever a change to the collection is made. È disponibile uno screencast sull'utilizzo di Funzioni di Azure e del feed di modifichewatch a screen cast of using Azure function and change feed

    I trigger possono essere creati nel portale di Funzioni di Azure, nel portale di Azure Cosmos DB o a livello di codice.Triggers can be created in the Azure Functions portal, in the Azure Cosmos DB portal, or programmatically. Visual Studio e VS Code dispongono di un supporto ottimo per scrivere funzioni di Azure.Visual Studio and VS Code has great support to write Azure Function. È possibile scrivere il codice ed eseguire il debug dal desktop e quindi distribuire la funzione con un solo clic.You can write and debug the code on your desktop, and then deploy the function with one click. Per altre informazioni, vedere l'articolo Azure Cosmos DB: elaborazione di database senza server con Funzioni di Azure.For more information, see Azure Cosmos DB: Serverless database computing using Azure Functions article.

Che cos'è l'ordine dei documenti nel feed di modifiche?What is the sort order of documents in change feed?

I documenti nel feed di modifiche sono ordinati in base all'ora di modifica.Change feed documents comes in order of their modification time. Questo tipo di ordinamento è garantito soltanto all'interno di ogni partizione.This sort order is guaranteed only per partition.

Per gli account con più aree, che cosa accade al feed di modifiche quando l'area di scrittura esegue il failover?For a multi-region account, what happens to the change feed when the write-region fails-over? Il failover coinvolge anche il feed di modifiche?Does the change feed also failover? Il feed di modifiche appare ancora contiguo o la causa del failover provoca la reimpostazione del feed di modifiche?Would the change feed still appear contiguous or would the fail-over cause change feed to reset?

Sì, il feed di modifiche funziona indipendentemente dall'operazione di failover manuale e sarà contiguo.Yes, change feed will work across the manual failover operation and it will be contiguous.

Per quanto tempo il feed di modifiche mantiene i dati modificati se si imposta la proprietà TTL (Time to Live) per il documento su -1?How long change feed persist the changed data if I set the TTL (Time to Live) property for the document to -1?

Il feed di modifiche mantiene i dati modificati per sempre.Change feed will persist forever. Se i dati non sono eliminati, rimarranno nel feed di modifiche.If data is not deleted, it will remain in change feed.

Come si configura Funzioni di Azure per leggere da una determinata area, dal momento che il feed di modifiche è disponibile in tutte le aree di lettura per impostazione predefinita?How can I configure Azure functions to read from a particular region, as change feed is available in all the read regions by default?

Non è attualmente possibile configurare Funzioni di Azure per leggere da una determinata area.Currently it’s not possible to configure Azure Functions to read from a particular region. C'è un problema di GitHub nell'archivio Funzioni di Azure che riguarda l'impostazione delle aree preferite per le operazioni di associazione e attivazione di Azure Cosmos DB.There is a GitHub issue in the Azure Functions repo to set the preferred regions of any Azure Cosmos DB binding and trigger.

Funzioni di Azure usa il criterio di connessione predefinito.Azure Functions uses the default connection policy. È possibile configurare la modalità di connessione in Funzioni di Azure e poiché, per impostazione predefinita, la modalità viene letta anche nell'area di scrittura, è consigliabile collocare Funzioni di Azure nella stessa area.You can configure connection mode in Azure Functions and by default, it reads from the write region, so it is best to co-locate Azure Functions on the same region.

Qual è la dimensione predefinita dei batch in Funzioni di Azure?What is the default size of batches in Azure Functions?

100 documenti in ogni chiamata di Funzioni di Azure.100 documents at every invocation of Azure Functions. Tuttavia, il numero è configurabile all'interno del file function.json.However, this number is configurable within the function.json file. Qui è disponibile un elenco completo delle opzioni di configurazione.Here is complete list of configuration options. Se si sta sviluppando localmente, aggiornare le impostazioni dell'applicazione all'interno del file local.settings.json.If you are developing locally, update the application settings within the local.settings.json file.

Durante il monitoraggio di una raccolta e la lettura del feed di modifiche si nota che non è possibile vedere tutti i documenti inseriti, alcuni mancano.I am monitoring a collection and reading its change feed, however I see I am not getting all the inserted document, some documents are missing. Che cosa accade?What is going on here?

Verificare che nessun'altra funzione stia leggendo la medesima raccolta con la stessa raccolta di lease.Please make sure that there is no other function reading the same collection with the same lease collection. È possibile che i documenti mancanti vengano elaborati da altre funzioni di Azure che usano lo stesso lease.It happened to me, and later I realized the missing documents are processed by my other Azure functions, which is also using the same lease.

Pertanto, se si creano più funzioni di Azure per leggere lo stesso feed di modifiche, le funzioni devono utilizzare una raccolta di lease diversa o usare la configurazione "leasePrefix" per condividere la stessa raccolta.Therefore, if you are creating multiple Azure Functions to read the same change feed then they must use different lease collection or use the “leasePrefix” configuration to share the same collection. Tuttavia, quando si usa la libreria del processore dei feed di modifiche, è possibile avviare più istanze della propria funzione e SDK provvederà a suddividere automaticamente i documenti tra le diverse istanze.However, when you use change feed processor library you can start multiple instances of your function and SDK will divide the documents between different instances automatically for you.

Il documento viene aggiornato ogni secondo ma le funzioni di Azure in ascolto su quel feed di modifiche non ricevono tutte le modifiche.My document is updated every second, and I am not getting all the changes in Azure Functions listening to change feed.

Funzioni di Azure esegue il polling del feed di modifiche ogni 5 secondi, quindi le modifiche apportate tra i due polling vanno perse.Azure Functions polls change feed for every 5 seconds, so any changes made between 5 seconds are lost. Azure Cosmos DB archivia una sola versione ogni 5 secondi, quindi si otterrà la 5° modifica del documento.Azure Cosmos DB stores just one version for every 5 seconds so you will get the 5th change on the document. Tuttavia, se si desidera scendere al di sotto dei 5 secondi ed eseguire il polling del feed di modifiche ogni secondo, configurare il tempo di polling "feedPollTime". A questo proposito, vedere le associazioni di Azure Cosmos DB.However, if you want to go below 5 second, and want to poll change Feed every second, You can configure the polling time “feedPollTime”, see Azure Cosmos DB bindings. Il valore è definito in millisecondi e l'impostazione predefinita è 5000.It is defined in milliseconds with a default of 5000. Scendere al di sotto di 1 secondo è possibile ma non consigliabile perché l'utilizzo della CPU diventa elevato.Below 1 second is possible but not advisable, as you will start burning more CPU.

Un documento è stato inserito nella raccolta di API Mongo, ma quando il documento compare nel feed di modifiche, presenta un valore ID diverso.I inserted a document in the Mongo API collection, but when I get the document in change feed, it shows a different id value. Qual è il problema?What is wrong here?

La raccolta è una raccolta di API Mongo.Your collection is Mongo API collection. Il feed di modifiche viene letto usando il client SQL e serializza gli elementi in formato JSON.Remember, change feed is read using the SQL client and serializes items into JSON format. A causa della formattazione JSON, nei client MongoDB i documenti in formato JSON non corrisponderanno al feed di modifiche in formato JSON.Because of the JSON formatting, MongoDB clients will experience a mismatch between BSON formatted documents and the JSON formatted change feed. Il realtà, quello che si visualizza è la rappresentazione di un documento BSON in JSON.You are seeing is the representation of a BSON document in JSON. Se si usano gli attributi binari in un account Mongo, questi vengono convertiti in JSON.If you use binary attributes in a Mongo accounts, they are converted to JSON.

È possibile controllare il feed di modifiche solo per gli aggiornamenti e non per gli inserimenti?Is there a way to control change feed for updates only and not inserts?

Al momento non è possibile, ma questa funzionalità è prevista.Not today, but this functionality is on roadmap. Per ora, è possibile contrassegnare gli aggiornamenti nel documento con un soft marker.Today, you can add a soft marker on the document for updates.

È possibile inserire le eliminazioni nel feed di modifiche?Is there a way to get deletes in change feed?

Attualmente, le eliminazioni non vengono registrate nel feed di modifiche.Currently change feed doesn’t log deletes. Il feed di modifiche viene continuamente aggiornato e questa funzionalità è prevista.Change feed is continuously improving, and this functionality is on roadmap. Per ora, è possibile contrassegnare le eliminazioni nel documento con un soft marker.Today, you can add a soft marker on the document for delete. Aggiungere al documento un attributo denominato "deleted", impostarlo su "true" e impostare una durata (TTL) nel documento in modo che possa essere eliminato automaticamente.Add an attribute on the document called “deleted” and set it to “true” and set a TTL on the document so that it can be automatically deleted.

È possibile leggere il feed di modifiche per i documenti storici, cioè documenti aggiunti, ad esempio, 5 anni fa?Can I read change feed for historic documents(for example, documents that were added 5 years back) ?

Se il documento non è stato eliminato, è possibile leggere il feed di modifiche fino all'origine della raccolta.Yes, if the document is not deleted you can read the change feed as far as the origin of your collection.

È possibile leggere il feed di modifiche tramite JavaScript?Can I read change feed using JavaScript?

Sì, il supporto iniziale di Node.js SDK per il feed di modifiche è stato aggiunto di recente.Yes, Node.js SDK initial support for change feed is recently added. E può essere utilizzato come illustrato nell'esempio seguente. Aggiornare il modulo documentdb alla versione corrente prima di eseguire il codice:It can be used as shown in the following example, please update documentdb module to current version before you run the code:


var DocumentDBClient = require('documentdb').DocumentClient;
const host = "https://your_host:443/";
const masterKey = "your_master_key==";
const databaseId = "db";
const collectionId = "c1";
const dbLink = 'dbs/' + databaseId;
const collLink = dbLink + '/colls/' + collectionId;
var client = new DocumentDBClient(host, { masterKey: masterKey });
let options = {
    a_im: "Incremental feed",
    accessCondition: {
        type: "IfNoneMatch",        // Use: - empty condition (or remove accessCondition entirely) to start from beginning.
        //      - '*' to start from current.
        //      - specific etag value to start from specific continuation.
        condition: ""
    }
};

var query = client.readDocuments(collLink, options);
query.executeNext((err, results, headers) =&gt; {
    // Now we have headers.etag, which can be used in next readDocuments in accessCondition option.
    console.log(results);
    console.log(headers.etag);
    console.log(results.length);
    options.accessCondition = { type: "IfNoneMatch", condition: headers.etag };
    var query = client.readDocuments(collLink, options);
    query.executeNext((err, results, headers) =&gt; {
        console.log("next one:", results[0]);
    });
});<span id="mce_SELREST_start" style="overflow:hidden;line-height:0;"></span>

È possibile leggere il feed di modifiche tramite Java?Can I read change feed using Java?

La libreria Java per leggere il feed di modifiche è disponibile nel repository Github.Java library to read change feed is available in Github repository. Tuttavia, attualmente la libreria Java è alcune versioni indietro rispetto alla libreria .NET.However, currently Java library is few versions behind .NET library. A breve le due librerie saranno sincronizzate.Soon both the libraries will be in sync.

Si possono usare _etag, _lsn o _ts per la gestione interna e come in risposta?Can I use _etag, _lsn or _ts for internal bookkeeping, which I get in response?

_etag è un formato interno da cui è sconsigliabile dipendere, pertanto evitare di analizzarlo perché può cambiare in qualsiasi momento._etag format is internal and you should not depend on it (do not parse it) because it can change anytime. _ts è un timestamp di creazione o modifica._ts is modification or creation time stamp. Si può usare _ts per confronti cronologici.You can use _ts for chronological comparison. _lsn è un ID batch che viene aggiunto solo per i feed di modifiche e che rappresenta l'ID della transazione dall'archivio._lsn is is a batch id that is added only for change feed, it represents the transaction id from the store.. Molti documenti potrebbero avere lo stesso _lsn.Many documents may have same _lsn. Un'altra cosa da segnalare: l'ETag di FeedResponse è diverso dal valore _etag visualizzato nel documento.One more thing to note, ETag on FeedResponse is different than the _etag you see on the document. _etag è un identificatore interno utilizzato per il controllo della concorrenza e indica la versione del documento mentre ETag viene utilizzato per la sequenziazione del feed._etag is an internal identifier and used to concurrency, it tells about the version of the document and ETag is used for sequencing the feed.

La lettura del feed di modifiche aggiunge costi supplementari?Does reading change feed add any additional cost ?

L'addebito riguarda le UR utilizzate, ad esempio, lo spostamento dei dati da e verso le raccolte di Azure Cosmos DB utilizzano sempre le UR.You are charged for the RU’s consumed i.e. data movement in and out of Azure Cosmos DB collections always consume RU. Agli utenti verranno addebitate le UR utilizzate dalla raccolta di lease.Users will be charged for RU consumed by the lease collection.

Più Funzioni di Azure possono leggere il feed di modifiche di una sola raccolta?Can multiple Azure Functions read one collection’s change feed?

Sì.Yes. S', più Funzioni di Azure possono leggere il feed di modifiche di una sola raccolta.Multiple Azure Functions can read the same collection’s change feed. Tuttavia, per ogni istanza di Funzioni di Azure dovrà essere stato definito un leaseCollectionPrefix separato.However, the Azure Functions need to have a separate leaseCollectionPrefix defined.

La raccolta di lease deve essere partizionata?Should the lease collection be partitioned?

No, la raccolta di lease può essere fissa.No, lease collection can be Fixed. Le raccolte di lease partizionate non sono necessarie e attualmente neanche supportate.Partitioned lease collection is not needed and it’s not currently supported.

È possibile leggere il feed di modifiche tramite Spark?Can I read change feed from Spark?

Sì,Yes, you can. Vedere Velocizzare l'analisi di Big Data in tempo reale con il connettore Spark per Azure Cosmos DB.Please see Azure Cosmos DB Spark Connector. È disponibile uno screencast che mostra come elaborare il feed di modifiche come flusso strutturato.Here is a screen cast showing how you can process change feed as a structured stream.

Poniamo che si stia elaborando un feed di modifiche utilizzando Funzioni di Azure, ad esempio su un batch di 10 documenti, e che si verifichi un errore nel documento 7.If I am processing change feed by using Azure Functions, say a batch of 10 documents, and I get an error at 7th Document. In tal caso, gli ultimi tre documenti non verrebbero elaborati. In che modo è possibile riprendere l'elaborazione a partire dal documento non riuscito, cioèIn that case the last three documents are not processed how can I start processing from the failed document(i.e dal documento 7, nel feed successivo?7th document) in my next feed?

La soluzione consigliata per gestire l'errore consiste nel racchiudere il codice in un blocco Try-Catch.To handle the error, the recommended pattern is to wrap your code with try-catch block. Questa procedura consiste nel rilevare l'errore, inserire il documento in questione in una coda di documenti non recapitabili e quindi definire la logica per gestire i documenti che hanno generato l'errore.Catch the error and put that document on a queue (dead-letter)and then define logic to deal with the documents that produced the error. Se il batch comprende 200 documenti e l'errore riguarda un solo documento, questo metodo consente di evitare di invalidare l'intero batch.With this method if you have a 200-document batch, and just one document failed, you do not have to throw away the whole batch.

In caso di errore, non si dovrà riportare il punto di controllo all'inizio altrimenti i documenti che hanno generato l'errore verranno continuamente recuperati dal feed di modifiche.In case of error you should not rewind the check point back to beginning else you will can keep getting those documents from change feed. Tenere presente che il feed di modifiche mantiene l'ultimo snapshot finale dei documenti, quindi, per questo motivo, si potrebbe perdere lo snapshot precedente del documento.Remember, change feed keeps the last final snap shot of the documents, because of this you may lose the previous snapshot on the document. Il feed di modifiche mantiene solo l'ultima versione del documento e nel frattempo altri processi possono intervenire a modificare il documento.change feed keeps only one last version of the document, and in between other processes can come and change the document.

Man mano che si continua a correggere il codice, la coda dei documenti non recapitabili si svuoterà.As you keep fixing your code, you will soon find no documents on dead-letter queue. Funzioni di Azure viene chiamato automaticamente dal sistema del feed di modifiche e il punto di controllo viene gestito internamente dalla funzione di Azure.Azure Functions is automatically called by change feed system and check point etc is maintained internally by Azure Function. Se si desidera eseguire il rollback del punto di controllo e controllarne tutti gli aspetti, considerare di utilizzare l'SDK processore del feed di modifiche.If you want to roll back the check point and control every aspect of it, you should consider using change feed Processor SDK.

Passaggi successiviNext steps

Per altre informazioni sull'uso di Azure Cosmos DB con Funzioni di Azure, vedere Azure Cosmos DB: elaborazione di database senza server con Funzioni di Azure.For more information about using Azure Cosmos DB with Azure Functions see Azure Cosmos DB: Serverless database computing using Azure Functions.

Per altre informazioni sull'uso della libreria del processore dei feed di modifiche, usare le risorse seguenti:For more information on using the change feed processor library, use the following resources:

Per altre informazioni sull'uso del feed di modifiche tramite l'SDK, usare le risorse seguenti:For more information on using the change feed via the SDK, use the following resources: