Espaces de noms Azure Event Grid – Prise en charge du schéma CloudEvents

Les rubriques d’espace de noms Event Grid acceptent les événements conformes à la spécification CloudEvents 1.0 standard ouverte de la Cloud Native Computing Foundation (CNCF) à l’aide de la liaison de protocole HTTP avec le format JSON. Un CloudEvent est un type de message qui contient ce qui est communiqué, que l’on appelle données d’événement, ainsi que des métadonnées à son sujet. Les données d’événement dans les architectures pilotées par les événements portent généralement les informations annonçant une modification d’état système. Les métadonnées CloudEvents sont composées d’un ensemble d’attributs qui fournissent des informations contextuelles sur le message, comme son origine (le système source), son type, etc. Tous les messages valides respectant les spécifications CloudEvents doivent inclure les attributs de contexte requis suivants :

• id
• source
• specversion
• type

La spécification CloudEvents définit également des attributs facultatifs et de contexte d’extension que vous pouvez inclure lors de l’utilisation d’Event Grid.

Lors de l’utilisation d’Event Grid, CloudEvents est le format d’événement préféré en raison de ses cas d’usage bien documentés (modes de transfert d’événements, formats d’événements, etc.), de son extensibilité et de son interopérabilité améliorée. CloudEvents améliore l’interopérabilité en proposant un format d’événement commun pour la publication et la consommation des événements. Il permet des méthodes standards de routage et des outils uniformes qui gèrent des événements.

Modes de contenu CloudEvents

La spécification CloudEvents définit trois modes de contenu : binaire, structuré et par lots.

Les modes de contenu ne concernent pas l’encodage que vous utilisez, binaire ou texte, mais la façon dont les données d’événement et leurs métadonnées sont décrites et échangées. Le mode de contenu structuré utilise une structure unique, par exemple un objet JSON, où les attributs de contexte et les données d’événement sont regroupés dans la charge utile HTTP. Le mode de contenu binaire sépare les attributs de contexte, qui sont mappés aux en-têtes HTTP, et les données d’événement, qui correspondent à la charge utile HTTP encodée en fonction du type de média défini dans Content-Type.

Prise en charge de CloudEvents

Ce tableau indique la prise en charge actuelle de la spécification CloudEvents :

La taille maximale autorisée pour un événement est de 1 Mo. Les événements de plus de 64 Ko donnent lieu à une facturation par incréments de 64 Ko.

Mode de contenu structuré

Un message en mode de contenu structuré CloudEvents dispose à la fois des attributs de contexte et des données d’événement regroupés dans une charge utile HTTP.

Voici un exemple de CloudEvents en mode structuré à l’aide du format JSON. Les métadonnées (tous les attributs qui ne sont pas des « données ») et les données de message/événement (l’objet de « données ») sont toutes décrites à l’aide de JSON. Notre exemple inclut tous les attributs de contexte requis, ainsi que certains attributs facultatifs (subject, time et datacontenttype) et les attributs d’extension (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"
    }
}

Vous pouvez utiliser le format JSON avec du contenu structuré pour envoyer des données d’événement qui ne sont pas représentées par une valeur JSON. Pour ce faire, procédez comme suit :

1. Incluez un attribut datacontenttype avec le type de média dans lequel les données sont encodées.
2. Si le type de média est encodé dans un format de texte tel que text/plain, text/csv ou application/xml, vous devez utiliser un attribut data avec une chaîne JSON contenant ce que vous communiquez en tant que valeur.
3. Si le type de média représente un encodage binaire, vous devez utiliser un attribut data_base64 dont la valeur est une chaîne JSON contenant la valeur binaire codée en BASE64.

Par exemple, ce CloudEvent transporte les données d’événement encodées dans application/protobuf pour échanger des messages 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=="
}

Pour plus d’informations sur l’utilisation des attributs data ou data_base64, consultez Gestion des données.

Pour plus d’informations sur ce mode de contenu, consultez la documentation de CloudEvents sur les spécifications du mode de contenu structuré HTTP.

Mode de contenu par lots

Event Grid prend actuellement en charge le mode de contenu par lots JSON lors de la publication de CloudEvents sur Event Grid. Ce mode de contenu utilise un tableau JSON rempli de CloudEvents en mode de contenu structuré. Par exemple, votre application peut publier deux événements à l’aide d’un tableau comme suit. De même, si vous utilisez le SDK de plan de données d’Event Grid, cette charge utile est également ce qui est envoyé :

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

Pour plus d’informations, consultez les spécifications de mode de contenu par lots de CloudEvents.

Traitement par lots

Votre application doit regrouper plusieurs événements dans un tableau afin d’obtenir une plus grande efficacité et un débit plus élevé avec une seule demande de publication. Les lots peuvent comporter jusqu’à 1 Mo. La taille maximale d’un événement est de 1 Mo.

Mode de contenu binaire

Un CloudEvent en mode de contenu binaire a ses attributs de contexte décrits en tant qu’en-têtes HTTP. Les noms des en-têtes HTTP sont le nom de l’attribut de contexte précédé de ce-. L’en-tête Content-Type reflète le type de média dans lequel les données d’événement sont encodées.

La charge utile HTTP représente les données d’événement encodées en fonction du type de média dans Content-Type.

Une requête HTTP utilisée pour publier un CloudEvent en mode de contenu binaire peut ressembler à cet exemple :

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.

Quand utiliser le mode de contenu binaire ou structuré de CloudEvents

Vous pouvez utiliser le mode de contenu structuré si vous souhaitez une approche simple pour transférer des CloudEvents entre tronçons et protocoles. Étant donné qu’un CloudEvent en mode de contenu structuré contient le message et ses métadonnées, il est facile pour les clients de l’utiliser dans son ensemble et de le transférer vers d’autres systèmes.

Vous pouvez utiliser le mode de contenu binaire si vous savez que les applications en aval nécessitent uniquement le message sans aucune information supplémentaire (autrement dit, les attributs de contexte). Bien qu’avec le mode de contenu structuré, vous pouvez toujours récupérer les données d’événement (message) hors du CloudEvent, cela est plus facile si une application grand public a simplement le message dans la charge utile HTTP. Par exemple, d’autres applications peuvent utiliser des protocoles différents et peuvent s’intéresser uniquement à votre message principal, et non à ses métadonnées. En fait, les métadonnées peuvent être pertinentes uniquement pour le premier tronçon immédiat. Dans ce cas, disposer des données que vous souhaitez échanger sans ses métadonnées se prête à une gestion et à un transfert plus faciles.

Contenu connexe

• Pour une présentation d’Event Grid, consultez À propos d’Event Grid.
• Pour commencer à utiliser des rubriques d’espace de noms, reportez-vous aux événements de publication à l’aide des rubriques d’espace de noms.