從 OpenAPI 定義建立自訂連接器

文章
04/19/2024

注意

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

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

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

先決條件

描述範例 API 範例的 OpenAPI 定義。建立自訂連接器時，OpenAPI 定義必須小於 1 MB。 OpenAPI 定義必須為 OpenAPI 2.0 (先前稱為 Swagger) 格式。

如果有多個安全性定義，則自訂連接器將選擇最上層的安全性定義。自訂連接器建立不支援 OAuth 安全性定義中的用戶端認證 (例如，應用程式和密碼)。
認知服務文字分析 API 的 API 金鑰。
下列其中一項訂閱：
- Azure，如果您使用 Logic Apps
- Power Automate
- Power Apps
如果您使用 Logic Apps，請先建立 Azure Logic Apps 自訂連接器。

匯入 OpenAPI 定義

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

首先匯入 Logic Apps 或 Power Automate 和 Power Apps 的 OpenAPI 定義。

注意

OpenAPI 定義必須為 OpenAPI 2.0 (先前稱為 Swagger) 格式。不支援 OpenAPI 3.0 格式的 OpenAPI 定義。

匯入 Logic Apps 的 OpenAPI 定義

移至 Azure 入口網站，並開啟您稍早在建立 Azure Logic Apps 自訂連接器中建立的 Logic Apps 連接器。
在連接器的功能表中，選取 Logic Apps 連接器，然後選取編輯。
在一般底下，選取上傳 OpenAPI 檔案，然後前往您建立的 OpenAPI 定義。

注意

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

匯入 Power Automate 和 Power Apps 的 OpenAPI 定義

登入 Power Apps 或 Power Automate。
在左窗格中，請選取資料 > 自訂連線。
選取新建自訂連接器，然後選取匯入 OpenAPI 檔案。
輸入自訂連接器的名稱，然後前往您下載或建立的 OpenAPI 定義，並選取繼續。

參數數值

自訂連接器標題 SentimentDemo

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

檢閱一般詳細資料

從這裡開始，我們將示範 Power Automate UI，但三種技術的步驟大致相同。我們會指出任何不同之處。在這一部分的主題中，我們將主要回顧 UI，並顯示值如何對應至 OpenAPI 檔案的區段。

在精靈頂端，確定會將名稱設定為 SentimentDemo，然後選取建立連接器。
在一般頁面上，檢閱從 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 中從頭開始定義物件的資訊，請前往建立連接器定義。

下列區域會顯示任何動作、觸發程序 (適用於 Logic Apps 和 Power Automate)，以及為連接器定義的參考。在此案例中，會顯示 OpenAPI 定義中的 DetectSentiment 動作。此連接器中沒有觸發程序，但您可以在使用 Webhook 搭配 Azure Logic Apps 和 Power Automate中了解自訂連接器的觸發程序。
一般區域會顯示目前所選擇的動作或觸發程序的相關資訊。您可以在這裡編輯此資訊，包括邏輯應用程式或流程中作業和參數的可見性屬性：
- 無：正常地顯示於邏輯應用程式或流程中
- 進階：隱藏在額外的功能表底下
- 內部：對使用者隱藏
- 重要：一律優先對使用者顯示
要求區域會根據 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"
```
回覆區域會根據 OpenAPI 定義中包含的 HTTP 回覆來顯示資訊。在此案例中，唯一定義的回應適用於 200 (成功回覆)，但您可以定義其他回覆。

OpenAPI 定義的以下區段包含與回覆的相關資訊：
```
"score": {
 "type": "number",
 "format": "float",
 "description": "score",
 "x-ms-summary": "score"
},
"id": {
 "type": "string",
 "description": "id",
 "x-ms-summary": "id"
}
```
此區段會顯示連接器傳回的兩個值：id 和 score。它包含其資料類型，以及 x-ms-summary 欄位 (副檔名為 OpenAPI)。如需此及其他擴充功能的詳細資訊，請前往擴充自訂連接器的 OpenAPI 定義。
驗證區域會顯示在 API 定義中偵測到的任何問題。務必在儲存連接器之前，先檢查這個區域。

更新定義

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

在要求區域中，選取本文，然後選取編輯。
在參數區域中，您現在會看到 API 預期的三個參數：ID、Language 和 Text。選取識別碼，然後選取編輯。
在結構描述屬性區域中更新參數的描述，然後選取上一頁。

參數數值

描述您提交之每份文件的數值識別碼
在參數區域中，選取上一頁，即可返回主要定義頁面。
在精靈的右上角，選取更新連接器。

參數	數值
描述	您提交之每份文件的數值識別碼

下載已更新的 OpenAPI 檔案

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

在 Logic Apps 中，請從自訂連接器下載。
在 Power Automate 或 Power Apps 中，從自訂連接器清單中進行下載。

測試連接器

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

重要

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

在測試頁面上，選取新增連線。
從文字分析 API 輸入 API 金鑰，然後選取建立連線。
返回測試頁面，然後執行下列其中一項：
- 在 Power Automate 中，您會回到測試頁面。選取重新整理圖示，以確保已更新連線資訊。
- 在 Power Apps 中，您會前往目前環境中可用的連線清單。選取右上角的齒輪圖示，然後選取自訂連接器。選擇您所建立的連接器，然後返回測試頁面。
在測試頁面的文字欄位中輸入值 (其他欄位則使用您先前設定的預設值)，然後選取測試作業。
連接器會呼叫 API，您也可以複查回覆，其中包括情緒分數。