Pour connecter deux applications différentes, vous pouvez utiliser des Webhooks. En utilisant des webhooks, vous pouvez configurer des notifications d'événements.
Un Webhook est un rappel HTTP. Lorsqu'un événement se produit, une application Web implémentant des Webhooks diffuse des données sur cet événement et les envoie à une URL Webhook à partir de l'application dont vous souhaitez recevoir les informations. Pour plus d'informations, reportez-vous à Cloud Developer Platform.
Dans le contexte de VMware Cloud Director, vous pouvez configurer des Webhooks à l'aide de comportements Webhook. Les comportements Webhook envoient une demande POST à un serveur Webhook distant. Le corps de la demande contient des informations sur l'appel de comportement et l'entité sur laquelle le comportement a été appelé. Vous pouvez également personnaliser le corps en utilisant un modèle. La réponse du serveur Webhook détermine le résultat de la tâche d'appel de comportement. Le serveur peut renvoyer trois types de réponses.
Le serveur Webhook distant peut être n'importe quel serveur accessible par VMware Cloud Director. Cependant, avant de créer un comportement de Webhook, vous devez vérifier que le point de terminaison du Webhook est sécurisé.
- Vérifiez que le point de terminaison Webhook est un point de terminaison HTTPS.
- Vérifiez que l'organisation de l'utilisateur qui appelle le comportement approuve le certificat du serveur Webhook. Cela signifie que même si le certificat est présent dans un magasin d'approbations VMware Cloud Director, si l'organisation de l'utilisateur qui appelle le comportement n'approuve pas le certificat, le comportement Webhook ne s'exécutera pas.
- Vous pouvez ajouter un certificat au magasin d'approbations à l'aide de l'interface utilisateur ou de l'API VMware Cloud Director. Reportez-vous à la section Gestion des certificats à l'aide de VMware Cloud Director.
Création de comportements Webhook
"POST https"://host/cloudapi/1.0.0/interfaces/<interface_id>/behaviors{ "name":"webhookBehavior", "execution":{ "type":"WebHook", "id":"testWebHook", "href":"https://hooks.slack.com:443/services/T07UZFN0N/B01EW5NC42D/rfjhHCGIwzuzQFrpPZiuLkIX", "key":"secretKey", "execution_properties":{ "template":{ "content":"<template_content_string>" }, "_secure_token":"secureToken", "invocation_timeout":7 } } }
Champ | Description |
---|---|
type |
Champ requis. Doit être WebHook . |
id |
Champ de chaîne facultatif. |
href |
Champ obligatoire pour l'URL qui doit recevoir les demandes de VMware Cloud Director. |
_internal_key |
Champ obligatoire pour le secret partagé utilisé pour signer les demandes envoyées au point de terminaison Webhook. |
invocation_timeout |
Champ facultatif spécifiant le délai d'expiration en secondes pour la réponse du serveur Webhook |
template.content |
Champ facultatif pour la personnalisation de la charge utile envoyée au serveur Webhook. Vous pouvez fournir un modèle sous forme de chaîne. Vous pouvez ajouter d'autres champs à execution_properties , accessible au modèle. |
_secure_ |
Les champs ayant le préfixe _secure_ sont facultatifs. Les champs sont en écriture seule et ne peuvent pas être obtenus via une demande GET sur le comportement. La valeur du champ est chiffrée avant d'être enregistrée dans la base de données VMware Cloud Director. Les champs sont accessibles au modèle. |
Charge utile de VMware Cloud Director vers le serveur Webhook
Il existe un format par défaut de la charge utile envoyée au serveur Webhook. Vous pouvez également personnaliser la charge utile à l'aide d'un modèle.
{ "entityId":"urn:vcloud:entity:vmware:test_entity_type:b95d96ec-c294-4a64-b5c4-9009abe6ab06", "typeId":"urn:vcloud:type:vmware:test_entity_type:1.0.0", "arguments":{ "x":7 }, "_metadata":{ "executionId":"testWebHook", "execution":{ "href":"https://webhook.site/3ca4588f-c9f1-4c0f-911f-734ab598b2dc" }, "invocation":{ }, "apiVersion":"36.0", "behaviorId":"urn:vcloud:behavior-interface:webhookBehavior:vmware:test_interface_3:1.0.0", "requestId":"8312df21-712c-4b85-86d4-c9b00669662f", "executionType":"WebHook", "invocationId":"115c5b99-09e8-44f7-8189-4b9d96e067b1", "taskId":"a9e0556b-7699-4ded-b56b-c51fee659008" }, "entity":{ "cluster":{ "name":"testCluster0" }, "clusterState":{ "host":"testHost", "status":"valid" } } }
Pour les charges utiles personnalisées avec un modèle vous pouvez spécifier un modèle pour la charge utile envoyée au serveur Webhook. Si vous ne spécifiez pas de modèle, VMware Cloud Director envoie la charge utile de demande par défaut au serveur Webhook. Le moteur de modèle Apache FreeMarker restaure la charge utile à partir du modèle fourni et du modèle de données.
+ - entityId | + - typeId | + - arguments | + - arguments_string | + - _execution_properties | + - _metadata | | | + - executionId | + - behaviorId | + - executionType | + - taskId | + - execution | | | | | + - href | + - invocation | + - invocationId | + - requestId | + - apiVersion | + - entity | + - entity_string
Argument | Description |
---|---|
entityId |
ID de l'entité définie appelée. |
typeId |
ID du type d'entité de l'entité définie appelée. |
arguments |
Arguments transmis dans l'appel de comportement. |
arguments_string |
Chaîne d'arguments au format JSON. Vous pouvez l'utiliser si vous souhaitez ajouter tous les arguments à la charge utile. |
_execution_properties |
Vous pouvez sélectionner toutes les valeurs à partir de l'argument d'appel de execution_properties par nom de clé. |
execution |
Vous pouvez sélectionner toutes les valeurs à partir de l'argument d'appel de execution par nom de clé. |
invocation |
Vous pouvez sélectionner toutes les valeurs à partir de l'argument invocation par nom de clé. |
entity |
Carte du contenu de l'entité. Vous pouvez sélectionner toutes les valeurs de l'entité par nom de clé. |
entity_string |
Chaîne au format JSON de l'entité. |
Pour plus d'informations sur le langage d'expression Apache FreeMarker pour le modèle de la charge utile, reportez-vous à la page https://freemarker.apache.org/docs/dgui_quickstart_template.html.
<#assign header_Content\-Type= "application/json" /> { "text": "Behavior with id ${_metadata.behaviorId} was executed on entity with id ${entityId}" }
header_
. Par exemple, vous pouvez spécifier la valeur de l'en-tête
Authorization
en ajoutant la ligne suivante au modèle :
<#assign header_Authorization = "${_execution_properties._secure_token}" />
Charge utile du serveur Webhook vers VMware Cloud Director
- Réponse par défaut
La charge utile par défaut du serveur Webhook vers VMware Cloud Director doit contenir les éléments suivants.
- La réponse peut ne pas avoir d'en-tête
Content-Type
ou un en-têteContent-Type
avec la valeurtext/plain
. - Le corps de la réponse doit être une chaîne.
- Le corps de la réponse est utilisé comme résultat de l'appel de comportement. L'état de la tâche d'appel de comportement est
success
. Le résultat de la tâche est défini sur le corps de la réponse.
- La réponse peut ne pas avoir d'en-tête
- Réponse de mise à jour de tâche unique
Outre le résultat du comportement, la réponse de mise à jour de la tâche peut définir d'autres propriétés de tâche d'invocation de comportement, telles que
status
,details
,operation
,error
,progress
etresult
. Il s'agit d'une mise à jour de tâche ponctuelle. La réponse doit terminer la tâche. Si la réponse ne définit pas l'état de la tâche sursuccess
,error
ouaborted
, la tâche échoue avec une erreur. Le message d'erreur indique que l'état n'était pas acceptable.- La réponse doit avoir un en-tête
Content-Type
avec la valeurapplication/vnd.vmware.vcloud.task+json
. - Le corps de la réponse doit contenir une représentation JSON de la classe
TaskType
contenant les propriétés de la tâche que vous souhaitez modifier. - Exemple de corps de réponse avec l'état
success
:{ "status":"success", "details":"example details", "operation":"example operation", "progress":100, "result":{ "resultContent":"example result" } }
- Exemple de corps de réponse avec l'état
error
:{ "status":"error", "details":"example details", "operation":"example operation", "progress":50, "error":{ "majorErrorCode":404, "minorErrorCode":"ERROR", "message":"example error message" } }
- La réponse doit avoir un en-tête
- Réponse de mise à jour de tâche continue
Le serveur Webhook peut envoyer plusieurs mises à jour de tâches à l'aide d'une réponse HTTP en plusieurs parties. Chaque mise à jour est une partie distincte du corps de la réponse. La dernière partie du corps de la réponse du serveur Webhook doit terminer la tâche. Si le corps de la réponse ne termine pas la tâche, la tâche échoue avec une erreur.
- La réponse doit avoir un en-tête
Content-Type
avec la valeurmultipart/form-data; boundary=...
. -
Le corps de la réponse doit commencer et se terminer par une chaîne de délimitation
--<boundary_string>
. Chaque partie du corps de la réponse doit se terminer par une chaîne de limite. Vous devez spécifier la limite dans l'en-têteContent-Type
de la réponse HTTP du serveur Webhook.Headers: ... Content-Type: multipart/form-data; boundary=<boundary_string> Body: --<boundary_string> Content-Type: application/vnd.vmware.vcloud.task+json { "details": "example details", "operation": "example operation", "progress": 50 } --<boundary_string> Content-Type: application/vnd.vmware.vcloud.task+json { "status": "success", "progress": 100, "result": { "resultContent": "example result" } } --<boundary_string>
Les parties du corps de la réponse doivent être au format pour une mise à jour de tâche ou au format pour une mise à jour finale.
Exemple de mise à jour de tâche :Content-Type: application/vnd.vmware.vcloud.task+json { "details": "example details", "operation": "example operation", "progress": 50 }
Exemple de mise à jour finale :Content-Type: text/plain <string>
- La réponse doit avoir un en-tête
Authentification des demandes de comportement Webhook
L'authentification par code d'authentification de message basée sur le hachage (HMAC) sécurise les demandes de comportement Webhook. HMAC est un mécanisme qui garantit l'authenticité et l'intégrité des demandes HTTP. Pour garantir l'authenticité et l'intégrité, HMAC inclut deux en-têtes personnalisés à chaque demande HTTP. Les en-têtes personnalisés sont un en-tête de signature et un résumé. Dans VMware Cloud Director, l'en-tête de signature est x-vcloud-signature
et l'en-tête de signature est x-vcloud-digest
.
x-vcloud-signature
est un en-tête personnalisé envoyé avec chaque demande de Webhook. L'en-tête de signature se compose d'un algorithme HMACSHA512, d'en-têtes et d'une signature générée par
VMware Cloud Director. Les en-têtes affichent le contenu de la chaîne de base qui est signée pour créer la signature.
Champ | Description |
---|---|
host |
L'hôte du serveur Webhook |
date |
Date de la demande |
(request-target) |
Méthode HTTP en minuscules liées, espace ASCII et en-têtes de chemin de demande. Par exemple, post /webhook . |
digest |
Résumé SHA-512 du corps de la demande |
Pour générer l'en-tête de signature, vous avez besoin d'un secret partagé. Le secret partagé est une chaîne que seuls VMware Cloud Director et le serveur Webhook connaissent.
L'en-tête de résumé x-vcloud-digest
est un résumé SHA-512 codé en Base64 du corps de la demande.
Vous pouvez vérifier chaque demande Webhook à partir de VMware Cloud Director en générant la signature à l'aide du secret partagé et en la comparant à la signature dans l'en-tête de signature de VMware Cloud Director.
Appel des comportements Webhook
{ "arguments": { "argument1": "data1", "argument2": "data2", ... } }