從 OpenAPI 定義建立自訂連接器

注意

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

若要建立自訂連接器,您必須描述您要連線的 API,讓連接器可了解 API 的作業和資料結構。 在此主題中,您使用 OpenAPI 定義 來描述認知服務文字分析情緒 API,以建立自訂連接器 (本系列的範例)。

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

先決條件

匯入 OpenAPI 定義

您現在已準備好使用所下載的 OpenAPI 定義。 定義中包含所有必要資訊,而您可以在執行自訂連接器精靈期間,檢閱及更新此資訊。

從為 Logic Apps 或為 Power Automate 和 Power Apps 匯入 OpenAPI 定義著手。

注意

OpenAPI 定義必須是 OpenAPI 2.0 (以前叫做 Swagger) 格式。 不支援 OpenAPI 3.0 格式的 OpenAPI 定義。

為 Logic Apps 匯入 OpenAPI 定義

  1. 移至 Azure 入口網站,並開啟您稍早在建立 Azure Logic Apps 自訂連接器中建立的 Logic Apps 連接器。

  2. 在連接器的功能表中,選擇 邏輯應用程式連接器,然後選擇 編輯

    邏輯應用程式連接器

  3. 一般 底下,選擇 上傳 OpenAPI 檔案,然後瀏覽至您所建立的 OpenAPI 定義。

    上傳 OpenAPI 檔案

注意

本教學課程著重於 REST API,但是您也可以使用 SOAP API 搭配 Logic Apps

為 Power Automate 和 Power Apps 匯入 OpenAPI 定義

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

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

    選取自訂連接器

  3. 選取 新建自訂連接器,然後選擇 匯入 OpenAPI 檔案

    匯入 OpenAPI 檔案

  4. 輸入自訂連接器的名稱,然後瀏覽至您下載或建立的 Open API 定義,並選擇 繼續

    上傳 Postman 集合

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

檢閱一般詳細資料

從這裡開始,我們將示範 Power Automate UI,但三種技術的步驟大致相同。 我們會指出任何不同之處。 在本主題的這個部分,我們主要會檢閱 UI,並說明值如何對應到 OpenAPI 檔案的各個區段。

  1. 在精靈頂端,確定會將名稱設定為 "SentimentDemo",然後選擇 建立連接器

  2. 一般 頁面上,檢閱從 OpenAPI 定義匯入的資訊,包括 API 主機和 API 基底 URL。 連接器會使用 API 主機和基底 URL 來決定如何呼叫 API。

    自訂連接器一般頁面

    注意

    如需連接至內部部署 API 的詳細資訊,請參閱使用資料閘道連線到內部部署 API

    下列 OpenAPI 定義區段包含此 UI 頁面的資訊:

      "info": {
        "version": "1.0.0",
        "title": "SentimentDemo",
        "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
      },
      "host": "westus.api.cognitive.microsoft.com",
      "basePath": "/",
      "schemes": [
        "https"
      ]
    

檢閱驗證類型

在自訂連接器中,有幾個可用的驗證的選項。 認知服務 API 會使用 API 金鑰驗證,所以這就是 OpenAPI 定義中的指定項目。

安全性 頁面上,檢閱 API 金鑰的驗證資訊。

API 金鑰參數

該標籤會在有人第一次使用自訂連接器進行連線時顯示。您可以選擇 編輯 並變更此值。 參數名稱和位置必須符合 API 的預期 (在此案例中是指 "Ocp-Apim-Subscription-Key" 和「標頭」)。

下列 OpenAPI 定義區段包含此 UI 頁面的資訊:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

檢閱連接器定義

