--- title: "Webhook で自動化する方法" order: 1 hidden: true ---
WebhookでProGetを他のサービスに接続すると、ユーザに通知したり、自動化をされたワークフローをトリガーしたり、特定のイベントを監査したりできます。例えば、
この機能は、パッケージの公開やデプロイ、削除などのイベントが発生したとき、HTTP ベースの通知(ペイロード)を送信するWebhookを作成します。ワークフロー自動化サービス(Zappier、Microsoft Flowなど)やその他のツールのAPIにも、ペイロードを適合できます。
有料版もしくは体験版の ProGet で使用できます。
Webhookは [Administration (管理)] > [Webhooks page (Webhookページ)] から、 すべてまたは個別のフィードに対してそれぞれ設定できます。複数のWebhookの指定もできますが、実行される順序は保証されません。
使用上の注意:Webhookは基本的な通知とトリガーのみが目的です。複数のWebhookを「連鎖」させ、一連のシーケンシャル(順番が決まっている)イベントのオーケストレーション(自動化)をするのは避けてください。テストでは問題なく実行されても、Webhookの起動順序は予測できず、並行して発生してしまうことがあります。
Webhookはフィードと関連付けることができ、以下の要素があります:
Webhookは以下のイベントに対して設定できます:
コンディショナル(条件)とは、Webhookが起動する前に検証される任意の式です。OtterScriptの述語式(リンク先英語)と同じ形式をとり、単項演算子 ( ! )や等価演算子 ( == と != )、ブーリアン演算 (&& と || )や丸括弧で構成されます。
以下が式の例とその結果です。
式 | 結果 |
---|---|
$FeedType == NuGet | $FeedType == NuGetフィードタイプが NuGet の場合、Webhook が実行される。 大文字と小文字を区別し比較するので、nugetと入力しても常にfalseで評価されるので注意が必要 |
true | Webhookは常に実行されるl |
!true | Webhookは実行されない |
true && false | Webhookは実行されない |
$CustomVar == true | $CustomVarが定義された変数であり、結果が "true "であれば、Webhookは実行される。変数が定義されていない場合はエラーが生じる |
デフォルトの場合、ProGet はシンプルな JSON ベースのオブジェクトを POST します。その際、パッケージ情報とイベントタイプを含むキー/値を持ちます。固有データのパッケージを送信する場合、変数を使用するのでご注意ください。
Content-Type=application/json
$ToJson(%(
feed: $FeedName,
package: $PackageId,
version: $PackageVersion,
hash: $PackageHash,
packageType: $FeedType,
event: $WebhookEvent,
user: $UserName
}
基本的な HTTP リクエストだけで特定のタスクを実行できない場合、サードパーティのワークフロー自動化サービスを利用し、ProGet と自動化をしたいツールの間のブリッジとして機能できます。
Zapier、IFTT、Microsoft Flow、elastic.io など、多くのホスト型やオンプレミスのワークフロー自動化サービスがあります。サービスの機能は少しずつ異なりますが、ProGet との統合方法はほとんど同じです。ProGet は自動化サービスに HTTP リクエストを送信します。自動化サービスはいくつかのワークフローをトリガーにし、他の API への追加リクエストをディスパッチできます。
例:Zapier
Zapier では、自動化ワークフローのことを Zaps(ザップ)と呼びます。有効にしたWebhookをトリガーとして新しいザップを作成すると、以下のようなURLを受信します。
https://zapier.com/hooks/catch/n/Lx2RH/
Zappier の Webhook は「シンプルで使いやすい」ことが特徴です。ProGet のデフォルトペイロードはシンプルな JSON ベースのキーと値のペアなので、 この URL を使ってプロセスを始めましょう。
フィードの Webhook に Zap URL を入力し、指定したイベントが発生すると、 ProGet は Zapier へのデータ送信を開始します。Zappier は、フィールド(フィード、グループ、名前、バージョンなど)を自動的にパースをします。
そして、それらの値をアウトバウンド統合に使うことができます。詳細やトラブルシューティングに関しては、ZapierのWebhookドキュメンテーション(リンク先英語) を参照してください。
それぞれのAPIは少しずつ違った形で認証を管理していますが、少なくとも 2 つのオプション(APIキーの使用か基本的なアクセス認証)のうちの 1 つが提示されます。どちらの認証方法もWebhook内で行うことができますが、カスタムペイロードが必要になるかもしれません。
API キーはクエリストリングやメッセージ本文、もしくは HTTP ヘッダーにある場合が多いです。それぞれ Webhook の適切な場所に追加しましょう。
Basic認証は、HTTP と同義です。以下のように Webhook のヘッダーセクションに追加できます:
Authorization:Basic $EncodeBasicAuth(username,password)
いずれの場合も、キーや名前、パスワードを蓄積するために変数を使うことをおすすめします。セキュアな状態にはできません(常にHTTP/S経由でプレインテキストとして送信される)が、難読化をして軽い不正アクセスを防いだり、別のWebhookでの再利用が簡単になったりします。
変数を使って、APIキーなどの静的構成の情報、ユーザー名などのコンテンツ固有のデータ、バージョン番号などのパッケージのメタデータを組み合わせて、さまざまなカスタムペイロードを作成できます。
設定変数は静的なので、グローバルまたはフィード上で定義できるキーと値のペアです。グローバル変数(大域変数)と同じ名前のフィードレベル変数を定義した場合、そのフィード上のコンテキストでイベントが発生した時にフィードレベル変数が使われます。
変数名は50文字以内で、数字 ( 0-9 )、大文字と小文字 ( a-Z )、ダッシュ ( - )、 アンダースコア ( _ )を使ったものが適用できます。ダッシュやアンダースコアを先頭や最後にはできません。
デフォルトペイロードには $JSEncode($PackageGroup) のような式がよくあります。これらは可変関数と言い、いくつかのパラメータを受け取る代わりに何らかの値を返すものです。$FeedName , $PackageVersion , $Date などのビルトイン(組み込み)変数はすべて可変関数として 実行されます。
可変関数と同じ名前の設定変数にもできますが、$FeedNameなどが実際のフィード名を返さないと混乱の原因になるので、あまりおすすめしません。同じ名前の設定変数がある場合、$FeedName() のようなパラメータリストを明確に指さない限り、名前の代わりに値が使われます。
可変関数は拡張可能なため、Inedoの拡張機能(リンク先英語)を使い独自の関数を書くことができます。
可変関数はパッケージからメタデータを抽出するために使われます。また、$PackageName や $PackageVersion など、すべてのパッケージが共通のメタデータにアクセスするための組み込み関数がいくつかあります。また、$PackageProperty() 関数を使うこともできます。
例えば、ユニバーサルパッケージで $PackageProperty(_sourceTarget) を使用した場合、_sourceTarget プロパティーが返されます。このようなプロパティーがない場合、ログにエラーが記録され Webhook は実行されません。
ただし、PackageProperty function(パッケージプロパティー関数)に第2引数(defaultText)を指定すると実行されます。つまり、$PackageProperty(_sourceTarget, unspecified)は_sourceTarget の値か不特定の値を返します。
変数のように「見える」、$で始まり文字が続くものは、すべてパースとして解析され評価されます。設定変数や可変関数が見つからない場合、エラーがログに記録され、リクエストも完了されません。これは$PackagNameのようなタイプミスを追跡するのに役立ち、必須と言ってもいい機能です。
ペイロードのどこかに$が必要な場合、アポストロフィ を使って、「$」 といった風にエスケープする必要があります。 アポストロフィー を使う場合は、「``」でエスケープします。r ,n, `tの場合は空白文字も使えます。
組み込み変数
変数 | 結果 |
---|---|
$WebhookName | 稼働中のWebhook名が表示される |
$WebhookId | 稼働中のWebhookIDが表示される |
$WebhookEvent | イベント名が表示される |
$FeedId | コンテキスト内のフィードIDが表示される |
$FeedName | コンテキスト内のフィード名が表示される |
$FeedType | NuGet、Chocolatey、PowerShell、{…}などコンテキスト内のフィードタイプが表示される |
$Date(format) | 同様 |
$PackageGroup | パッケージのグループ名が表示される、もしくは空欄 |
$PackageName | パッケージ名が表示される、もしくはIDのみの場合は空欄 |
$PackageId | パッケージのIDが表示される |
$PackageVersion | パッケージのバージョンが表示される |
$PackageHash | パッケージのハッシュが表示される |
$PackageProperty(name, default) | メタデータから任意のプロパティーが表示される。[default (デフォルト)] を指定しプロパティーが存在しない場合、発生したエラーの代わりに、そのテキストが表示される |
$Username | イベントを開始したユーザーの名前が表示される。サービス (例:ドロップパス) や [Anonymous (匿名)] によって動作させられた場合、SYSTEMになる |
$EncodeBasicAuth(username,password) | 基本的な認証リクエストで使用されるbase64文字列が表示される |
$JSEncode(s) | javascript/JSON文字列で使用するためにエンコードされた値が表示される |
$Coalesce(s, …) | 引数から最初の空白以外の値が表示される |
エラー処理とデバッグ
ProGet は作業を続行するために外部サーバからのレスポンスを待機しません。エラーが発生した場合(不正なHTTPステータスコードやネットワークレベルの問題)、ProGetの [Diagnostics Center (診断センター)] に保存されます。 エラーは、[Administration (管理)] > [Diagnostics Center (診断センター)] に移動し、 [View Messages (メッセージの表示)] ボタンをクリックして表示します。 Webhookメッセージのみを表示するカテゴリフィルタもあります。
一部のエラーが発生すると、HTTPリクエストができなくなります。(例:変数を置き換えられない、または無効なURLがあるなど)
Webhook リクエストは、イベントが発生した場所に応じてウェブかサービスから行われます。例えば、パッケージのプロモーションリクエストは、リクエストを受け取ったWebノードから来ます。それに対して、パッケージの追加リクエストは Web ノード (Web ui や API) やサービス (ドロップ、パス) から来る可能性があります。
このトピックについての詳細: