--- title: "Webhook で自動化する方法" order: 1 hidden: true ---

WebhookでProGetを他のサービスに接続すると、ユーザに通知したり、自動化をされたワークフローをトリガーしたり、特定のイベントを監査したりできます。例えば、

- パッケージがフィードに追加されたとき、メッセージを送信する
- BuildMaster（リンク先英語）で、パッケージが別のフィード（例、開発中パッケージのフィードから、デプロイ可のパッケージのフィード）に移動したとき、パッケージをデプロイさせる
- パッケージが削除された場合、サードパーティのツールにてメッセージを記録する

この機能は、パッケージの公開やデプロイ、削除などのイベントが発生したとき、HTTP ベースの通知（ペイロード）を送信するWebhookを作成します。ワークフロー自動化サービス（Zappier、Microsoft Flowなど）やその他のツールのAPIにも、ペイロードを適合できます。

有料版もしくは体験版の ProGet で使用できます。

## Webhookの設定

Webhookは [Administration (管理)] > [Webhooks page (Webhookページ)] から、 すべてまたは個別のフィードに対してそれぞれ設定できます。複数のWebhookの指定もできますが、実行される順序は保証されません。

使用上の注意：Webhookは基本的な通知とトリガーのみが目的です。複数のWebhookを「連鎖」させ、一連のシーケンシャル（順番が決まっている）イベントのオーケストレーション（自動化）をするのは避けてください。テストでは問題なく実行されても、Webhookの起動順序は予測できず、並行して発生してしまうことがあります。

Webhookはフィードと関連付けることができ、以下の要素があります：

- Id – システムが生成した固有の識別子
- [Name (名前)] – UI （ユーザーインターフェイス）内やログのWebhookを特定するための固有でない識別子
- [Event Type (イベントタイプ)] - イベントタイプの一種
- URL - 要求を送信するURL
- [Conditional (コンディショナル/条件的)] - Webhookが実行されるべきか判断するために検証されるエクスプレッション
- [Custom payload (カスタムペイロード)] - デフォルトペイロードの代わりに、送信されるリクエストをカスタマイズする
- [Method (メソッド)] - GET, DELETE, POST, PUT, HEAD, OPTIONS, PATCHのいずれか
- [Headers (ヘッダー)] - HTTPヘッダーの改行個別リスト
- [Body (本文)] - 送信されるリクエストの本文

## イベントタイプ

Webhookは以下のイベントに対して設定できます：

- [added (追加)] - API、ウェブインターフェイス、もしくはドロップパスを使ってパッケージが追加される
- [promoted (プロモーション)] - APIもしくはウェブインターフェイスを使ってパッケージがプロモーションされる
- [deployed (デプロイ)] - デプロイ記録が追加される。特定のHTTPヘッダーがAPIベースのパッケージダウンロード中に送信される時に発生する
- [deleted (削除)] - APIもしくはウェブインターフェイスを使ってパッケージが削除される
- [purged (パージ)] - リテンションポリシーに基づいてパッケージが削除される

## コンディショナル

コンディショナル（条件）とは、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） やサービス （ドロップ、パス） から来る可能性があります。

このトピックについての詳細：

oSlackへの接続

oTeamsへの接続