使用 Webhook 作為 Azure Logic Apps 和 Power Automate 的觸發程序

  • 發行項

Webhook 是用來提供事件通知的簡單 HTTP 回呼。 Azure Logic Apps 和 Power Automate 兩者都可讓您使用 Webhook 作為觸發程序。 邏輯應用程式或流程會接聽此觸發程序，並在觸發程序引發時執行動作。 本教學課程示範如何使用 Webhook 做為觸發程序。

注意

我們將使用 GitHub 做為服務的範例，可以透過 Webhook 傳送通知，但此處所示範的技巧可以延伸到使用 Webhook 的任何服務。

先決條件

OpenAPI 定義

Webhook 會在 Logic Apps 和 Power Automate 中當作自訂連接器的一部分來進行實作，所以您需要提供可定義 Webhook 圖形的 OpenAPI 定義。 如果要建立觸發程序，但沒有 OpenAPI 定義，則可以使用自訂連接器精靈中的觸發程序 UI 來定義 Webhook 觸發程序。

OpenAPI 定義包含讓 Webhook 得以運作的三個關鍵部分：

  • 建立 webhook
  • 定義來自 API 的連入勾點要求 (在此案例中，GitHub)
  • 刪除 webhook

建立 webhook

webhook 是在 GitHub 端由 HTTP POST 建立至 /repos/{owner}/{repo}/hooks。 建立新的邏輯應用程式或流程時，會使用 OpenAPI 定義中定義的觸發程序，將它張貼到此 URL。 也會在觸發程序被修改時張貼至 URL。 在下面範例中，post 屬性包含張貼到 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 targeted 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" 屬性是結構描述擴充功能，可指示 Logic Apps 和 Power Automate 在設計工具中可用的觸發程序清單中顯示此 Webhook，所以請務必要將它納入。

定義來自 API 的傳入勾點要求

如先前範例所示，傳入勾點要求 (從 GitHub 傳送至 Logic Apps 或 Power Automate 的通知) 的圖形已於自訂 x-ms-notification-content 屬性中定義。 不需要包含要求的整個內容，只要包含您想要在邏輯應用程式或流程中使用的部分。

刪除 Webhook

OpenAPI 定義必須包含刪除 Webhook 方法的定義。 如果您更新觸發程序，而且刪除邏輯應用程式或流程，Logic Apps 和 Power Automate 會嘗試刪除 Webhook。

"/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 targeted 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"
        }
    ]
    }
},

刪除 webhook 呼叫不包含教學課程標頭。 連接器中使用的相同連線也用於刪除 webhook 呼叫。

重要

為了讓 Logic Apps 或 Power Automate 刪除 Webhook，API 必須在建立 Webhook 時於 201 回應中包含 Location HTTP 標頭。 Location 標頭應該包含用於 HTTP DELETE 的 Webhook 路徑。 例如，Location 隨附下列格式的 GitHub 回應︰https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>。

在 GitHub 中啟用驗證

將 Webhook 要求傳送至 Logic Apps 或 Power Automate 的 API 通常會使用某種形式的驗證，而 GitHub 也不例外。 GitHub 支援數種驗證類型；我們會使用 GitHub 個人存取權杖進行此教學課程。

  1. 瀏覽至 GitHub，如果您尚未登入，請登入。

  2. 在右上方，選取您的設定檔圖片，然後在功能表中，選擇設定。

    設定

  3. 在左邊功能表中選擇開發人員設定，然後選擇個人存取權杖。

  4. 選擇產生新權杖按鈕，然後根據要求確認您的密碼。

    產生新權杖

  5. 在權杖描述方塊中輸入描述。

  6. 選取 admin:repo_hook 核取方塊。

    admin:repo_hook

  7. 選擇產生權杖按鈕。

  8. 記下新的權杖。

    新權杖

    重要

    您無法再存取此權杖。 您應該複製並貼到其他位置，稍後在本教學課程中使用。

匯入 OpenAPI 定義

