從頭開始建立自訂連接器

注意

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

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

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

注意

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

先決條件

啟動自訂連接器精靈

  1. 登入 Power AppsPower Automate

  2. 在左窗格中,請選取資料 > 自訂連線

    選取自訂連接器的螢幕擷取畫面。

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

    從空白建立的螢幕擷取畫面。

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

    自訂連接器名稱的螢幕擷取畫面。

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

步驟 1:更新一般詳細資料

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

  1. 一般索引標籤中,執行下列動作:

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

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

    自訂連接器一般索引標籤的螢幕擷取畫面。

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

    注意

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

步驟 2:指定驗證類型

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

  1. 安全性索引標籤的驗證類型底下,選取 API 金鑰

    驗證類型的螢幕擷取畫面。

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

    API 金鑰參數的螢幕擷取畫面。

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

步驟 3:建立連接器定義

自訂連接精靈提供許多選項,可讓您定義連接器的功能,以及它在 Logic Apps、流程和應用程式中的公開方式。 我們將解釋 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,您通常會從文件 (例如 Text Analytics API (v2.0)) 取得此資訊。

    [定義] 索引標籤 - 從範例匯入的螢幕擷取畫面。

    參數 數值
    動詞 POST
    URL <https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
    本文 使用以下 JSON 代碼
    {
      "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
是必要的
  1. 參數區域中選取語言,選取編輯,然後重複您在此程序步驟 2 和步驟 3 中用於 id 的流程,並使用以下值。

    參數 數值
    標題 語言
    描述 文字的 2 或 4 個字元語言代碼
    預設值 en
    是必要的
  2. 參數區域中選取文字,選取編輯,然後重複您在此程序步驟 2 和步驟 3 中用於 id 的流程,並使用以下值。

    參數 數值
    標題 文字
    描述 要分析情感的文字
    預設值
    是必要的
  3. 參數區域中,選取返回回到主要定義索引標籤。

  4. 在精靈的右上角,選取更新連接器

步驟 4:(選用) 使用自訂程式碼支援

注意

  • 此步驟是選擇性的。 您可以忽略此步驟,並移至步驟 5:測試連接器,來完成建立連接器的無程式碼體驗。

  • 您可以在公開預覽版中使用自訂程式碼支援。

自訂程式碼會轉換超出現有原則範本範圍的要求和回覆裝載。 轉換包括傳送外部要求以取得額外的資料。 使用程式碼時,其優先順序會比無程式碼定義高。 這代表將執行程式碼,而我們不會將要求傳送給後端。

您可以貼上程式碼,或將上傳包含程式碼的檔案。 您的程式碼必須:

  • 以 C# 編寫。
  • 最長執行時間為五秒。
  • 檔案大小不能大於 1 MB。

有關編寫程式碼的指示和範例,請移至在自訂連接器中編寫程式碼

有關自訂程式碼的常見問題,請移至自訂程式碼常見問題集

  1. 程式碼索引標籤上,使用以下其中一個選項插入您的自訂程式碼:

    • 複製/貼上
    • 選取上傳按鈕。

    如果您選擇上傳自訂程式碼,則只能使用副檔名為 .cs 或 .csx 的檔案。

    上傳自訂程式碼的螢幕擷取畫面。

    重要

    目前,我們只支援程式碼編輯器中醒目顯示的語法。 請務必在本機測試您的程式碼。

  2. 貼上或上傳程式碼後,選取程式碼已停用旁的開關,以啟用您的程式碼。 開關名稱會變更為程式碼已啟用

    您隨時可以啟用或停用程式碼。 若開關為程式碼已停用,則會刪除您的程式碼。

    停用程式碼訊息的螢幕擷取畫面。

  3. 在下拉式清單中選取選項,以選取要套用至自訂程式碼的動作和觸發程序。 如果未選取任何作業,動作和觸發程序 會套用至所有的作業。

    選取動作和觸發程序的螢幕擷取畫面。

步驟 5:測試連接器

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

重要

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

  1. 測試索引標籤上,選取新增連線

    新增連線的螢幕擷取畫面。

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

    建立連線的螢幕擷取畫面。

    注意

    對於需要 Bearer 驗證的 API,請在 API 金鑰之前新增 Bearer 和一個空格。

  3. 返回測試索引標籤,然後執行下列其中一項:

    • 您會回到 Power Automate 中的測試索引標籤。請選取 [重新整理] 圖示,確認已更新連線資訊。

      重新整理連線的螢幕擷取畫面。

    • 在 Power Apps 中,您會前往目前環境中可用的連線清單。 在左窗格中,請選取資料 > 自訂連線。 選擇您所建立的連接器,然後回到測試索引標籤。

      選取自訂連接器的螢幕擷取畫面。

  4. 測試索引標籤上,輸入文字欄位的值 (其他欄位使用先前設定的預設值),然後選取測試作業

    測試作業的螢幕擷取畫面。

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

    連接器回覆的螢幕擷取畫面。

(對於 CLI 使用者) 最佳做法

  • 下載所有連接器,並使用 Git 或任何原始程式碼管理系統來儲存檔案。

  • 如果更新不正確,請藉由使用來自原始程式碼管理系統中的一組正確檔案重新執行 update 命令,以重新部署連接器。

  • 請先在測試環境中測試自訂連接器和設定檔案,然後再在生產環境中進行部署。

  • 每次都請再次檢查環境和連接器識別碼是否正確。

後續步驟

您現已建立自訂連接器並定義其行為,您可以從以下位置使用連接器:

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

提供意見反應

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