Microsoft Flow で webhook を使用するUse webhooks with Microsoft Flow

webhook は、イベント通知を提供する単純な HTTP コールバックです。Webhooks are simple HTTP callbacks used to provide event notifications. Microsoft Flow では、webhook を利用してフローをトリガーできます。Microsoft Flow allows you to use webhooks to trigger flows. このチュートリアルでは、webhook によってトリガーされるフローを作成する方法を示します。This tutorial demonstrates how to create a flow triggered by a webhook.

注意

webhook で通知を送信できるサービスの例として GitHub を利用しますが、ここで紹介する手法は webhook を使用するあらゆるサービスに応用できます。We will use GitHub as an example of a service that can send notifications via webhooks, but the techniques demonstrated here can be extended to any service that uses webhooks.

前提条件Prerequisites

このチュートリアルを完了するために必要な要素:To complete the tutorial, you will need:

OpenAPI ファイルThe OpenAPI file

webhook は Microsoft Flow に一種のカスタム コネクタとして実装されます。そのため、OpenAPI JSON ファイルを与え、webhook の形を定義する必要があります。Webhooks are implemented in Microsoft Flow as a type of custom connector, so we'll need to provide an OpenAPI JSON file to define the shape of our webhook. OpenAPI には、webhook ワーク作成のために重要な 3 つの定義が含まれています。The OpenAPI contains three definitions critical to making the webhook work:

  1. webhook を作成するCreating the webhook
  2. API (ここでは、GitHub) から入ってくるフック要求を定義するDefining the incoming hook request from the API (in this case, GitHub)
  3. webhook を削除するDeleting the webhook

webhook を作成するCreating the webhook

webhook は GitHub 側で /repos/{owner}/{repo}/hooks に対する HTTP POST により作成されます。The webhook is created on the GitHub side by an HTTP POST to /repos/{owner}/{repo}/hooks. OpenAPI に定義されているトリガーで新しいフローが作成されるとき、あるいはトリガーが変更されるとき、Microsoft Flow はこの URL に投稿する必要があります。Microsoft Flow will need to post to this URL when a new flow is created using the trigger defined in the OpenAPI, or whenever the trigger is modified. 下のサンプルでは、GitHub に投稿される要求のスキーマが post プロパティに含まれています。In the sample below, the post property contains the schema of the request that will be posted to GitHub.

"/repos/{owner}/{repo}/hooks": {
    "x-ms-notification-content": {
    "description": "Details for Webhook",
    "schema": {
        "$ref": "#/definitions/WebhookPushResponse"
    }
    },
    "post": {
    "description": "Creates a Github webhook",
    "summary": "Triggers when a PUSH event occurs",
    "operationId": "webhook-trigger",
    "x-ms-trigger": "single",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targetted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "Request body of webhook",
        "in": "body",
        "description": "This is the request body of the Webhook",
        "schema": {
            "$ref": "#/definitions/WebhookRequestBody"
        }
        }
    ],
    "responses": {
        "201": {
        "description": "Created",
        "schema": {
            "$ref": "#/definitions/WebhookCreationResponse"
        }
        }
    }
    }
},

重要

"x-ms-trigger": "single" プロパティは、フロー デザイナーの利用可能トリガー リストにこの webhook を表示するように Microsoft Flow に通知するスキーマ拡張機能です。そのため、これを必ず含めてください。The "x-ms-trigger": "single" property is a schema extension that tells Microsoft Flow to display this webhook in the list of available triggers in the flow designer, so be sure to include it.

API から入ってくるフック要求を定義するDefining the incoming hook request from the API

上のサンプルのように、入ってくるフック要求 (GitHub から Microsoft Flow への通知) の形はカスタム x-ms-notification-content プロパティで定義されます。The shape of the incoming hook request (the notification from GitHub to Microsoft Flow) is defined in the custom x-ms-notification-content property, as shown in the sample above. 要求のコンテンツ全体を含める必要はありません。フローで使用する部分だけで十分です。It doesn't need to contain the entire contents of the request, just the portions you want to use in your flows.