自訂連接器精靈的 定義 頁面會為您提供許多選項,以便定義連接器的運作方式,以及在邏輯應用程式、流程和應用程式中的公開方式。 我們將解釋 UI 並涵蓋本節的幾個選項,但是我們也鼓勵您自行探索。 如需在此 UI 中從頭開始定義物件的資訊,請參閱建立連接器定義

  1. 下列區域會顯示任何動作、觸發程序 (適用於 Logic Apps 和 Power Automate),以及為連接器定義的參考。 在此情況下,會顯示 OpenAPI 定義中的 DetectSentiment 動作。 此連接器中沒有觸發程序,但您可以在使用 Webhook 搭配 Azure Logic Apps 和 Power Automate中了解自訂連接器的觸發程序。

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

  2. 一般 區域會顯示目前所選擇的動作或觸發程序的相關資訊。 您可以在這裡編輯此資訊,包括邏輯應用程式或流程中作業和參數的 可見性 屬性:

    • :正常地顯示於邏輯應用程式或流程中

    • 進階:隱藏在額外的功能表底下

    • 內部:對使用者隱藏

    • 重要:一律優先對使用者顯示

      定義頁面 - 一般

  3. 要求 區域會根據 OpenAPI 定義中包含的 HTTP 要求來顯示資訊。 在此案例中,您會看到 HTTP 動詞命令POST,而 URL 是 "/text/analytics/v2.0/sentiment" (API 的完整 URL 為 "https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment")。 我們很快就會更進一步討論 本文 參數。

    定義頁面 - 要求

    下列 OpenAPI 定義區段包含 UI 一般要求 區域的資訊:

    "paths": {
      "/text/analytics/v2.0/sentiment": {
        "post": {
          "summary": "Returns a numeric score representing the sentiment detected",
          "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
          "operationId": "DetectSentiment"
    
  4. 回覆 區域會根據 OpenAPI 定義中包含的 HTTP 回覆來顯示資訊。 在此案例中,唯一定義的回應適用於 "200" (成功回應),但您可以定義其他回應。

    定義頁面 - 回覆

    下列 OpenAPI 定義區段包含與該回應相關的部分資訊:

    "score": {
     "type": "number",
     "format": "float",
     "description": "score",
     "x-ms-summary": "score"
    },
    "id": {
     "type": "string",
     "description": "id",
     "x-ms-summary": "id"
    }
    

    此區段會顯示連接器傳回的兩個值:idscore。 其包含這些值的資料類型及屬於 OpenAPI 擴充功能的 x-ms-summary 欄位。 如需有關此擴充功能和其他擴充功能的詳細資訊,請參閱擴充自訂連接器的 OpenAPI 定義

  5. 驗證 區域會顯示在 API 定義中偵測到的任何問題。 務必在儲存連接器之前,先檢查這個區域。

    定義頁面 - 驗證

更新定義

您下載的 OpenAPI 定義已是良好的基本範例,但您也可以使用需要大量更新的定義,以便在邏輯應用程式、流程或應用程式中更輕鬆地使用連接器。 我們將示範如何對定義進行簡單的變更。

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

    編輯要求本文

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

    編輯要求本文識別碼

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

    編輯結構描述屬性

    參數
    描述 「您提交之每份文件的數值識別碼」
  4. 參數 區域中,選擇 上一頁,即可返回主要定義頁面。

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

下載更新的 OpenAPI 檔案

您可以從 OpenAPI 檔案、Postman 集合或從頭開始 (在 Power Automate 和 Power Apps 中) 建立自訂連接器。 不論如何建立連接器,您都可以下載 OpenAPI 定義,讓服務於內部使用。

  • 在 Logic Apps 中,請從自訂連接器下載。

    在邏輯應用程式中下載 OpenAPI 定義

  • 在 Power Automate 或 Power Apps 中,從自訂連接器清單中進行下載。

    在 Power Automate 或 Power Apps 中下載 OpenAPI 定義

測試連接器

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

重要

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

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

    新增連接

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

    建立連線

  3. 返回 測試頁面

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

      重新整理連接

    • 在 Power Apps 中,您會前往目前環境中可用的連線清單。 在右上角,選擇齒輪圖示,然後選擇 自訂連接器。 選擇您所建立的連接器,然後返回 測試 頁面。

      服務中的齒輪圖示

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

    測試作業

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

    連接器回覆

後續步驟

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

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