VMware Cloud Director Webhook 行为

要连接两个不同的应用程序，您可以使用 Webhook。通过使用 Webhook，您可以设置事件通知。

Webhook 是 HTTP 回调。发生事件时，实现 Webhook 的 Web 应用程序会广播有关该事件的数据，并将其发送到要接收信息的应用程序的 Webhook URL。有关详细信息，请参见 Cloud Developer Platform。

在 VMware Cloud Director 上下文中，可以使用 Webhook 行为配置 Webhook。Webhook 行为向远程 Webhook 服务器发出 POST 请求。请求的正文包含有关行为调用和对其调用行为的实体的信息。您还可以使用模板自定义正文。Webhook 服务器响应确定行为调用任务的结果。服务器可以返回三种不同类型的响应。

远程 Webhook 服务器可以是 VMware Cloud Director 可访问的任何服务器。但是，在创建 Webhook 行为之前，必须验证 Webhook 的端点是否安全。

验证 Webhook 端点是否为 HTTPS 端点。
确认调用行为的用户所在的组织信任 Webhook 服务器证书。这意味着，即使证书存在于 VMware Cloud Director 信任存储区中，如果调用行为的用户所在组织不信任该证书，也不会运行 Webhook 行为。
可以使用 UI 或 VMware Cloud Director API 将证书添加到信任存储区中。请参见使用 VMware Cloud Director 管理证书。

创建 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
      }
   }
}


字段	描述
`type`	必填字段。必须为 `WebHook`。
`id`	可选字符串字段。
`href`	必填字段，输入必须接收来自 VMware Cloud Director 请求的 URL。
`_internal_key`	必填字段，输入用于对发送到 Webhook 端点的请求进行签名的共享密钥。
`invocation_timeout`	可选字段，用于指定 Webhook 服务器响应的超时时间（以秒为单位）
`template.content`	可选字段，用于自定义发送到 Webhook 服务器的负载。可以将模板以字符串的形式提供。可以将其他字段添加到模板可访问的 `execution_properties`。
`_secure_`	前缀为 `_secure_` 的字段是可选字段。这些字段是只写字段，无法通过对行为发出 GET 请求获取。字段值会在保存到 VMware Cloud Director 数据库之前进行加密。模板可以访问这些字段。

从 VMware Cloud Director 到 Webhook 服务器的负载

发送到 Webhook 服务器的负载有默认格式。您还可以使用模板自定义负载。

默认负载示例：

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

对于具有模板的自定义负载，您可以为发送到 Webhook 服务器的负载指定模板。如果未指定模板，则 VMware Cloud Director 会将默认请求负载发送到 Webhook 服务器。Apache FreeMarker 模板引擎会根据提供的模板和数据模型呈现负载。

数据模型表示为模板准备的所有数据，换句话说，就是可以包含在负载中的所有数据。数据模型包含 Webhook 行为的调用参数，例如，参数、元数据、执行属性和实体信息。以下示例显示了数据模型的树形结构。

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

表 1. 调用参数
参数	描述
`entityId`	调用的已定义实体的 ID。
`typeId`	调用的已定义实体的实体类型的 ID。
`arguments`	在行为调用中传递的参数。
`arguments_string`	JSON 格式的参数字符串。如果要将所有参数添加到负载，则可以使用该参数。
`_execution_properties`	可以按键名称从 `execution_properties` 调用参数中选择所有值。
`execution`	可以按键名称从 `execution` 调用参数中选择所有值。
`invocation`	可以按键名称从 `invocation` 参数中选择所有值。
`entity`	实体内容的映射。您可以按键名称选择实体中的所有值。
`entity_string`	实体的 JSON 格式字符串。

有关负载模板的 Apache FreeMarker 表达式语言的详细信息，请参见 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}"   
}

可以指定要添加到发送到 Webhook 服务器的 POST 请求中的自定义标头。可以使用 Webhook 模板添加自定义标头，这些标头是模板中带有前缀 header_ 的变量。例如，可以通过在模板中添加以下行来指定 Authorization 标头的值：

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

