共用方式為

從頭開始建立自訂連接器

  • 發行項

本文屬於有關在 Azure Logic Apps、Microsoft Power Automate 與 Microsoft Power Apps 中建立和使用自訂連接器的教學課程系列。

注意

請務必閱讀自訂連接器概觀，以了解該程序。

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

有關描述 API 的另一個方式，請移至從 OpenAPI 定義建立自訂連接器。

注意

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

先決條件

啟動自訂連接器精靈

  1. 登入 Power Apps 或 Power Automate。

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

  3. 選取新增自訂連接器 > 從空白建立。

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

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

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

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

在一般索引標籤中，執行下列動作：

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

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

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

步驟 2：指定驗證類型

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

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

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

    參數 數值
    參數標籤 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>
    Body 使用以下 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. 在結構描述屬性區域中更新參數值，然後選取上一頁。

    參數 數值
    名稱 識別碼
    描述: 您提交之每份文件的識別碼
    Default value 7
    是必要的 .是

  4. 在參數區域中，選取語言 > 編輯，然後使用下列值重複您在此程序步驟 2 和 3 中用作 id 的過程。

    參數 數值
    名稱 語言
    描述: 文字的兩字元或四字元語言代碼
    Default value en
    是必要的 .是

  5. 在參數區域中，選取文字 > 編輯，然後使用下列值重複您在此程序步驟 2 和 3 中用作 id 的過程。

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

  6. 在參數區域中，選取返回回到主要定義索引標籤。

  7. 在精靈的右上角，選取更新連接器。

步驟 4：(選用) 啟用連接器做為 AI 外掛程式

只有在您打算對連接器進行認證時，才要使用連接器的 AI 外掛程式 (預覽版) 索引標籤。 為了讓連接器用作 AI 外掛程式，連接器必須經過認證。

啟用連接器做為 AI 外掛程式之前，請確定您了解 AI 外掛程式案例的使用案例，並已審視其他考量事項，例如可支援性、最佳做法和建議。 其他資訊：建立連接器 AI 外掛程式 (預覽版)

  1. 在左側導覽窗格上，選取自訂連接器。

    如果沒有看到自訂連接器，請選取更多 > 探索所有 > 自訂連接器。 選項會出現在左側導覽窗格中。

  2. 在右上角，從新增自訂連接器功能表選取選項。

  3. 確定您已完成本文中的步驟 1、步驟 2 和步驟 3。

  4. 選取 AI 外掛程式 (預覽版) 索引標籤。

  5. 在外掛程式資訊清單區段中，輸入詳細資料以將此連接器啟用為 AI 外掛程式。

    「外掛程式資訊清單」頁面中欄位的螢幕擷取畫面。

    欄位 Description
    外掛程式資訊清單：名稱 AI 外掛程式的名稱。
    外掛程式資訊清單：描述 AI 外掛程式的描述。 其他資訊：建立連接器 AI 外掛程式 (預覽版)
    外掛程式資訊清單：連絡人電子郵件 此 AI 外掛程式連絡人的電子郵件地址。
    外掛程式資訊清單：法律資訊 URL 發佈與 AI 外掛程式相關之法律資訊所在的可公開存取位置。

  6. 向下捲動至外掛程式動作詳細資料區段，並輸入連接器 AI 外掛程式中每個動作的動作詳細資料。

    「外掛程式動作詳細資料」頁面中欄位的螢幕擷取畫面。

    欄位 Description
    外掛程式動作詳細資料：摘要 有關使用者所能執行之每個 AI 外掛程式動作的摘要。
    外掛程式動作詳細資料：描述 使用者可在此特定 AI 外掛程式動作步驟方面執行之每項動作的描述。
    核取方塊：啟用為 Copilot 外掛程式作業 核取方塊中出現核取記號時，表示已啟用 AI 外掛程式作業。
    核取方塊：需要使用者確認嗎？ 核取方塊中出現核取記號時，表示需要使用者確認。

    提示

    如果需要定義您的動作的協助，請開啟 Swagger 編輯器切換。

  7. 向下捲動至參數區段，並輸入連接器 AI 外掛程式的參數詳細資料。

    「參數」頁面中欄位的螢幕擷取畫面。

    欄位 Description
    參數：名稱 參數的名稱。 使用可識別的名稱，例如帳戶識別碼而不是識別碼。
    參數：描述 參數的描述。 使用描述性說明，例如 MM/DD/YYYY 格式的連絡人出生日期，而不是 b_date。 這樣的名稱和描述可協助 LLM (大型語言模型) 與 AI 外掛程式有效互動。
    參數：摘要 有關參數的摘要資訊。
    參數：預設值 參數的預設值。

  8. 在 AI 外掛程式 (預覽版) 區段下方的要求區段中，選取輸入參數，然後輸入描述。

步驟 5：(選用) 使用自訂程式碼支援

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

注意

  • 此步驟是選擇性的。 您可以忽略此步驟，並移至步驟 6：測試連接器，來完成建立連接器的無程式碼體驗。
  • 您可以在公開預覽版中使用自訂程式碼支援。

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

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

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

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

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

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

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

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

    重要

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

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

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

  3. 在功能表中選取選項，以選取要套用至自訂程式碼的動作和觸發程序。 如果未選取任何作業，則會將動作和觸發程序套用至所有作業。

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

步驟 6：測試連接器

您現已建立連接器，請進行測試以確定它運作正常。 測試目前僅適用於 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 命令，以重新部署連接器。

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

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

後續步驟

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

您還可以在組織內共用連接器，或為連接器取得認證，讓組織外部人員也能使用此連接器。

提供意見反應

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