Webhook-Verhaltensweisen in VMware Cloud Director

Um zwei verschiedene Anwendungen zu verbinden, können Sie Webhooks verwenden. Mithilfe von Webhooks können Sie Ereignisbenachrichtigungen einrichten.

Ein Webhook ist ein HTTP-Callback. Wenn ein Ereignis eintritt, überträgt eine Webanwendung, die Webhooks implementiert, Daten zu diesem Ereignis und sendet sie an eine Webhook-URL von der Anwendung, für die Sie die Informationen erhalten möchten. Weitere Informationen finden Sie auf der Cloud-Entwicklerplattform.

Im Kontext von VMware Cloud Director können Sie Webhooks mithilfe von Webhook-Verhaltensweisen konfigurieren. Webhook-Verhaltensweisen senden eine POST-Anforderung an einen Remote-Webhook-Server. Der Textkörper der Anforderung enthält Informationen über das Aufrufen von Verhaltensweisen und die Einheit, für die die Verhaltensweise aufgerufen wurde. Sie können den Textkörper auch mithilfe einer Vorlage anpassen. Die Antwort des Webhook-Servers bestimmt das Ergebnis der Aufrufaufgabe für die Verhaltensweise. Es gibt drei verschiedene Arten von Antworten, die der Server zurückgeben kann.

Der Remote-Webhook-Server kann jeder Server sein, den VMware Cloud Director erreichen kann. Bevor Sie jedoch eine Webhook-Verhaltensweise erstellen, müssen Sie sicherstellen, dass der Endpoint des Webhooks sicher ist.

Stellen Sie sicher, dass der Webhook-Endpoint ein HTTPS-Endpoint ist.
Stellen Sie sicher, dass die Organisation des Benutzers, der die Verhaltensweise aufruft, dem Webhook-Serverzertifikat vertraut. Dies bedeutet, dass die Webhook-Verhaltensweise auch dann nicht ausgeführt wird, wenn das Zertifikat in einem VMware Cloud Director Trust Store vorhanden ist und die Organisation des Benutzers, der die Verhaltensweise aufruft, dem Zertifikat nicht vertraut.
Sie können ein Zertifikat zum Trust Store hinzufügen, indem Sie die Benutzeroberfläche oder die VMware Cloud Director-API verwenden. Weitere Informationen finden Sie im Verwalten von Zertifikaten mithilfe von VMware Cloud Director.

Erstellen von Webhook-Verhaltensweisen

Anfrage:

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


Bereich	Beschreibung
`type`	Pflichtfeld. Muss `WebHook` sein.
`id`	Optionales Zeichenfolgenfeld.
`href`	Erforderliches Feld für die URL, die Anforderungen von VMware Cloud Director empfangen muss.
`_internal_key`	Erforderliches Feld für den gemeinsamen geheimen Schlüssel, der zum Signieren der an den Webhook-Endpoint gesendeten Anforderungen verwendet wird.
`invocation_timeout`	Optionales Feld für die Zeitüberschreitung in Sekunden für die Antwort vom Webhook-Server
`template.content`	Optionales Feld für die Anpassung der an den Webhook-Server gesendeten Nutzlast. Sie können eine Vorlage als Zeichenfolge bereitstellen. Sie können `execution_properties` weitere Felder hinzufügen, auf die die Vorlage zugreifen kann.
`_secure_`	Felder mit Präfix `_secure_` sind optional. Die Felder sind schreibgeschützt und können nicht über eine GET-Anforderung für die Verhaltensweise abgerufen werden. Der Feldwert wird verschlüsselt, bevor er in der VMware Cloud Director-Datenbank gespeichert wird. Auf die Felder kann die Vorlage zugreifen.

Nutzlast von VMware Cloud Director zum Webhook-Server

Es gibt ein Standardformat für die an den Webhook-Server gesendete Nutzlast. Sie können die Nutzlast auch mithilfe einer Vorlage anpassen.

Beispiel für Standardnutzlast:

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

Für benutzerdefinierte Nutzlasten mit einer Vorlage können Sie eine Vorlage für die an den Webhook-Server gesendete Nutzlast angeben. Wenn Sie keine Vorlage angeben, sendet VMware Cloud Director die standardmäßige Anforderungsnutzlast an den Webhook-Server. Die Apache FreeMarker-Vorlagen-Engine rendert die Nutzlast aus der bereitgestellten Vorlage und dem Datenmodell.

