共用方式為

從 Postman 集合建立自訂連接器

  • 發行項

注意

本主題屬於在 Azure Logic Apps、Power Automate 和 Power Apps 中建立及使用自訂連接器的教學課程系列。 請務必閱讀自訂連接器概觀，以了解該程序。

若要建立自訂連接器，您必須描述您要連線的 API，讓連接器可了解 API 的作業和資料結構。 在此主題中，您使用 Postman 集合來描述認知服務文字分析情緒 API，以建立自訂連接器 (本系列的範例)。

如需其他描述 API 的方式，請移至下列主題：

先決條件

匯入 Postman 集合

您現在可以使用您所建立或下載的 Postman 集合。 集合中包含許多必要的資訊。 您也可以在瀏覽自訂連接器精靈時，檢閱並更新此資訊。 從為 Logic Apps 或為 Power Automate 和 Power Apps 匯入 Postman 集合開始。

為 Postman 集合匯入 Logic Apps

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

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

    邏輯應用程式連接器

  3. 在一般下，選擇上傳 Postman 集合 V1，然後瀏覽至您建立的 Postman 集合。

    顯示 [上傳 Postman 集合 V1] 選項的螢幕擷取畫面。

    精靈會匯入集合，然後將它轉換成名為 generatedApiDefinition.swagger.json 的 OpenAPI 定義。

注意

本教學課程著重於 REST API，但是您也可以使用 SOAP API 搭配 Logic Apps。

為 Power Automate 和 Power Apps 匯入 Postman 集合

  1. 前往 make.powerapps.com 或 flow.microsoft.com。

  2. 在瀏覽窗格中，選取資料 > 自訂連接器。

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

  4. 輸入自訂連接器的名稱，然後瀏覽至您下載或建立的 Postman 集合，並選擇繼續。

    顯示匯入集合步驟的螢幕擷取畫面。

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

    精靈會匯入集合，然後將它轉換成名為 generatedApiDefinition.swagger.json 的 OpenAPI 定義。

更新一般詳細資料

從這裡開始，我們將示範 Power Automate UI，但三種技術的步驟大致相同。 我們會醒目提示任何差異。

  1. 在一般頁面上，檢閱從 Postman 集合匯入的資訊，包括主機和 API 基底 URL。 連接器會使用主機和基底 URL 來決定如何呼叫 API。

    注意

    如需連接至內部部署 API 的詳細資訊，請參閱使用資料閘道連線到內部部署 API。

  2. 將描述更新為有意義的內容。 此描述會顯示在自訂連接器的詳細資訊中，並可協助其他使用者理解此連接器是否實用。

    參數 值
    描述 「使用認知服務文字分析情感 API 來判斷文字為正面或負面」

指定驗證類型

在自訂連接器中，有幾個可用的驗證的選項。 認知服務 API 使用 API 金鑰驗證。

  1. 在安全性頁面的驗證類型底下，選擇 API 金鑰。

  2. 在 API 金鑰 底下，指定參數標籤、名稱和位置。 選擇可表達且有意義的標籤。 系統會向使用者顯示此文字，以引導他們使用您的自訂連接器進行連線。 參數名稱和位置必須符合 API 的預期 (在此案例中，是您在 Postman 中指定的標頭)。 選擇 連線。

    API 金鑰參數

    參數 值
    參數標籤 「API 金鑰」
    參數名稱 "Ocp-Apim-Subscription-Key"
    參數位置 「標頭」

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

檢閱及更新連接器定義

自訂連接器精靈會為您提供許多選項，以便定義連接器的運作方式，以及在邏輯應用程式、流程和應用程式中的公開方式。 我們將解釋 UI 並涵蓋本節的幾個選項，但是我們也鼓勵您自行探索。

檢閱 UI 和定義

