Condividi tramite

Spazi dei nomi di Griglia di eventi di Azure - Supporto per lo schema CloudEvents

  • Articolo

Gli argomenti dello spazio dei nomi di Griglia di eventi accettano eventi conformi alla specifica CloudEvents 1.0, standard aperto, della Cloud Native Computing Foundation (CNCF) usando il binding del protocollo HTTP in formato JSON. Un CloudEvent è un tipo di messaggio che contiene ciò che viene comunicato, detto dati dell'evento e metadati su di esso. I dati degli eventi nelle architetture guidate dagli eventi in genere contengono le informazioni che annunciano una modifica dello stato del sistema. I metadati CloudEvents sono costituiti da un set di attributi che forniscono informazioni contestuali sul messaggio, ad esempio dove ha avuto origine (il sistema di origine), il tipo e così via. Tutti i messaggi validi che seguono le specifiche CloudEvents devono includere gli attributi di contesto obbligatori seguenti:

La specifica CloudEvents definisce anche gli attributi facoltativi e di contesto dell'estensione che è possibile includere quando si usa Griglia di eventi.

Quando si usa Griglia di eventi, CloudEvents è il formato di evento preferito perché offre casi d'uso ben documentati (modalità per il trasferimento di eventi, formati di eventi e così via), estendibilità e interoperabilità migliorata. CloudEvents migliora l'interoperabilità fornendo un formato eventi comune per la pubblicazione e l'utilizzo degli eventi. Consente di usare strumenti uniformi e modi standard di routing e gestione degli eventi.

Modalità contenuto CloudEvents

La specifica CloudEvents definisce tre modalità di contenuto: binaria, strutturata e in batch.

Importante

