從頭開始建立自訂連接器

  • 發行項

注意

本主題屬於在 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 Apps 或 Power 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 預期的三個參數：id、language 和 text。 選取識別碼，然後選取編輯。

    編輯要求本文識別碼的螢幕擷取畫面。

  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 命令，以重新部署連接器。

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

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

後續步驟

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

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

提供意見反應

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