VMware Cloud Director Webhook 行為

若要連線兩個不同的應用程式，您可以使用 Webhook。透過使用 Webhook，可以設定事件通知。

Webhook 是 HTTP 回撥。發生事件時，實作 Webhook 的 Web 應用程式會廣播有關該事件的資料，並將資料從要接收資訊的應用程式傳送至 Webhook URL。如需詳細資訊，請參閱雲端開發人員平台。

在 VMware Cloud Director 的環境中，可以使用 Webhook 行為設定 Webhook。Webhook 行為會向遠端 Webhook 伺服器傳送 POST 要求。要求的本文包含有關行為叫用和在其上叫用行為之實體的資訊。還可以使用範本自訂本文。Webhook 伺服器回應確定行為叫用工作的結果。伺服器可以傳回三種不同類型的回應。

遠端 Webhook 伺服器可以是 VMware Cloud Director 可存取的任何伺服器。但是，在建立 Webhook 行為之前，必須驗證 Webhook 的端點是否安全。

驗證 Webhook 端點是否為 HTTPS 端點。
確認叫用行為的使用者所在的組織信任 Webhook 伺服器憑證。這意味著，即使憑證存在於 VMware Cloud Director 信任存放區中，如果叫用行為的使用者所在組織不信任該憑證，也不會執行 Webhook 行為。
您可以使用使用者介面或 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`	叫用的已定義實體的識別碼。
`typeId`	叫用的已定義實體之實體類型的識別碼。
`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",
...
 }
}