Das Datenmodell stellt alle für die Vorlage vorbereiteten Daten dar, d. h. alle Daten, die Sie in die Nutzlast aufnehmen können. Das Datenmodell enthält die Aufrufargumente der Webhook-Verhaltensweise, z. B. Argumente, Metadaten, Ausführungseigenschaften und Einheitsinformationen. Das folgende Beispiel zeigt die baumähnliche Struktur des Datenmodells.

+ - entityId 
|
+ - typeId 
|   
+ - arguments
|  
+ - arguments_string 
|
+ - _execution_properties 
|                      
+ - _metadata
|   |
|   + - executionId
|   + - behaviorId
|   + - executionType
|   + - taskId
|   + - execution 
|   |   |
|   |   + - href
|   + - invocation 
|   + - invocationId
|   + - requestId
|   + - apiVersion
|  
+ - entity 
|
+ - entity_string

Tabelle 1. Aufrufargumente
Argument	Beschreibung
`entityId`	ID der aufgerufenen definierten Einheit.
`typeId`	ID des Einheitstyps der aufgerufenen definierten Einheit.
`arguments`	Die beim Aufrufen der Verhaltensweise übergebenen Argumente.
`arguments_string`	Eine Zeichenfolge im JSON-Format mit Argumenten. Sie können sie verwenden, wenn Sie alle Argumente zur Nutzlast hinzufügen möchten.
`_execution_properties`	Sie können alle Werte aus dem `execution_properties` Aufrufargument anhand des Schlüsselnamens auswählen.
`execution`	Sie können alle Werte aus dem `execution` Aufrufargument anhand des Schlüsselnamens auswählen.
`invocation`	Sie können alle Werte aus dem `invocation` Argument anhand des Schlüsselnamens auswählen.
`entity`	Eine Zuordnung des Einheitsinhalts. Sie können alle Werte in der Einheit nach Schlüsselnamen auswählen.
`entity_string`	Eine JSON-Formatzeichenfolge der Einheit.

Weitere Informationen zur Apache FreeMarker-Ausdruckssprache für die Vorlage für die Nutzlast finden Sie unter https://freemarker.apache.org/docs/dgui_quickstart_template.html.

Beispielvorlage:

<#assign header_Content\-Type= "application/json" />
{
"text": "Behavior with id ${_metadata.behaviorId} was executed on entity with id ${entityId}"   
}

Sie können benutzerdefinierte Kopfzeilen angeben, die Sie zur POST-Anforderung hinzufügen möchten, die an die Webhook-Server gesendet wird. Sie können die Webhook-Vorlage verwenden, um benutzerdefinierte Header hinzuzufügen, bei denen es sich um Variablen in der Vorlage mit dem Präfix header_ handelt. Sie können beispielsweise den Wert für die Authorization-Kopfzeile angeben, indem Sie der Vorlage die folgende Zeile hinzufügen:

<#assign header_Authorization = "${_execution_properties._secure_token}" />

Nutzlast vom Webhook-Server zu VMware Cloud Director

