Delen via

Azure Event Grid-naamruimten - ondersteuning voor CloudEvents-schema

  • Artikel

Event Grid-naamruimteonderwerpen accepteren gebeurtenissen die voldoen aan de Open Standard CloudEvents 1.0-specificatie van CloudEvents (CloudEvents) van De Cloud Native Computing Foundation (CNCF) met behulp van de HTTP-protocolbinding met JSON-indeling. Een CloudEvent is een soort bericht dat bevat wat er wordt gecommuniceerd, aangeduid als gebeurtenisgegevens en metagegevens. De gebeurtenisgegevens in gebeurtenisgestuurde architecturen bevatten doorgaans de informatie die een wijziging van de systeemstatus aankondigt. De metagegevens van CloudEvents bestaan uit een set kenmerken die contextuele informatie bieden over het bericht, zoals waar het afkomstig is (het bronsysteem), het type, enzovoort. Alle geldige berichten die voldoen aan de specificaties van CloudEvents, moeten de volgende vereiste contextkenmerken bevatten:

De CloudEvents-specificatie definieert ook optionele en extensiecontextkenmerken die u kunt opnemen bij het gebruik van Event Grid.

Wanneer u Event Grid gebruikt, is CloudEvents de voorkeursgebeurtenisindeling vanwege de goed gedocumenteerde gebruiksvoorbeelden (modi voor het overdragen van gebeurtenissen, gebeurtenisindelingen, enzovoort), uitbreidbaarheid en verbeterde interoperabiliteit. CloudEvents verbetert de interoperabiliteit door een algemene gebeurtenisindeling te bieden voor het publiceren en gebruiken van gebeurtenissen. Het biedt uniforme tooling en standaard manieren om gebeurtenissen te routeren en te verwerken.

CloudEvents con tentmodus s

De specificatie CloudEvents definieert drie con tentmodus s: binair, gestructureerd en gebatcheerd.

Belangrijk

