若要連線兩個不同的應用程式,您可以使用 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 將憑證新增到信任存放區中。請參閱管理憑證

建立 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/plainContent-Type 標頭。
    • 回應本文必須是字串。
    • 回應本文用作行為叫用的結果。行為叫用工作的狀態為 success。將工作結果設定為回應本文。
  • 單一工作更新回應
    除了行為結果外,工作更新回應還可以設定一些其他行為叫用工作內容,如 statusdetailsoperationerrorprogressresult。由於這是一次性工作更新,因此回應必須完成工作。如果回應未將工作狀態設定為 successerroraborted,則工作將失敗並顯示錯誤。錯誤訊息指示狀態不可接受。
    • 回應必須包含值為 application/vnd.vmware.vcloud.task+jsonContent-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",
...
 }
}