webhook を削除するDeleting the webhook

webhook の削除方法を Microsoft Flow に通知する定義を OpenAPI に含めることはとても重要です。It's very important to include a definition in the OpenAPI that tells Microsoft Flow how to delete the webhook. フローのトリガーを更新したり、フローを削除したりするたびに、Microsoft Flow は webhook の削除を試行します。Microsoft Flow will try to delete the webhook every time you update the trigger in your flow, or when you delete your flow.

"/repos/{owner}/{repo}/hooks/{hook_Id}": {
    "delete": {
    "description": "Deletes a Github webhook",
    "operationId": "DeleteTrigger",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targetted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "hook_Id",
        "in": "path",
        "description": "ID of the Hook being deleted",
        "required": true,
        "type": "string"
        }
    ]
    }
},

重要

Microsoft Flow が webhook を削除できるように、webhook の作成時、API で 201 応答に Location HTTP ヘッダーを含める必要がありますIn order for Microsoft Flow to be able to delete a webhook, the API must include a Location HTTP header in the 201 response at the time the webhook is created. Location ヘッダーには、HTTP DELETE と共に使用する webhook のパスを含める必要があります。The Location header should contain the path to the webhook that will be used with the HTTP DELETE. たとえば、GitHub の応答に付属する Location の形式は https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID> です。For example, the Location included with GitHub's response follows this format: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>.

認証Authentication

Microsoft Flow に webhook 要求を送信する API には、通常、何らかの形式の認証が与えられます。GitHub も例外ではありません。The API sending the webhook request to Microsoft Flow will usually have some form of authentication, and GitHub is no exception. 数種類の認証がサポートされています。Several types of authentication are supported. このチュートリアルでは、GitHub の個人アクセス トークンを使用します。For this tutorial, we'll use GitHub's personal access tokens.

  1. GitHub に移動し、サインインしていない場合はサインインします。Navigate to GitHub and sign in if you haven't already.
  2. 右上にある自分のプロフィール写真をクリックし、メニューの [設定] をクリックします。In the upper right, click your profile picture, and then, in the menu, click Settings.

    設定

  3. 左のメニューの [開発者向け設定] で、[個人用アクセス トークン] をクリックします。In the menu on the left, under Developer settings, click Personal access tokens.

    個人用アクセス トークン

  4. [新しいトークンを生成する] ボタンをクリックします。Click the Generate new token button.

    新しいトークンを生成する

  5. [トークンの説明] ボックスに説明を入力します。In the Token description box, enter a description.
  6. [admin:repo_hook] チェック ボックスをオンにします。Select the admin:repo_hook checkbox.

    admin:repo_hook

  7. [トークンの生成] ボタンをクリックします。Click the Generate token button.
  8. 新しいトークンをメモします。Make note of your new token.

    新しいトークン

    重要

    このトークンに再びアクセスすることはできません。You won't be able to access this token again. コピーしてメモ帳などに貼り付け、チュートリアルの後半で使用します。You should copy and paste it somewhere like Notepad to use later in the tutorial.

webhook を Microsoft Flow に追加するAdding the webhook to Microsoft Flow

