HCL Compass Webhooks の活用法
2022/3/17 - 読み終える時間: 8 分
HCL Compass Webhooks in Action の翻訳版です。
HCL Compass Webhooks の活用法
はじめに
この記事では、HCL CompassのWebhooksについて説明します。Webhookとは、何かがトリガーされたときにアプリから送信される自動化されたデータに他なりません。この場合、HCL Compass は Webhook データを送信するアプリで、これは Payload とも呼ばれます。Webhook は Compass アプリケーションを購読し、特定の条件が満たされるまで待機し、ペイロードを送信します。ペイロードは通常、レコードデータを含む JSON で、HTTP POST リクエストとして送信され、サードパーティーアプリケーションまたはカスタムスクリプトでキャッチして、有用な処理を行えます。これはRESTAPIとは異なり、アプリケーションからCompassにリクエストを送信し、特定の情報を得たり、特定のアクションを実行したりできます。Compass Webhook レコードで定義された条件に基づいて、Compass から一定間隔でデータが送信されるのを待ちます。
このデモを行うために、まずHCL CompassインスタンスでWebhookを有効にするつもりです。これを行うために必要な手順を説明します。すべての設定が完了したら、シンプルな Python Flask アプリケーションを使用して、Compass Webhooks からの POST リクエストをリスンし、それを表示することで、その動作を証明します。
CompassでWebhooksを有効にする
HCL compassでWebhooksを有効にする方法について順を追って説明します。これらの手順のほとんどはWindowsに特有のものですが、UNIX環境でも同じように変換できます。
- Webhooksを使用するためには、HCL CompassのRESTAPIサーバーコンポーネントをインストールする必要があります。
Start -> Programs -> IBM Installation Manager -> View Installed Packages で確認できます。
ページが開いたら、以下のように表示され、RESTAPIサーバーがインストールされていることを確認します。
インストールされていない場合は、Installation Managerからインストールする必要がありますが、次のステップに進みます。
- 次のステップは、Webhooks 1.0 パッケージをスキーマリポジトリにインストールすることです。Compass Designerを起動し、スタート->プログラム->HCL Compass-> Compass Designerをクリックします。
- スキーマリポジトリに認証情報を使って接続し、スキーマ -> バージョン -> パッケージ - > パッケージを適用 をクリックします。
- Webhooks パッケージ 1.0 を選択し、適用します。
- パッケージで有効にするレコードの種類を選択します。
- パッケージが適用されたら、スキーマをチェックインし、データベースをアップグレードします。
Webhookの設定を作成する
Webhooks パッケージを使用すると、レコードに対して特定のアクションが実行されたり、レコードの状態が変化するなど、特定の条件が満たされたときに、他のシステムが Compass レコードに関する JSON ペイロードを受信できるようになります。
パッケージが正常に適用されたら、Webhooks を稼働させるために必要なレコードを作成する時間です。
Administratorアカウントでcqwebにログインし、WebhookMasterというタイプのレコードを追加します。WebhookConfig レコードの作成を許可するグループを追加します (これは必須ではありません)。このグループのユーザーは WebhookConfig を作成できます。また、コールバックURLを指定する必要がありますが、これはCompass Rest APIのURL以外の何物でもありません。私たちはそれをマシン上にローカルに置いているので、localhostという名前になっています。基本的に、Compassはサードパーティーのアプリケーションにデータを送信し、メッセージが配信されているかどうかを確認するために待機しています。そのため、コールバックURLにはその応答が期待されます。
次のステップは、WebhookConfigレコードの作成です。
ここでは、Webhookを起動するための有効なレコードの条件や、サードパーティーアプリケーションへのURLなど、Webhookのパラメータを定義する場所です。以下のスクリーンショットのように、DefectはWebhookを有効にする必要があるレコードタイプなので、compassdefectという名前を入力しました。ここでは任意の名前を付けられます。次のフィールドは URL で、サードパーティーアプリケーションが Compass Webhooks からの POST リクエストをリッスンするための URL です。 この例では、compassdefect ルートをリッスンするシンプルな Python Flask アプリケーションです。アプリケーションはCompassと同じシステムで動作しているので、127.0.0.1がループバックアドレスです。あなたの場合、これは別のIPまたはホスト名かもしれません。オプションで SECRET フィールドがありますが、これは Webhook データを保護するために使用されます。本番環境では有効にしておくことを強くお勧めします。あなたが提供する秘密は、HMAC-SHA1 ハッシュ関数を使用してペイロードをハッシュ化し、ペイロードと一緒に署名ヘッダーを介して送信されるために使用されます。アプリケーションでは、ハッシュ関数に秘密を渡し、ヘッダでCompassから提供されたものと一致するかどうかを確認する必要があります。
また、DescriptionフィールドにWebhookのDescriptionを指定できます。追跡が必要なレコードタイプを指定します。この場合、これは「欠陥」です。Webhookの種類をCommitかNotificationから選択します。Commit はコントロールに記載されたアクションが成功した場合のみペイロードを送信し、Notification はステータスに関係なくペイロードを送信することになっているという違いがあります。この場合、Commit が選択されています。
コントロール]タブでは、この場合、選択されているアクションは[投稿]、状態は[投稿]です。つまり、Defectレコードを投稿すると、FlaskサーバーにWebhookペイロードがトリガーされることになります。また、Controlsタブに関連した不具合もあり、その対処方法は以下のドキュメントに記載されています。
PostmanなどのAPIクライアントを使用して、REST APIサーバーのhooksetupエンドポイントにHTTP POSTリクエストを作成します。このために、まずRESTAPIサーバを起動する必要があります。 Compassのインストールディレクトリに移動し、コマンドラインで以下のパスに移動し、start.batを実行します。
RESTサーバを起動すると、Server is NOT configured for Webhooksのような行が表示されるはずです。
サーバーが立ち上がったら、APIクライアントから、以下のエンドポイントを指定してHTTP POST Requestを実行します。
Method : POST
URL : https://localhost:8190/ccmweb/rest/hooksetup
Body : {
“username”: “admin”,
“password”: “”,
“repo”: “Gitintegration”,
“db”: “GITIN”
}
この場合、GITintegrationがスキーマ・リポジトリ、GITINがユーザー・データベースで、adminはパスワードのないユーザーです。
この場合、RESTサーバは同じマシン上で動作しているため、localhostという名前になっています。Compassで必要なアクションを実行できるシステムユーザーを作成することで、Webhooksパッケージで使用するためのサーバーを有効にします。
RESTAPIサーバーを再起動します。
今度はWebhooksがEnableになったことが確認できます。
Webhooksの実行
ここからは、すべて自動で行われるはずです。Compassは、新しいレコードが送信された瞬間にWebhookのペイロードのトリガーをかけます。このペイロードが正常に送信され、Flaskアプリケーションで読み込めるかどうかを確認します。この作業を行うには、RESTAPIサーバが稼働している必要があり、Flaskアプリケーションも同様に稼働していることを忘れないでください。
- Compassで新しい不具合を作成します。
- RESTAPI サーバが起動していない場合は起動し、Webhooks が動作していることを確認します。
そして、Flask Applicationでも同じようにデータを受信していることが確認できます。
Webhooksのトラブルシューティングはどのように行うのですか？
Compassでクエリを作成し、Webhooksを追跡できます。クエリのベースとなるのは、WebhookDataというレコードタイプにする必要があります。このクエリを実行すると、配信待ちのWebhookがあるかどうか、何回アプリケーションに配信しようとしたか、エラーがあるかどうかを確認できます。
配信するものがない場合、レコードは表示されません。
以下は失敗の例です。今回はFlaskサーバーが起動していないため、レスポンスコードが500、リトライが1となっています。
FLASKアプリケーションのサンプルコードです。
まとめ
注：これはあくまでデモンストレーション用のサンプルコードであり、本番で使用するものではないことに注意してください。
上記からわかるように、このアプリケーションはコンソールにデータを出力する以外には何もしていません。DBに格納したり、ウェブページに表示するために他の目的に使用するなど、他の多くのことを行うことができました。しかし、現実の世界では、サードパーティーアプリケーションとHCL Compassの統合をセットアップすることで、可能性は無限に広がります。Webhooksを使い始め、HCL Compassのデータと連携する可能性を探るきっかけになれば幸いです。