首先匯入 Logic Apps 或 Power Automate 的 OpenAPI 定義。

匯入 Logic Apps 的 OpenAPI 定義

  1. 前往 Azure 入口網站，並開啟您稍早在建立 Azure Logic Apps 自訂連接器中建立的 Logic Apps 連接器。

  2. 在連接器的功能表中，選擇邏輯應用程式連接器，然後選擇編輯。

    邏輯應用程式連接器

  3. 在一般底下，選擇上傳 OpenAPI 檔案，然後瀏覽至您下載的 OpenAPI 檔案。

    顯示 [上傳 OpenAPI 檔案] 選項的螢幕擷取畫面。

匯入 Power Automate 的 OpenAPI 定義

  1. 移至 flow.microsoft.com。

  2. 在右上角，選擇齒輪圖示，然後選擇自訂連接器。

    自訂連接器

  3. 選擇建立自訂連接器，然後選擇匯入 Postman 集合。

    建立自訂連接器

  4. 輸入自訂連接器的名稱，然後瀏覽至您下載的 OpenAPI 檔案，並選擇連線。

    顯示用於輸入名稱之欄位的螢幕擷取畫面。

    參數 值
    自訂連接器標題 "GitHubDemo"

完成建立自訂連接器

  1. 在一般頁面上，選擇繼續。

  2. 在安全性頁面的驗證類型底下，選取基本驗證。

  3. 在基本驗證區段的標籤欄位中，輸入文字使用者名稱和密碼。 這些都是在 Logic Apps 或流程中使用觸發程序時將會顯示的標籤。

    基本驗證

  4. 在精靈頂端，確定會將名稱設定為 "GitHubDemo"，然後選擇建立連接器。

您現在已準備好在邏輯應用程式或流程中使用觸發程序，或者您也可以閱讀如何從 UI 建立觸發程序。

從 UI 建立 Webhook 觸發程序

在本節中，我們將說明如何在 UI 中建立觸發程序，而不需要 OpenAPI 定義中的任何觸發程序定義。 從基準 OpenAPI 定義開始，或在自訂連接器精靈中從頭開始。

  1. 在一般頁面上，確定指定描述和 URL。

    參數 值
    描述 「GitHub 是社交原始程式碼存放庫。」
    URL "api.github.com"

  2. 在安全性頁面上，設定基本驗證（如您在上一節中所進行的工作）。

  3. 在定義頁面上，選擇 + 新增觸發程序，然後填入觸發程序的描述。 在此範例中，您建立會在對存放庫進行提取要求時引發的觸發程序。

    建立觸發程序-1

    參數 值
    摘要 「對選定存放庫發出拉取要求時觸發」
    描述 「對選定存放庫發出拉取要求時觸發」
    作業識別碼 "webhook-PR-觸發程序"
    可視性 "無" (如需詳細資訊，請參閱下方)
    觸發程序類型 "Webhook"

    適用於邏輯應用程式或流程中作業和參數的顯示性屬性有下列選項：

    • 無：正常地顯示於邏輯應用程式或流程中
    • 進階：隱藏在額外的功能表底下
    • 內部：對使用者隱藏
    • 重要：一律優先對使用者顯示

  4. 要求區域會根據動作的 HTTP 要求來顯示資訊。 選擇從範例匯入。

    定義頁面 - 從範例匯入

  5. 定義 Webhook 觸發程序的要求，然後選擇匯入。 我們提供範例，讓您匯入 (影像下方)。 如需詳細資訊，請參閱 GitHub API 參考。 Logic Apps 和 Power Automate 會自動新增標準 content-type 和安全性標頭，所以從範例匯入時，您不需要定義這些項目。

    建立觸發程序-2

    參數 值
    動詞命令 「POST」
    URL "https://api.github.com/repos/{owner}/{repo}/hooks"
    本文 請參閱下文 
    {
  "name": "web",
  "active": true,
  "events": [
    "pull_request"
  ],
  "config": {
    "url": "http://example.com/webhook"
  }
}

  6. 回覆區域會根據動作的 HTTP 回覆來顯示資訊。 選擇新增預設回應。

    定義頁面 - 回覆

  7. 定義 Webhook 觸發程序的回覆，然後選擇匯入。 同樣的，我們提供範例，讓您匯入。 如需詳細資訊，請參閱 GitHub API 參考。

    建立觸發程序-3

    {
  "action": "opened",
  "number": 1,
  "pull_request": {
    "html_url": "https://github.com/baxterthehacker/public-repo/pull/1",
    "state": "open",
    "locked": false,
    "title": "Update the README with new information",
    "user": {
      "login": "baxterthehacker",
      "type": "User"
    }
  }
}

  8. 在觸發程序設定區域中，選取應接收來自 GitHub 之回撥 URL 值的參數。 這是 config 物件中的 url 屬性。

    建立觸發程序-4

  9. 在精靈的頂端，輸入名稱，然後選擇建立連接器。