これで、webhook をカスタム コネクタとして Microsoft Flow に追加するために必要なすべての要素が揃いました。Now we've got everything we need to add the webhook to Microsoft Flow as a custom connector.

  1. Microsoft Flow Web ポータルに移動し、サインインしていない場合はサインインします。Navigate to the Microsoft Flow web portal and sign in if you haven't already.
  2. [設定] アイコンをクリックし、[Custom Connectors (カスタム コネクタ)] をクリックします。Click the settings icon, and then click Custom Connectors.

    カスタム コネクタ

  3. [Create custom connector (カスタム コネクタの作成)] ボタンをクリックします。Click the Create custom connector button.
  4. [Import OpenAPI (OpenAPI のインポート)] ボックスのファイル フォルダー アイコンをクリックし、サンプルの OpenAPI ファイルを選択します。Click the file folder icon in the Import OpenAPI box and then select the sample OpenAPI file.
  5. [一般情報] セクションの [更新] をクリックし、アイコンとして使用する画像ファイルを選択します。Click Upload icon in the General information section and then select an image file to use as an icon.
  6. [続行] をクリックします。Click Continue.

    OpenAPI をインポートする

  7. 次の画面で、セキュリティ設定を構成します。On the next screen, we'll configure security settings. [認証の種類][基本認証] を選択します。Under Authentication type, select Basic authentication.
  8. [基本認証] セクションで、ラベル フィールドにテキストを入力します。ユーザー名パスワードです。In the Basic authentication section, for the label fields, enter the text User name and Password. これはフローでトリガーが使用されるときに表示されるラベルです。Note that these are only labels that will be displayed when the trigger is used in a flow.

    基本認証

  9. ページ上部でフローに名前を付け、[Create connector (コネクタの作成)] をクリックします。At the top of the page, give your flow a name and click Create connector.

    API の作成

新しいカスタム コネクタがカスタム コネクタ ページの一覧に表示されるはずです。The new custom connector should now appear in the list on the custom connectors page.

UI からの webhook トリガーの作成Creating webhook triggers from the UI

  1. 基準 OpenAPI ファイルをアップロード/作成した後、カスタム コネクタ ウィザードの [定義] タブに移動します。After uploading / creating your baseline OpenAPI file, navigate to the Definition tab of the custom connector wizard.
  2. 左側のウィンドウで [+ 新しいトリガー] をクリックし、トリガーの説明を入力します。In the left hand pane, click + New trigger, and fill out the description of your trigger. この例では、リポジトリに対してプル要求が行われたときに起動されるトリガーを作成します。In this example, we are creating a trigger that fires when a pull request is made to a repository.

    トリガーの作成 - 1

  3. 次に、webhook トリガーを作成する要求を定義します。Next, define the request to create the webhook trigger. これは、サンプルの "webhook トリガー作成" 要求をインポートすることによって行うことができます。You can do this by importing a sample create webhook trigger request. webhook の作成については、Github の API リファレンスをご覧ください。See the Github API reference for creating a webhook.
  4. Microsoft Flow は標準の content-type とセキュリティ ヘッダーを自動的に追加するので、サンプルからインポートするときに定義する必要はありません。Microsoft Flow automatically adds standard content-type and security headers, so we don’t need to define those while importing from a sample.

    トリガーの作成 - 2

  5. webhook 作成要求をインポートした後、サンプルの応答からインポートして webhook の応答を定義します。After importing the create webhook request, next we will define the webhook response by importing from a sample response. プル要求イベントについては、Github の API リファレンスをご覧ください。See the Github API reference for a pull request event.

    : 応答をすべて貼り付ける必要はありません。Note: You don’t have to paste in the full response. 必要なフィールドのみを定義する必要があります。Only the fields that you need should be defined. この例では、PR の URL と、PR を行ったユーザーの情報のみを抽出します。For this example, we are extracting only the PR url and information of the user who made the PR.

    トリガーの作成 - 3

  6. 最後の手順では、webhook 作成要求のパラメーターで、Github が設定するために Microsoft Flow がコールバック URL を設定する必要がある値を選択します。The final step is to select a parameter in the webhook creation request, in the value of which Microsoft Flow should populate a callback URL for Github to populate. この場合、これは config オブジェクトの URL プロパティです。For us this is the url property in the config object.

    トリガーの作成 - 4

トリガーとして webhook を使用するUsing the webhook as a trigger

