VMware Cloud Director Webhook の動作

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 です。タスクの結果は、応答の本文に設定されます。
単一のタスク更新応答
動作の結果とは別に、タスク更新応答では、 status、 details、 operation、 error、 progress、および result などの他の動作の呼び出しタスクのプロパティを設定できます。これは 1 回限りのタスク更新であるため、応答でタスクを完了する必要があります。応答でタスクのステータスが 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 要求に 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",
...
 }
}