在定義頁面上的特定步驟之前，讓我們先看一下 UI。

  1. 這個區域會顯示任何動作、觸發程序 (適用於 Logic Apps 和 Power Automate)，以及為連接器定義的參考。 在此情況下，便會顯示 Postman 集合中的 DetectSentiment 動作。 此連接器中沒有觸發程序，但您可以在使用 Webhook 搭配 Azure Logic Apps 和 Power Automate中了解自訂連接器的觸發程序。

    定義頁面 - 動作和觸發程序

  2. 一般區域會顯示目前所選擇的動作或觸發程序的相關資訊。 此資訊來自 Postman 集合。 您可以在這裡編輯此資訊，包括邏輯應用程式或流程中作業和參數的可見性屬性：

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

  3. 要求區域會根據 Postman 集合中包含的 HTTP 要求來顯示資訊。 在此案例中，您會看到 HTTP 動詞命令是 POST，而 URL 是 "/text/analytics/v2.0/sentiment" (API 的完整 URL 為 <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>)。 我們很快就會更進一步討論本文參數。

  4. 回覆區域會根據 Postman 集合中包含的 HTTP 回應顯示資訊。 在此案例中，唯一定義的回應適用於 "200" (成功回應)，但您可以定義其他回應。

  5. 驗證區域會顯示在 API 定義中偵測到的任何問題。 務必在儲存連接器之前，先檢查這個區域。

更新定義

現在讓我們變更下列事項，以便在邏輯應用程式、Power Automate 或 Power Apps 應用程式中更輕鬆地使用連接器。

  1. 在一般區域中，將摘要更新為「傳回代表所偵測到情感的數值分數」。

  2. 在要求區域中，選擇本文，然後選擇編輯。

  3. 在參數區域中，您現在會看到 API 預期的三個參數：id、language 和 text。 依序選擇識別碼和編輯。

  4. 在結構描述屬性區域中更新參數值，然後選擇上一頁。

    編輯結構描述屬性

    參數 值
    標題 「識別碼」
    描述 「您提交之每份文件的識別碼」
    預設值 「1」
    是必要的 「是」

  5. 在參數區域中，選擇語言，然後選擇編輯並使用下列值重複進行您在上方所使用的程序。

    參數 值
    標題 「語言」
    描述 「文字的 2 或 4 個字元語言代碼」
    預設值 「en」
    是必要的 「是」

  6. 在參數區域中，選擇文字，然後選擇編輯並使用下列值重複進行您在上方所使用的程序。

    參數 值
    標題 "文字"
    描述 「要分析情感的文字」
    預設值 無​​
    是必要的 「是」

  7. 在參數 區域中，選擇上一頁，即可返回主要定義頁面。

  8. 在精靈的右上方，選擇更新連接器。

測試連接器

您現已建立連接器，請進行測試以確定它運作正常。 測試目前僅適用於 Power Automate 和 Power Apps。

重要

使用 API 金鑰時，建議不要在建立連接器之後立即進行測試。 在連接器準備好連至 API 之前，可能需要幾分鐘的時間。

  1. 在測試頁面上，選擇新增連線。

  2. 從文字分析 API 輸入 API 金鑰，然後選擇建立連線。

  3. 返回測試頁面：

    • 在 Power Automate 中，您會回到測試頁面。 選擇重新整理圖示，以確保已更新連線資訊。
    • 在 Power Apps 中，您會前往目前環境中可用的連線清單。 在右上角，選擇齒輪圖示，然後選擇自訂連接器。 選擇您所建立的連接器，然後返回測試頁面。

  4. 在測試頁面的文字欄位中輸入值 (其他欄位則使用您先前設定的預設值)，然後選擇測試作業。

  5. 連接器會呼叫 API，您也可以複查回覆，其中包括情緒分數。

    連接器回覆

限制

在 Power Automate 和 Power Apps 中，如果使用 Postman 集合更新現有的自訂連接器，則必須重新進行任何先前的自訂，才能儲存連接器。 例如，您必須重新設定驗證類型、動作參數預設值及其他。

後續步驟

您現已建立自訂連接器並定義其行為，您便可使用連接器。

您也可以在組織內共用連接器和/或讓連接器獲得認證，這樣一來，組織外部人員也可以使用此連接器。

提供意見反應

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