Modificare il flusso in Azure DocumentDB

I flussi di modifica sono un flusso in tempo reale delle modifiche del database che passano dal database all'applicazione. Questa funzionalità consente di creare applicazioni reattive sottoscrivendo le modifiche del database, eliminando la necessità di eseguire il polling continuo per rilevare le modifiche.

Annotazioni

Azure DocumentDB supporta attualmente Change Stream in cluster a partizione singola. Microsoft sta lavorando attivamente per fornire il supporto di Change Stream per i cluster con più partizioni nel prossimo futuro.

Azure DocumentDB applica un limite di log gestito dal sistema di 400 MB per i flussi di modifica. I clienti devono elaborare continuamente i "Change Streams" per evitare di perdere eventi di modifica nel passato. Change Streams usa log gestiti dal sistema con un limite di dimensioni di 400 MB. Se un token di ripresa fa riferimento a un evento di modifica che è stato eliminato dal registro, il Change Stream non può essere ripreso da quel punto e deve essere riavviato. Abbiamo in programma un'anteprima per il supporto esteso nel prossimo futuro.

Abilitare i flussi di modifica

È possibile abilitare o disabilitare questa funzionalità usando interfaccia della riga di comando di Azure o un modello ARM. Il supporto del portale verrà aggiunto a breve.

Procedura per abilitare i flussi di modifica nel cluster tramite l'interfaccia della riga di comando

  1. Accedere a interfaccia della riga di comando di Azure
az login
  1. Recupera le impostazioni correnti dei flag di funzionalità del cluster. In questo modo si garantisce di mantenere tutti i flag esistenti durante l'aggiunta della nuova funzionalità.
az resource show --ids "/subscriptions/<sub id>/resourceGroups/<resource group name>/providers/Microsoft.DocumentDB/mongoClusters/<resource name of your Azure DocumentDB cluster>" --api-version 2024-10-01-preview
  1. Inviare una richiesta PATCH per abilitare la funzionalità.
az resource patch --ids "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>" --api-version 2024-10-01-preview --properties "{\"previewFeatures\": [ \"ChangeStreams\"]}"
  1. Verificare il risultato:
    • Verificare che il payload della risposta includa "previewFeatures": ["ChangeStreams"].
    • Se si verifica l'errore "i flussi di modifica non sono supportati in questo cluster", creare una richiesta di supporto.

Configurazione dei flussi di modifica

Questo codice di esempio avvia un flusso di modifiche nella exampleCollection raccolta, monitorando continuamente eventuali modifiche. Quando viene rilevata una modifica, recupera l'evento di modifica e la stampa in formato JSON.

// Open a change stream
const changeStream = db.exampleCollection.watch();

// Listen for changes
while (changeStream.hasNext()) 
    {
        const change = changeStream.next();
        printjson(change);
    }

Importante

I flussi di modifica possono essere ripresi specificando un token di ripresa a resumeAfter quando si apre il cursore. Tuttavia, è previsto che sia disponibile una cronologia sufficiente per individuare l'operazione associata al token. Il documento osservato nel flusso di modifiche nel _id campo rappresenta il token ripristinabile.

cursor = db.exampleCollection.watch(resume_after=resume_token)

Monitoraggio delle modifiche del database con Change Stream

Si esaminerà ora l'output del flusso di modifiche tramite l'esempio.

In questo evento del flusso di modifiche, vediamo che un nuovo record è stato inserted nella collezione exampleCollection all'interno del database cs, e i dettagli dell'evento includono il contenuto completo del documento appena aggiunto.

{
  "_id": { "_data": "AeARBpQ/AAAA" }, // "resume_token"
  "operationType": "insert",
  "fullDocument": {
    "_id": { "$oid": "66e6f63e6f49ecaabf794958" },
    "employee_id": "17986",
    "name": "John",
    "position": "Software Engineer",
    "department": "IT",
    "rating": 4
  },
  "ns": { "db": "cs", "coll": "exampleCollection" },
  "documentKey": { "_id": { "$oid": "66e6f63e6f49ecaabf794958" } }
}

Personalizzare i dati nel flusso di cambiamento

Personalizzare l'output del flusso di modifiche specificando una matrice di una o più fasi della pipeline durante la configurazione. Gli operatori supportati includono quanto segue.

  • $addFields
  • $match
  • $project
  • $set
  • $unset

Limitazioni

  • Gli eventi del flusso di modifica nel cluster con più partizioni non sono ancora supportati.
  • È necessario reinizializzare i cursori del flusso di modifica dopo un evento di failover allo stato corrente.
  • Update l'evento non supporta ancora la funzione di aggiornamento della descrizione.
  • pre-image è un'opzione non supportata.
  • $changestream come pipeline annidata all'interno di un'altra fase, non è ancora supportata.