Partager via

Schéma d’événement Azure Event Grid

  • Article

Cet article décrit le schéma Event Grid, qui est un format d’événement propriétaire, non extensible, mais entièrement fonctionnel. Event Grid prend toujours en charge ce format d’événement et continuera de le prendre en charge. Toutefois, CloudEvents est le format d’événement recommandé à utiliser. Si vous utilisez des applications qui utilisent le format Event Grid, vous trouverez peut-être des informations utiles dans la section [CloudEvents] qui décrit les transformations entre le format Event Grid et CloudEvents pris en charge par Event Grid.

Cet article décrit en détail les propriétés et le schéma du format Event Grid. Les événements sont un ensemble de quatre propriétés de chaîne requises. Les propriétés sont communes à tous les événements, quel que soit le serveur de publication. L’objet de données a des propriétés spécifiques à chaque serveur de publication. Dans les rubriques du système, ces propriétés sont spécifiques au fournisseur de ressources tel que Stockage Azure ou Azure Event Hubs.

Les sources d’événements envoient des événements à Azure Event Grid dans un tableau qui peut avoir plusieurs objets d’événement. Quand les événements sont envoyés vers une rubrique Event Grid, le tableau peut avoir une taille totale de 1 Mo. Chaque événement du tableau est limité à 1 Mo. Si un événement ou si le tableau dépasse la taille maximale autorisée, vous recevez le message suivant : 413 Payload Too Large (413 : charge utile maximale dépassée). Toutefois, les opérations sont facturées par incréments de 64 Ko. Ainsi, les événements de plus de 64 Ko entraînent des frais d’opération comme s’il s’agissait de plusieurs événements. Par exemple, un événement d’une taille de 130 Ko entraîne des opérations équivalents à trois événements distincts.

Event Grid envoie les événements aux abonnés sous forme de tableau ne contenant qu’un seul événement. Ce comportement peut changer à l’avenir.

Vous trouverez le schéma JSON pour l’événement Event Grid et la charge utile des données de chaque serveur de publication Azure dans le magasin de schémas d’événement.

Remarque

La prise en charge du schéma d’événements Event Grid ne sera pas supprimée, mais nous n’apporterons pas d’améliorations majeures à l’avenir. Nous vous recommandons d’utiliser le schéma CloudEvents, qui fournit une définition standardisée et indépendante du protocole de la structure et de la description des métadonnées des événements. Pour plus d’informations, consultez le schéma CloudEvents v1.0 avec Azure Event Grid.

Schéma d’événement

L’exemple suivant montre les propriétés qui sont utilisées par tous les éditeurs d’événements :

[
  {
    "topic": string,
    "subject": string,
    "id": string,
    "eventType": string,
    "eventTime": string,
    "data":{
      object-unique-to-each-publisher
    },
    "dataVersion": string,
    "metadataVersion": string
  }
]

Par exemple, voici le schéma publié pour un événement de stockage Blob Azure :

[
  {
    "topic": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contosorg/providers/Microsoft.Storage/storageAccounts/contosostorage",
    "subject": "/blobServices/default/containers/testcontainer/blobs/dataflow.jpg",
    "eventType": "Microsoft.Storage.BlobCreated",
    "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "data": {
      "api": "PutBlob",
      "clientRequestId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "requestId": "cccccccc-2222-3333-4444-dddddddddddd",
      "eTag": "0x8DD15A69488FE5A",
      "contentType": "image/jpeg",
      "contentLength": 52577,
      "blobType": "BlockBlob",
      "accessTier": "Default",
      "url": "https://contosostorage.blob.core.windows.net/testcontainer/dataflow.jpg",
      "sequencer": "0000000000000000000000000003A13C00000000007da85d",
      "storageDiagnostics": {
        "batchId": "9d292d9f-e006-00a5-008f-47b300000000"
      }
    },
    "dataVersion": "",
    "metadataVersion": "1",
    "eventTime": "2024-12-06T03:32:15.7238874Z"
  }
]

Propriétés d’événement

