共用方式為


從頭開始建立自訂連接器

本文屬於有關在 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 AppsPower 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 預期的三個參數:idlanguagetext。 選取識別碼,然後選取編輯

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

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

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

後續步驟

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

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

提供意見反應

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