Con qualsiasi modalità di contenuto è possibile scambiare dati evento testuali (JSON, text/*, ecc.) o codificati in formato binario. La modalità di contenuto binaria non viene usata esclusivamente per l'invio di dati binari.

Le modalità di contenuto non riguardano la codifica usata, binaria o testuale, ma il modo in cui i dati dell'evento e i relativi metadati vengono descritti e scambiati. La modalità di contenuto strutturata usa una singola struttura, ad esempio un oggetto JSON, in cui sia gli attributi di contesto che i dati evento si trovano nel payload HTTP. La modalità di contenuto binaria separa gli attributi di contesto, di cui viene eseguito il mapping alle intestazioni HTTP, e i dati evento, ovvero il payload HTTP codificato in base al tipo di supporto impostato in Content-Type.

Supporto di CloudEvents

Questa tabella illustra il supporto corrente per la specifica CloudEvents:

Modalità contenuto CloudEvents Supportato?
JSON strutturato Sì
JSON strutturato in batch Sì, per la pubblicazione di eventi
Binario Sì, per la pubblicazione di eventi

La dimensione massima consentita per un evento è 1 MB. Gli eventi superiori a 64 KB vengono addebitati in incrementi di 64 KB.

Modalità contenuto strutturato

Un messaggio in modalità contenuto strutturato CloudEvents include sia gli attributi di contesto che i dati dell'evento in un payload HTTP.

Importante

Attualmente Griglia di eventi supporta il formato JSON CloudEvents con HTTP.

Ecco un esempio di CloudEvents in modalità strutturata usando il formato JSON. Entrambi i metadati (tutti gli attributi che non sono "dati") e i dati di messaggio/evento (l'oggetto "dati") vengono descritti in JSON. L'esempio include tutti gli attributi di contesto obbligatori insieme ad alcuni attributi facoltativi (subject, time e datacontenttype) e attributi di estensione (comexampleextension1, comexampleothervalue).

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "subject" : "O-28964",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "comexampleextension1" : "value",
    "comexampleothervalue" : 5,
    "datacontenttype" : "application/json",
    "data" : {
       "orderId" : "O-28964",
       "URL" : "https://com.yourcompany/orders/O-28964"
    }
}

È possibile usare il formato JSON con contenuto strutturato per inviare dati dell'evento che non sono un valore JSON. A tale scopo, seguire questa procedura:

  1. Includere un attributo datacontenttype con il tipo di supporto in cui vengono codificati i dati.
  2. Se il tipo di supporto è codificato in un formato di testo come text/plain, text/csv o application/xml, è consigliabile usare un attributo data con una stringa JSON contenente ciò che si sta comunicando come valore.
  3. Se il tipo di supporto rappresenta una codifica binaria, è necessario usare un attributo data_base64 il cui valore è una stringa JSON contenente il valore binario con codifica BASE64.

Ad esempio, questo CloudEvent contiene i dati dell'evento codificati in application/protobuf per scambiare messaggi Protobuf.

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "datacontenttype" : "application/protobuf",
    "data_base64" : "VGhpcyBpcyBub3QgZW5jb2RlZCBpbiBwcm90b2J1ZmYgYnV0IGZvciBpbGx1c3RyYXRpb24gcHVycG9zZXMsIGltYWdpbmUgdGhhdCBpdCBpcyA6KQ=="
}

Per altre informazioni sull'uso degli attributi data o data_base64, vedere Gestione dei dati.

Per altre informazioni su questa modalità di contenuto, vedere le specifiche della modalità contenuto strutturato HTTP di CloudEvents.

Modalità contenuto in batch

Griglia di eventi supporta attualmente la modalità contenuto in batch JSON durante la pubblicazione di CloudEvent in Griglia di eventi. Questa modalità di contenuto usa una matrice JSON riempita con CloudEvent in modalità contenuto strutturato. Ad esempio, l'applicazione può pubblicare due eventi usando una matrice simile alla seguente. Analogamente, se si usa l'SDK del piano dati di Griglia di eventi, questo payload è anche ciò che viene inviato:

[
    {
        "specversion": "1.0",
        "id": "E921-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": "some data"
    },
    {
        "specversion": "1.0",
        "id": "F555-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": {
            "somekey" : "value",
            "someOtherKey" : 9
        }
    }
]

Per altre informazioni, vedere le specifiche della modalità contenuto in batch di CloudEvents.

Batch

L'applicazione deve raggruppare in batch più eventi in una matrice per ottenere una maggiore efficienza e una maggiore velocità effettiva con una singola richiesta di pubblicazione. I batch possono avere fino a 1 MB e la dimensione massima di un evento è di 1 MB.

Modalità contenuto binario

Un CloudEvent in modalità contenuto binario ha i relativi attributi di contesto descritti come intestazioni HTTP. I nomi delle intestazioni HTTP corrispondono al nome dell'attributo di contesto preceduto dal suffisso ce-. L'intestazione Content-Type riflette il tipo di supporto in cui vengono codificati i dati dell'evento.

Importante

Quando si usa la modalità di contenuto binario, anche l'intestazione HTTP ce-datacontenttype NON DEVE essere presente.

Importante

Se si prevede di includere attributi personalizzati (ovvero attributi di estensione) quando si usa la modalità di contenuto binario, assicurarsi che i nomi siano costituiti da lettere minuscole (dalla "a" alla "z") o cifre (da "0" a "9") del carattere ASCII e che non superino i 20 caratteri. Ovvero, la convenzione di denominazione per la denominazione degli attributi di contesto CloudEvents è più restrittiva rispetto a quella dei nomi di intestazione HTTP validi. Non tutti i nomi di intestazione HTTP validi sono un nome di attributo di estensione valido.

Il payload HTTP corrisponde ai dati dell'evento codificati in base al tipo di supporto in Content-Type.

Una richiesta HTTP usata per pubblicare un CloudEvent in modalità binaria del contenuto può essere simile all'esempio seguente:

POST / HTTP/1.1
HOST mynamespace.eastus-1.eventgrid.azure.net/topics/mytopic
ce-specversion: 1.0
ce-type: com.example.someevent
ce-source: /mycontext
ce-id: A234-1234-1234
ce-time: 2018-04-05T17:31:00Z
ce-comexampleextension1: value
ce-comexampleothervalue: 5
content-type: application/protobuf

Binary data according to protobuf encoding format. No context attributes are included.

Quando usare la modalità di contenuto binario o di contenuto strutturato di CloudEvents

È possibile usare la modalità contenuto strutturato se si vuole un approccio semplice per l'inoltro di CloudEvents tra hop e protocolli. Poiché un CloudEvent in modalità contenuto strutturato contiene il messaggio insieme ai relativi metadati, per i client è facile utilizzarlo nel suo complesso e inoltrarlo ad altri sistemi.

È possibile usare la modalità contenuto binario se si è a conoscenza che le applicazioni downstream richiedono solo il messaggio senza informazioni aggiuntive (ovvero gli attributi di contesto). Anche se con la modalità contenuto strutturato è comunque possibile ottenere i dati dell'evento (messaggio) dal CloudEvent, è più semplice se un'applicazione consumer li contenga solo nel payload HTTP. Ad esempio, altre applicazioni possono usare altri protocolli e potrebbero essere interessate solo al messaggio principale, non ai relativi metadati. Infatti, i metadati potrebbero essere rilevanti solo per il primo hop immediato. In questo caso, avere i dati che si desidera scambiare oltre ai relativi metadati comporta una gestione e un inoltro più semplici.

Contenuto correlato