すべての構成が完了したので、フローで webhook を使用できます。Now that we've got everything configured, we can use the webhook in a flow. GitHub リポジトリが git プッシュを受信するたびに Microsoft Flow モバイル アプリにプッシュ通知を送信するフローを作成します。Let's create a flow that will send a push notification to the Microsoft Flow mobile app whenever our GitHub repo receives a git push.

  1. Microsoft Flow Web ポータルで、ページの上部にある [自分のフロー] をクリックします。In the Microsoft Flow web portal, at the top of the page, click My flows.
  2. [一から作成] をクリックします。Click Create from blank.
  3. Microsoft Flow のデザイナーで、前に登録したカスタム コネクタを検索します。In the designer for Microsoft Flow, search for the custom connector we registered earlier.

    新しいトリガー

    一覧で、トリガーとして使用する項目をクリックします。Click on the item in the list to use it as a trigger.

  4. このカスタム コネクタを使用するのは初めてとなるため、これに接続する必要があります。Since this is the first time we've used this custom connector, we have to connect to it. 接続名の場合、わかりやすい名前を入力します。For Connection name, enter a descriptive name. ユーザー名の場合、GitHub ユーザー名を使用します。For User name, use your GitHub username. パスワードの場合、先に作成した個人用アクセス トークンを使用します。For Password, use the personal access token you created earlier.

    新しい接続

    [作成] をクリックします。Click Create.

  5. 次に、監視するリポジトリに関する情報を Microsoft Flow に指定します。Now we need to give Microsoft Flow information about the repo we want to monitor. OpenAPI ファイルの WebhookRequestBody オブジェクトのフィールドを認識できます。You might recognize the fields from the WebhookRequestBody object in the OpenAPI file. 所有者リポジトリに関しては、監視する GitHub リポジトリの所有者名とリポジトリ名を入力します。For owner and repo, enter the owner and repo name of a GitHub repo you want to monitor.

    リポジトリ情報

    重要

    この例では、Visual Studio コードのリポジトリを使用しています。In this example, I'm using the repository for Visual Studio Code. 自分のアカウントに権限が与えられているリポジトリを使用してください。You should use a repo that your account has rights to. 自分のリポジトリを作成すると簡単です。The easiest way to do this would be to use your own repo.

  6. [+ 新しいステップ] をクリックし、[アクションの追加] をクリックします。Click + New step, and then click Add an action.
  7. [プッシュ通知] アクションを見つけて選択します。Search for and select the Push notification action.

    プッシュ通知

  8. [テキスト] フィールドにテキストを入力します。Enter some text in the the Text field. OpenAPI ファイルの WebhookPushResponse オブジェクトでは使用できるパラメーターのリストが定義されていることに注意してください。Note that the WebhookPushResponse object in the OpenAPI file defines the list of parameters you can use.

    プッシュ通知の詳細

  9. ページ上部でフローに名前を付け、[フローの作成] をクリックします。At the top of the page, give the flow a name and click Create flow.

    フロー名

検証とトラブルシューティングVerification and troubleshooting

すべてが正しく設定されていることを確認するには、[自分のフロー] をクリックし、新しいフローの隣にある情報アイコンをクリックし、実行履歴を表示します。To verify everything is set up correctly, click My flows, and then click the information icon next to the new flow to view the run history. webhook 作成で "Succeeded" (成功) の実行が 1 つ以上表示されているはずです。You should already see at least one "Succeeded" run from the webhook creation. GitHub 側で webhook が作成されたことを示します。This indicates that the webhook was created successfully on the GitHub side. 実行に失敗した場合、実行詳細に移動し、失敗した理由を確認できます。If the run failed, you can drill into the run details to see why it failed. 失敗の原因が "404 Not Found" 応答の場合、使用したリポジトリで webhook を作成する権限が GitHub アカウントに与えられていない可能性があります。If the failure was due to a "404 Not Found" response, it's likely your GitHub account doesn't have the correct permissions to create a webhook on the repo you used.

概要Summary

すべてが正しく構成されると、選択した GitHub リポジトリで git プッシュが発生したとき、Microsoft Flow モバイル アプリにプッシュ通知が送信されます。If everything is correctly configured, you will now receive push notifications in the Microsoft Flow mobile app whenever a git push occurs on the GitHub repository you selected. 上記のプロセスを利用すれば、あらゆる webhook 対応サービスをフローのトリガーとして使用できます。Using the process above, you can use any webhook-capable service as a trigger in your flows.

次のステップNext steps