Met elke con tentmodus kunt u tekst (JSON, text/*, enzovoort) of binaire-gecodeerde gebeurtenisgegevens uitwisselen. De binaire con tentmodus wordt niet uitsluitend gebruikt voor het verzenden van binaire gegevens.

De con tentmodus s gaan niet over de codering die u gebruikt, binair of tekst, maar over hoe de gebeurtenisgegevens en metagegevens worden beschreven en uitgewisseld. De gestructureerde con tentmodus maakt gebruik van één structuur, bijvoorbeeld een JSON-object, waarbij zowel de contextkenmerken als gebeurtenisgegevens zich in de HTTP-nettolading bevinden. De binaire con tentmodus scheidt contextkenmerken, die zijn toegewezen aan HTTP-headers en gebeurtenisgegevens, wat de HTTP-nettolading is gecodeerd volgens het mediatype dat is ingesteld in Content-Type.

CloudEvents-ondersteuning

In deze tabel ziet u de huidige ondersteuning voor CloudEvents-specificatie:

CloudEvents con tentmodus Ondersteund?
Gestructureerde JSON Ja
Gestructureerde JSON-batched Ja, voor het publiceren van gebeurtenissen
Binair Ja, voor het publiceren van gebeurtenissen

De maximale toegestane grootte voor een gebeurtenis is 1 MB. Gebeurtenissen van meer dan 64 kB worden in rekening gebracht in stappen van 64 kB.

Gestructureerde con tentmodus

Een bericht in CloudEvents structured con tentmodus heeft zowel de contextkenmerken als de gebeurtenisgegevens samen in een HTTP-nettolading.

Belangrijk

Momenteel ondersteunt Event Grid de JSON-indeling CloudEvents met HTTP.

Hier volgt een voorbeeld van een CloudEvents in de gestructureerde modus met behulp van de JSON-indeling. Beide metagegevens (alle kenmerken die geen 'gegevens' zijn) en de bericht-/gebeurtenisgegevens (het 'gegevensobject') worden beschreven met behulp van JSON. Ons voorbeeld bevat alle vereiste contextkenmerken, samen met enkele optionele kenmerken (subject, timeen ) en datacontenttypeextensiekenmerken (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"
    }
}

U kunt de JSON-indeling met gestructureerde inhoud gebruiken om gebeurtenisgegevens te verzenden die geen JSON-waarde zijn. Daartoe voert u de volgende stappen uit:

  1. Voeg een datacontenttype kenmerk toe aan het mediatype waarin de gegevens worden gecodeerd.
  2. Als het mediatype is gecodeerd in een tekstindeling zoals text/plain, text/csvof application/xml, moet u een data kenmerk gebruiken met een JSON-tekenreeks die bevat wat u als waarde communiceert.
  3. Als het mediatype een binaire codering vertegenwoordigt, moet u een data_base64 kenmerk gebruiken waarvan de waarde een JSON-tekenreeks is die de binaire waarde base64 bevat.

Deze CloudEvent bevat bijvoorbeeld gebeurtenisgegevens die zijn gecodeerd application/protobuf om Protobuf-berichten uit te wisselen.

{
    "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=="
}

Zie De verwerking van gegevens voor meer informatie over het gebruik van de data of data_base64 kenmerken.

Zie de specificaties van CloudEvents HTTP structured con tentmodus voor meer informatie over deze con tentmodus.

Batched con tentmodus

Event Grid ondersteunt momenteel de JSON-batched con tentmodus bij het publiceren van CloudEvents naar Event Grid. Deze con tentmodus maakt gebruik van een JSON-matrix die is gevuld met CloudEvents in structured con tentmodus. Uw toepassing kan bijvoorbeeld twee gebeurtenissen publiceren met behulp van een matrix zoals hieronder. Als u ook de SDK voor het gegevensvlak van Event Grid gebruikt, wordt deze nettolading ook verzonden:

[
    {
        "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
        }
    }
]

Zie CloudEvents Batched Content Mode-specificaties voor meer informatie.

Batching

Uw toepassing moet verschillende gebeurtenissen samenvoegen in een matrix om een grotere efficiëntie en hogere doorvoer te bereiken met één publicatieaanvraag. Batches kunnen maximaal 1 MB zijn en de maximale grootte van een gebeurtenis is 1 MB.

Binaire con tentmodus

Een CloudEvent in binaire con tentmodus heeft de contextkenmerken die worden beschreven als HTTP-headers. De namen van de HTTP-headers zijn de naam van het contextkenmerk met het voorvoegsel ce-. De Content-Type header weerspiegelt het mediatype waarin de gebeurtenisgegevens worden gecodeerd.

Belangrijk

Wanneer u de binaire con gebruikt tentmodus mag de ce-datacontenttype HTTP-header niet ook aanwezig zijn.

Belangrijk

Als u van plan bent om uw eigen kenmerken (d.w.z. extensiekenmerken) op te nemen bij het gebruik van de binaire con tentmodus, moet u ervoor zorgen dat de namen bestaan uit kleine letters ('a' tot 'z') of cijfers ('0' tot '9') van het ASCII-teken en dat ze niet langer zijn dan 20 tekens. Dat wil gezegd, de naamconventie voor het benoemen van contextkenmerken van CloudEvents is meer beperkend dan die van geldige HTTP-headernamen. Niet elke geldige HTTP-headernaam is een geldige naam van het extensiekenmerk.

De HTTP-nettolading is de gebeurtenisgegevens die zijn gecodeerd volgens het mediatype in Content-Type.

Een HTTP-aanvraag die wordt gebruikt voor het publiceren van een CloudEvent in de binaire inhoudsmodus, kan er als volgt uitzien:

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.

Wanneer gebruikt u de binaire of gestructureerde con van CloudEvents tentmodus

U kunt gestructureerde con tentmodus gebruiken als u een eenvoudige benadering wilt voor het doorsturen van CloudEvents tussen hops en protocollen. Omdat een CloudEvent in structured con tentmodus het bericht samen met de metagegevens bevat, is het voor clients eenvoudig om het als geheel te gebruiken en door te sturen naar andere systemen.

U kunt binaire con tentmodus als u weet dat downstreamtoepassingen alleen het bericht vereisen zonder extra informatie (dat wil zeggen de contextkenmerken). Hoewel u met structured con tentmodus de gebeurtenisgegevens (bericht) nog steeds kunt ophalen uit CloudEvent, is het eenvoudiger als een consumententoepassing deze alleen in de HTTP-nettolading heeft. Andere toepassingen kunnen bijvoorbeeld andere protocollen gebruiken en zijn mogelijk alleen geïnteresseerd in uw kernbericht, niet de metagegevens ervan. De metagegevens kunnen zelfs relevant zijn voor de onmiddellijke eerste hop. In dit geval zijn de gegevens die u wilt uitwisselen, afgezien van de metagegevens, geschikt voor eenvoudigere verwerking en doorsturen.

Gerelateerde inhoud