Tous les événements contiennent les mêmes données de supérieur suivantes :

Propriété Type Requise Description
topic string Non, mais s’il est inclus, il doit correspondre exactement à l’ID Azure Resource Manager de la rubrique Event Grid. S’il n’est pas inclus, Event Grid applique une empreinte sur l’événement. Chemin d’accès complet à la source de l’événement. Ce champ n’est pas modifiable. Event Grid fournit cette valeur.
subject string Oui Chemin de l’objet de l’événement, défini par le serveur de publication.
eventType string Oui Un des types d’événements inscrits pour cette source d’événement.
eventTime string Oui L’heure à quelle l’événement est généré selon l’heure UTC du fournisseur.
id string Oui Identificateur unique de l’événement.
data object Oui Données d’événement spécifiques au fournisseur de ressources.
dataVersion string Non, mais sera marqué avec une valeur vide. Version du schéma de l’objet de données. Le serveur de publication définit la version du schéma.
metadataVersion string Non obligatoire, mais s’il est inclus, il doit correspondre exactement au schéma Event Grid metadataVersion (actuellement, uniquement 1). S’il n’est pas inclus, Event Grid applique une empreinte sur l’événement. Version du schéma des métadonnées d’événement. Event Grid définit le schéma des propriétés de niveau supérieur. Event Grid fournit cette valeur.

Pour en savoir plus sur les propriétés de l’objet de données, consultez les articles de cette section : Rubriques système.

Pour les rubriques personnalisées, l’éditeur d’événements détermine l’objet de données. Les données de niveau supérieur doivent avoir les mêmes champs que des événements standard définis par les ressources.

Lorsque vous publiez des événements dans des rubriques personnalisées, créez des objets pour vos événements permettant aux abonnés de savoir facilement si l’événement les intéresse. Les abonnés utilisent l’objet pour filtrer et router des événements. Envisagez de fournir le chemin d’accès à l’origine de l’événement, de sorte que les abonnés puissent filtrer par segments de ce chemin d’accès. Le chemin d’accès permet aux abonnés de filtrer les événements avec précision ou à grande échelle. Par exemple, si vous fournissez un chemin d’accès de trois segments comme /A/B/C dans l’objet, les abonnés peuvent filtrer par le premier segment /A pour obtenir un vaste ensemble d’événements. Ces abonnés obtiennent des événements avec des objets tels que /A/B/C ou /A/D/E. Les autres abonnés peuvent filtrer par /A/B pour obtenir un ensemble plus restreint d’événements.

Votre objet a parfois besoin d’être plus précis sur ce qui est arrivé. Par exemple, le serveur de publication Comptes de stockage fournit l’objet /blobServices/default/containers/<container-name>/blobs/<file> lorsqu’un fichier est ajouté à un conteneur. Un abonné peut filtrer par le chemin d’accès /blobServices/default/containers/<container-name>/ pour obtenir tous les événements pour ce conteneur, mais pas pour d’autres conteneurs du compte de stockage. Un abonné peut également filtrer ou router par le suffixe .txt pour n’utiliser que des fichiers texte.

CloudEvents

CloudEvents est le format d’événement recommandé à utiliser. Azure Event Grid continue d’investir dans des fonctionnalités liées au format JSON CloudEvents au moins. Étant donné que certaines sources d’événements comme les services Azure utilisent le format Event Grid, le tableau suivant vous permet de comprendre la transformation prise en charge lors de l’utilisation des formats CloudEvents et Event Grid comme schéma d’entrée dans les rubriques et comme schéma de sortie dans les abonnements aux événements. Un schéma de sortie Event Grid ne peut pas être utilisé lors de l’utilisation de CloudEvents comme schéma d’entrée, car CloudEvents prend en charge les attributs d’extension qui ne sont pas pris en charge par le schéma Event Grid.

Schéma d’entrée Schéma de sortie
Format CloudEvents Format CloudEvents
Format Event Grid Format CloudEvents
Format Event Grid Format Event Grid

Étapes suivantes