Standardantwort
Die Standardnutzlast vom Webhook-Server zu VMware Cloud Director muss Folgendes enthalten.
- Die Antwort kann entweder keine Content-Type-Kopfzeile oder eine Content-Type-Kopfzeile mit text/plain-Wert aufweisen.
- Der Textkörper der Antwort muss eine Zeichenfolge sein.
- Der Textkörper der Antwort wird als Ergebnis des Aufrufs der Verhaltensweise verwendet. Der Status für die Aufgabe zum Aufrufen der Verhaltensweise lautet success. Das Aufgabenergebnis wird auf den Textkörper der Antwort festgelegt.
Antwort auf die Aktualisierung einzelner Aufgaben
Abgesehen vom Ergebnis der Verhaltensweisen kann die Antwort auf die Aufgabenaktualisierung einige andere Eigenschaften für Aufrufaufgaben festlegen, wie z. B. status, details, operation, error, progress und result. Da dies ist ein einmaliges Task-Update ist, muss die Antwort die Aufgabe abschließen. Wenn der Aufgabenstatus in der Antwort nicht auf success, error oder aborted festgelegt wird, schlägt die Aufgabe mit einem Fehler fehl. Die Fehlermeldung weist darauf hin, dass der Status nicht akzeptabel war.
- Die Antwort muss über einen Content-Type-Header mit application/vnd.vmware.vcloud.task+json-Wert verfügen.
- Der Antworttext muss eine JSON-Darstellung der TaskType-Klasse enthalten, die die Aufgabeneigenschaften enthält, die Sie ändern möchten.
- Beispiel eines Antworttexts mit Status success:
```
{
   "status":"success",
   "details":"example details",
   "operation":"example operation",
   "progress":100,
   "result":{
      "resultContent":"example result"
   }
}
```
- Beispiel eines Antworttexts mit Status error:
```
{
   "status":"error",
   "details":"example details",
   "operation":"example operation",
   "progress":50,
   "error":{
      "majorErrorCode":404,
      "minorErrorCode":"ERROR",
      "message":"example error message"
   }
}
```
Antwort auf die Aktualisierung kontinuierlicher Aufgaben
Der Webhook-Server kann mehrere Aufgabenaktualisierungen mithilfe einer mehrteiligen HTTP-Antwort senden. Jedes Update ist ein separater Textteil des Antworttexts. Der letzte Antwort-Textteil des Webhook-Servers muss die Aufgabe abschließen. Wenn der Antworttext die Aufgabe nicht abgeschlossen hat, schlägt die Aufgabe mit einem Fehler fehl.
- Die Antwort muss über einen Content-Type-Header mit multipart/form-data; boundary=...-Wert verfügen.
- Der Antworttext der Antwort muss mit einer Begrenzungszeichenfolge --<boundary_string> beginnen und enden. Jeder Teil des Antworttexts muss in einer Begrenzungszeichenfolge enden. Sie müssen die Begrenzung in der Content-Type-Kopfzeile der HTTP-Antwort vom Webhook-Server angeben.
```
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>
```
Die Textelemente im Textkörper der Antwort müssen im Format für eine Aufgabenaktualisierung oder im Format für eine abschließende Aktualisierung vorliegen.
Beispiel für Aufgabenaktualisierung:
```
Content-Type: application/vnd.vmware.vcloud.task+json
{
"details": "example details",
"operation": "example operation",
"progress": 50
}
```
Beispiel für eine abschließende Aktualisierung:
```
Content-Type: text/plain
<string>
```

Authentifizierung der Webhook-Verhaltensanforderungen

Die HMAC-Authentifizierung (Hash-basierter Nachrichten-Authentifizierungscode) sichert Webhook-Verhaltensanforderungen. HMAC ist ein Mechanismus, der die Authentizität und Integrität von HTTP-Anforderungen sicherstellt. Um die Authentizität und Integrität sicherzustellen, enthält HMAC zwei benutzerdefinierte Kopfzeilen für jede HTTP-Anforderung. Die benutzerdefinierten Kopfzeilen sind eine Signaturkopfzeile und ein Digest. Für VMware Cloud Director ist die Signaturkopfzeile x-vcloud-signature, und der Digest ist x-vcloud-digest.

Die Signaturkopfzeile x-vcloud-signature ist eine benutzerdefinierte Kopfzeile, die mit jeder Webhook-Anforderung gesendet wird. Die Signaturkopfzeile besteht aus einem HMACSHA512-Algorithmus, Kopfzeilen und einer VMware Cloud Director-generierten Signatur. Die Kopfzeilen zeigen, was in der Basiszeichenfolge enthalten ist, die signiert wird, um die Signatur zu erstellen.

Tabelle 2. Kopfzeilenfelder
Bereich	Beschreibung
`host`	Der Webhook-Serverhost
`date`	Datum der Anforderung
`(request-target)`	Verknüpfte HTTP-Methode in Kleinbuchstaben, ASCII-Leerzeichen und Anforderungspfad-Kopfzeile. Beispiel: `post /webhook`.
`digest`	SHA-512-Digest des Anforderungstexts

Zum Erzeugen der Signaturkopfzeile benötigen Sie einen gemeinsamen geheimen Schlüssel. Der gemeinsame geheime Schlüssel ist eine Zeichenfolge, die nur VMware Cloud Director und der Webhook-Server kennen.

Die Digest-Kopfzeile x-vcloud-digest ist ein Base64-codierter SHA-512-Digest des Anforderungstexts.

Jede Webhook-Anforderung von VMware Cloud Director kann verifiziert werden, indem die Signatur mithilfe des gemeinsamen geheimen Schlüssels generiert und mit der Signatur in der Signaturkopfzeile von VMware Cloud Director verglichen wird.

Aufrufen von Webhook-Verhaltensweisen

Sie können Webhook-Verhaltensweisen wie jede andere Verhaltensweise aufrufen.

{
"arguments": {
"argument1": "data1",
"argument2": "data2",
...
 }
}