从 Webhook 服务器到 VMware Cloud Director 的负载

默认响应
从 Webhook 服务器到 VMware Cloud Director 的默认负载必须包含以下内容。
- 响应可以不包含 Content-Type 标头，也可以包含值为 text/plain 的 Content-Type 标头。
- 响应正文必须是字符串。
- 响应的正文用作行为调用的结果。行为调用任务的状态为 success。任务结果设置为响应的正文。
单个任务更新响应
除了行为结果外，任务更新响应还可以设置一些其他行为调用任务属性，如 status、 details、 operation、 error、 progress 和 result。由于这是一次性任务更新，因此响应必须完成任务。如果响应未将任务状态设置为 success、 error 或 aborted，则任务将失败并显示错误。错误消息指示状态不可接受。
- 响应必须包含值为 application/vnd.vmware.vcloud.task+json 的 Content-Type 标头。
- 响应正文必须包含 TaskType 类（包含要修改的任务属性）的 JSON 表示形式。
- 状态为 success 的响应正文示例：
```
{
   "status":"success",
   "details":"example details",
   "operation":"example operation",
   "progress":100,
   "result":{
      "resultContent":"example result"
   }
}
```
- 状态为 error 的响应正文示例：
```
{
   "status":"error",
   "details":"example details",
   "operation":"example operation",
   "progress":50,
   "error":{
      "majorErrorCode":404,
      "minorErrorCode":"ERROR",
      "message":"example error message"
   }
}
```
连续任务更新响应
Webhook 服务器可以使用多部分 HTTP 响应发送多个任务更新。每个更新都是响应正文的独立正文部分。Webhook 服务器响应正文的最后一个正文部分必须完成任务。如果响应正文未完成任务，则任务将失败并显示错误。
- 响应必须包含值为 multipart/form-data; boundary=... 的 Content-Type 标头。
- 响应正文必须以边界字符串 --<boundary_string> 开头和结尾。响应正文的每个部分都必须以边界字符串结尾。必须在来自 Webhook 服务器的 HTTP 响应的 Content-Type 标头中指定边界。
```
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>
```
响应正文中的各个正文部分必须采用任务更新的格式或最终更新的格式。
任务更新示例：
```
Content-Type: application/vnd.vmware.vcloud.task+json
{
"details": "example details",
"operation": "example operation",
"progress": 50
}
```
最终更新示例：
```
Content-Type: text/plain
<string>
```

Webhook 行为请求的身份验证

基于哈希的消息身份验证代码 (HMAC) 身份验证可保护 Webhook 行为请求。HMAC 是一种确保 HTTP 请求真实性和完整性的机制。为确保真实性和完整性，HMAC 对每个 HTTP 请求都包含两个自定义标头。这两个自定义标头分别是签名标头和摘要。对于 VMware Cloud Director，签名标头为 x-vcloud-signature，摘要为 x-vcloud-digest。

签名标头 x-vcloud-signature 是随每个 Webhook 请求一起发送的自定义标头。签名标头由 HMACSHA512 算法、标头和 VMware Cloud Director 生成的签名组成。标头显示为创建签名而签名的基本字符串中的内容。

表 2. 标头字段
字段	描述
`host`	Webhook 服务器主机
`date`	请求日期
`(request-target)`	链接的小写 HTTP 方法、ASCII 空格和请求路径标头。例如，`post /webhook`。
`digest`	请求正文的 SHA-512 摘要

要生成签名标头，您需要一个共享密钥。共享密钥是一个只有 VMware Cloud Director 和 Webhook 服务器知道的字符串。

摘要标头 x-vcloud-digest 是请求正文的 Base64 编码 SHA-512 摘要。

可以通过使用共享密钥生成签名并将其与 VMware Cloud Director 签名标头中的签名进行比较来验证来自 VMware Cloud Director 的每个 Webhook 请求。

调用 Webhook 行为

可以像调用任何其他行为一样调用 Webhook 行为。

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