從頭開始建立自訂連接器

注意

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

若要建立自訂連接器,您必須描述您要連線的 API,讓連接器可了解 API 的作業和資料結構。 在此主題中,您可以從頭開始建立自訂連接器,而不需使用 Postman 集合OpenAPI 定義 來描述認知服務文字分析情緒 API(本系列的範例)。 相反地,您完全在自訂連接器精靈中描述連接器。

如需其他描述 API 的方式,請參閱下列主題:

注意

您目前可以在 Power Automate 和 Power Apps 中從頭開始建立自訂連接器。 對於 Logic Apps,您必須至少以基本 OpenAPI 定義Postman 集合開頭。

先決條件

啟動自訂連接器精靈

  1. 前往 make.powerapps.comflow.microsoft.com

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

    選取自訂連接器

  3. 選取 新建自訂連接器,然後選擇 從空白建立

    從空白建立

  4. 輸入自訂連接器的名稱,然後選取 繼續

    輸入自訂連接器名稱

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

更新一般詳細資料

從這裡開始,我們將示範 Power Automate UI,但這些技術的步驟大致相同。 我們會指出任何不同之處。

  1. 一般 頁面上:

    • 描述 輸入有意義的值。 此描述會顯示在自訂連接器的詳細資訊中,並可協助其他人知道此連接器是否對他們有用。

    • 主機 更新至文字分析 API 的位址。 連接器會使用 API 主機和基底 URL 來決定如何呼叫 API。

    自訂連接器一般頁面

    參數
    描述 「使用認知服務文字分析情感 API 來判斷文字為正面或負面」
    主機 "westus.api.cognitive.microsoft.com"

    注意

    如需 透過內部部署資料閘道連線 選項的詳細資訊,請參閱使用資料閘道連線到內部部署 API

指定驗證類型

在自訂連接器中,有幾個可用的驗證的選項。 認知服務 API 使用 API 金鑰驗證,因此這正是您為此教學課程指定的內容。

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

    驗證類型

  2. API 金鑰 底下,指定參數標籤、名稱和位置。 指定有意義的標籤,因為當有人第一次使用自訂連接器進行連線時,這會顯示出來。 參數名稱和位置必須符合 API 所預期的。 選擇 連線

    API 金鑰參數

    參數
    參數標籤 「API 金鑰」
    參數名稱 "Ocp-Apim-Subscription-Key"
    參數位置 「標頭」
  3. 在精靈頂端,確定會將名稱設定為 "SentimentDemo",然後選擇 建立連接器

建立連接器定義

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

建立動作

第一件事是建立呼叫文字分析情緒 API 的動作。

  1. 定義 頁面上,左側區域會顯示為連接器定義的任何動作、觸發程序 (適用於 Logic Apps 和 Power Automate) 及參考。 選擇 新增動作

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

    此連接器中沒有觸發程序,但您可以在使用 Webhook 搭配 Azure Logic Apps 和 Power Automate中了解自訂連接器的觸發程序。

  2. 一般 區域會顯示目前所選擇的動作或觸發程序的相關資訊。 新增此動作的摘要、描述及作業識別碼。

    定義頁面 - 一般

    參數
    摘要 「傳回代表偵測到情緒的數值分數」
    描述 「此 API 會傳回 0 到 1 之間的數值分數。 分數接近 1 時,表示正面情感;分數接近 0 時,則表示負面情感。」
    作業識別碼 "DetectSentiment"

    顯示性 屬性設為 。 此屬性適用於邏輯應用程式或流程中的作業和參數,有下列選項:

    • :正常地顯示於邏輯應用程式或流程中
    • 進階:隱藏在額外的功能表底下
    • 內部:對使用者隱藏
    • 重要:一律優先對使用者顯示
  3. 要求 區域會根據動作的 HTTP 要求來顯示資訊。 選擇 從範例匯入

    定義頁面 - 從範例匯入

  4. 指定連接至 API 所需的資訊,以及要求本文,然後選擇 匯入。 我們為您提供此資訊(影像下方)。 至於公用 API,通常會從文件取得它(例如文字分析情緒 API)。

    定義頁面 - 從範例匯入

    參數
    動詞 「POST」
    URL "https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"
    本文 請參閱下文
    {
      "documents": [
        {
          "language": "string",
          "id": "string",
          "text": "string"
        }
      ]
    }
    
  5. 回覆 區域會根據動作的 HTTP 回覆來顯示資訊。 選擇 新增預設回應

    定義頁面 - 回覆

  6. 指定回覆本文,然後選擇 匯入。 與要求一樣,我們為您提供此資訊,但是通常是在 API 文件中。

    定義頁面 - 回覆

    {
     "documents": [
       {
         "score": 0.0,
         "id": "string"
       }
     ],
     "errors": [
       {
         "id": "string",
         "message": "string"
       }
     ]
    }
    
  7. 驗證 區域會顯示在 API 定義中偵測到的任何問題。 檢查狀態,然後在精靈的右上部選擇 更新連接器

    定義頁面 - 驗證

更新定義

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

  1. 要求 區域中,選擇 本文,然後選擇 編輯

    編輯要求本文

  2. 參數 區域中,您現在會看到 API 預期的三個參數:idlanguagetext。 依序選擇 識別碼編輯

    編輯要求本文識別碼

  3. 結構描述屬性 區域中更新參數值,然後選擇 上一頁

    編輯結構描述屬性

    參數
    標題 「識別碼」
    描述 「您提交之每份文件的識別碼」
    預設值 「1」
    是必要的 「是」
  4. 參數 區域中,選擇 語言,然後選擇 編輯 並使用下列值重複進行您用於 id 的程序。

    參數
    標題 「語言」
    描述 「文字的 2 或 4 個字元語言代碼」
    預設值 「en」
    是必要的 「是」
  5. 參數 區域中,選擇 文字,然後選擇 編輯 並使用下列值重複進行您用於 idlanguage 的程序。

    參數
    標題 "文字"
    描述 「要分析情感的文字」
    預設值 無​​
    是必要的 「是」
  6. 參數 區域中,選擇 上一頁,即可返回主要定義頁面。

  7. 在精靈的右上方,選擇 更新連接器

測試連接器

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

重要

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

  1. 測試 頁面上,選擇 新增連線

    新增連接

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

    建立連線

  3. 返回 測試頁面

    • 在 Power Automate 中,您會回到 測試 頁面。 選擇重新整理圖示,以確保已更新連線資訊。

      重新整理連接

    • 在 Power Apps 中,您會前往目前環境中可用的連線清單。 在瀏覽窗格中,選擇 資料 > 自訂連接器。 選擇您所建立的連接器,然後返回 測試 頁面。

      選取自訂連接器

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

    測試作業

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

    連接器回覆

後續步驟

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

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