2 つの異なるアプリケーションを接続するには、Webhook を使用できます。Webhook を使用すると、イベント通知を設定できます。

Webhook は HTTP コールバックです。イベントが発生すると、Webhook を実装する Web アプリケーションは、そのイベントに関するデータをブロードキャストし、情報を受信するアプリケーションから Webhook URL に送信します。詳細については、Cloud Developer Platformを参照してください。

VMware Cloud Director のコンテキストでは、Webhook の動作を使用して Webhook を構成できます。Webhook の動作は、リモート Webhook サーバに POST 要求を送信します。要求の本文には、動作の呼び出しと、動作が呼び出されたエンティティに関する情報が含まれています。また、テンプレートを使用して本文をカスタマイズすることもできます。Webhook サーバの応答によって、動作の呼び出しタスクの結果が決まります。サーバが返すことができる応答には、3 つの異なるタイプがあります。

リモート 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 呼び出された定義済みエンティティの 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 です。タスクの結果は、応答の本文に設定されます。
  • 単一のタスク更新応答
    動作の結果とは別に、タスク更新応答では、 statusdetailsoperationerrorprogress、および result などの他の動作の呼び出しタスクのプロパティを設定できます。これは 1 回限りのタスク更新であるため、応答でタスクを完了する必要があります。応答でタスクのステータスが successerror、または 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 要求に 2 つのカスタム ヘッダーが含まれています。カスタム ヘッダーは、署名ヘッダーとダイジェストです。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 からの各 Webhook 要求は、共有シークレット キーを使用して署名を生成し、VMware Cloud Director からの署名ヘッダーの署名と比較することで検証できます。

Webhook の動作の呼び出し

Webhook の動作は、他の動作と同様に呼び出すことができます。
{
"arguments": {
"argument1": "data1",
"argument2": "data2",
...
 }
}