使用 Webhook 作為觸發程序

您現在已設定好所有項目，因此可以在邏輯應用程式或流程中使用 webhook。 接下來建立流程，該流程會在您的 GitHub 存放庫接收 git 推送時將推播通知傳送至 Power Automate 行動應用程式。

  1. 在 flow.microsoft.com 中，在頁面頂端選擇我的流程。

  2. 選擇從空白建立，然後選擇下一頁的搜尋數百個連接器和觸發程序。

    搜尋連接器

  3. 在 Power Automate 的設計工具中，搜尋您稍早註冊的自訂連接器。

    新增觸發程序

    選擇清單中要用來做為觸發程序的項目。

  4. 由於這是您第一次使用此自訂連接器，您必須連線至該連接器。 輸入連接資訊，然後選擇建立。

    新連線

    參數 值
    連線名稱 描述性名稱
    使用者名稱 您的 GitHub 使用者名稱
    密碼 您稍早建立的個人存取權杖

  5. 輸入您想要監視的存放庫詳細資料。 您可以從 OpenAPI 檔案中的 WebhookRequestBody 物件辨識欄位。

    存放庫資訊

    參數 數值
    負責人 要監控的存放庫負責人
    repo 要監控的存放庫

    重要

    您應該使用您的帳戶具有權限的存放庫。 若要這樣做，最簡單的方法是使用您自己的存放庫。

  6. 選擇 + 新增步驟，然後選擇新增動作。

  7. 搜尋並選取推播通知動作。

    推播通知

  8. 使用動態內容對話方塊中的值，在文字欄位和其他欄位中輸入一些文字。 請注意，這些值來自 OpenAPI 檔案中的 WebhookPushResponse 物件。

    推播通知詳細資料

    參數 數值
    連線名稱 描述性名稱
    使用者名稱 您的 GitHub 使用者名稱
    密碼 您稍早建立的個人存取權杖

  9. 在頁面頂端，提供流程名稱，然後選擇建立流程。

    流程名稱

驗證與疑難排解

若要確認一切已正確設定，請選擇我的流程，然後選擇新流程旁邊的資訊圖示，以檢視執行歷程記錄：

  • 您應該會在 webhook 建立作業中看到至少一個「成功」執行。 這表示在 GitHub 端成功建立 webhook。

  • 如果執行失敗，您可以切入執行詳細資料，以查看失敗的原因。 如果失敗是因為「404 找不到」回應，很可能是您的 GitHub 帳戶沒有在您所使用的存放庫上建立 webhook 的正確權限。

摘要

如果一切都已正確設定，您會在每當您選取的 GitHub 存放庫上發生 git 推送時，在 Power Automate 行動應用程式中立即收到推播通知。 使用上述程序，您可以使用任何支援 webhook 的服務做為您的流程中的觸發程序。

後續步驟

提供意見反應

非常感謝您提供有關連接器平台問題，或新功能構想的意見反應。 若要提供意見反應，請移至提交問題或取得連接器說明，然後選取您的意見反應類型。