PowerApps 文件

在 PowerApps 中註冊及使用自訂連接器

由 Michael Blythe 提供

2017年4月28日

其他文章

本文內容：

必要條件
自訂連接器程序的步驟
描述 API
註冊自訂連接器
使用自訂連接器
共用自訂連接器
後續步驟

PowerApps 可讓您建置完整的精選 App，而不需要使用傳統應用程式程式碼。但在某些情況下，您需要擴充 PowerApps 功能，而 Web 服務十分適合。您的應用程式可以連接到服務、執行作業，以及取回資料。當您具有要使用 PowerApps 連接的 Web 服務時，會將服務註冊為自訂連接器。這個程序可讓 PowerApps 了解 Web API 的特性，包括它所需的驗證、所支援的作業，以及所有這些作業的參數和輸出。

在本主題中，我們將查看註冊及使用自訂連接器所需的步驟，並使用 Azure 辨識服務 Text Analytics API 作為範例。這個 API 會識別傳遞給它的文字中的語言、人氣和關鍵片語。下圖顯示服務、透過它所建立的自訂連接器與呼叫 API 的應用程式之間的互動。

API、自訂連接器和應用程式

必要條件

PowerApps 帳戶。
JSON 格式的 OpenAPI 檔案、OpenAPI 定義的 URL，或 API 的 Postman Collection。如果您沒有上述任何項目，我們將提供您的指引。
要作為自訂連接器圖示的影像 (選擇性)。

自訂連接器程序的步驟

自訂連接器程序有幾個步驟，我們將簡單說明如下。本文假設您已經有 RESTful API 以及某種類型的驗證存取權，因此我們在文件的其餘部分將著重於步驟 3-6。如需步驟 1 和 2 的範例，請參閱為 PowerApps 建立自訂 Web API。

使用您選擇的語言和平台，來建置 RESTful API。針對 Microsoft 技術，建議使用下列其中一項。
- Azure Functions
- Azure Web Apps
- Azure API 應用程式
使用下列其中一種驗證機制，來保護 API。您可以允許未驗證存取 API，但不建議這麼做。
- Azure Active Directory。如需詳細資訊，請參閱在 PowerApps 中搭配使用 Azure Active Directory 與自訂連接器。
- 特定服務 (例如 Dropbox、Facebook 和 SalesForce) 的 OAuth 2.0
- 一般 OAuth 2.0
- API 金鑰
- 基本驗證
使用兩種業界標準方式的其中一種，來描述 API，讓 PowerApps 可以與之連接。
- OpenAPI 檔案 (也稱為 Swagger 檔案)
- Postman Collection
您也可以在註冊程序的步驟 4 建置 OpenAPI 檔案。
在 PowerApps 中使用精靈，來註冊自訂連接器，而您可以在此精靈中指定 API 描述、安全性詳細資料和其他資訊。
在應用程式中使用自訂連接器。在應用程式中建立與 API 的連線，以及呼叫 API 所提供的任何作業，就像您在 PowerApps 中呼叫原生函式一樣。
共用自訂連接器，就像在 PowerApps 中執行其他資料連線一樣。這是選擇性步驟，但可以跨多個應用程式建立者來共用自訂連接器。

描述 API

假設您有某種類型的驗證存取權的 API，則需要有一種方式來描述 API，讓 PowerApps 可以與之連接。若要這樣做，您可以從「任何」 REST API 端點建立 OpenAPI 檔案或 Postman Collection，包括：

公開可用的 API。有些範例包含 Spotify、Uber、Slack、Rackspace 等等。
您建立和部署到任何雲端主機服務提供者 (包括 Azure、Amazon Web Services (AWS)、Heroku、Google Cloud 等等) 的 API。
在您網路上的自訂企業營運 API 部署 (只要在公用網際網路上公開該 API)。

OpenAPI 檔案和 Postman Collections 使用不同的格式，但兩者都是無從驗證語言的電腦可讀取文件，可描述 API 作業和參數︰

您可以根據建置 API 的語言和平台，使用各種工具來產生這些文件。如需 OpenAPI 檔案的範例，請參閱 Text Analytics API 文件。
如果您還沒有 API 的 OpenAPI 檔案，而且不想要建立 OpenAPI 檔案，則仍然可以使用 Postman Collection 輕鬆地建立自訂連接器。如需詳細資訊，請參閱建立 Postman Collection。
PowerApps 最後會在幕後使用 OpenAPI，以將 Postman Collection 剖析和轉譯為 OpenAPI 定義檔。

注意：檔案大小必須小於 1MB。

開始使用 OpenAPI 和 Postman

如果您不熟悉 OpenAPI，請參閱 swagger.io 網站上的開始使用 OpenAPI。
如果您不熟悉 Postman，請從其網站安裝 Postman app。
如果您的 API 是以 Azure API Apps 或 Azure Functions 建置，請參閱將 Azure 裝載的 API 匯出至 PowerApps 和 Microsoft Flow 以取得詳細資訊。

註冊自訂連接器

您現在將使用 OpenAPI 檔案或 Postman Collection，在 PowerApps 中註冊自訂連接器。

在 powerapps.com 的左功能表中，選取 [連線]。選取省略符號 (...)，然後選取右上角的 [管理自訂連接器]。

秘訣︰如果您找不到在行動瀏覽器的哪個位置管理自訂連接器，則它可能是在左上角的功能表下方。
選取 [建立自訂連接器]。
在 [一般] 索引標籤中，選擇您要如何建立自訂連接器。
- 上傳 OpenAPI 檔案
- 使用 OpenAPI URL
- 上傳 Postman Collection V1
上傳自訂連接器的圖示。 [描述]、[主機] 和 [基底 URL] 欄位一般會自動填入 OpenAPI 檔案中的資訊。如果它們未自動填入資訊，則您可以新增這些欄位的資訊。選取 [繼續]。
在 [安全性] 索引標籤上，輸入任何驗證內容。
- 根據 OpenAPI securityDefinitions 物件中所定義的資訊，自動填入驗證類型。以下是 OAuth2.0 範例。
```
"securityDefinitions": {
    "AAD": {
    "type": "oauth2",
    "flow": "accessCode",
    "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
    "scopes": {}
    }
},
```
- 如果 OpenAPI 檔案未使用 securityDefintions 物件，則不需要任何其他值。
- 使用 Postman Collection 時，只有在使用支援的驗證類型 (例如 OAuth 2.0 或 Basic) 時，才會自動填入驗證類型。
- 如需設定 Azure Active Directory (AAD) 驗證的範例，請參閱為 PowerApps 建立自訂 Web API。
在 [定義] 索引標籤中，會自動填入 OpenAPI 檔案或 Postman Collection 中所定義的所有作業以及要求和回應值。如果已定義所有必要作業，則可以移至註冊程序中的步驟 6，而不需要在此畫面上進行任何變更。

如果您想要編輯現有動作，或將新的動作新增至自訂連接器，請繼續閱讀下方。
1. 如果您想要新增 OpenAPI 檔案或 Postman Collection 中沒有的動作，請選取左窗格中的 [新增動作]並使用作業的名稱、描述和可見性來填入 [一般] 區段。
2. 在 [要求] 區段中，選取右上方的 [從範例匯入]。在右邊的表單中，貼入範例要求。範例要求通常位於 API 文件中，您可以在其中取得資訊來填寫 [動詞]、[要求 URL]、[標頭] 和 [主體] 欄位。如需範例，請參閱 Text Analytics API 文件。
3. 選取 [匯入]，以完成要求定義。以類似的方式定義回應。
定義所有作業之後，請選取 [建立] 來建立自訂連接器。
建立自訂連接器之後，請移至 [測試] 索引標籤來測試 API 中所定義的作業。選擇連線，並提供輸入參數來測試作業。

如果呼叫成功，您會取得有效的回應。

使用自訂連接器

既然您已經註冊 API，請將自訂連接器新增至應用程式，就像新增任何其他資料來源一樣。我們將在這裡探討一個簡短的範例。如需資料連線的詳細資訊，請參閱在 PowerApps 中新增資料連線。

在 PowerApps Studio 的右窗格中，按一下或點選 [新增資料來源]。
按一下或點選您所建立的自訂連接器。
完成登入您要連線之服務所需的任何步驟。如果您的 API 使用 OAuth 驗證，則可能會看到登入畫面。若為 API 金鑰驗證，系統可能會提示您輸入金鑰值。
在應用程式中呼叫 API。在此範例中，我們建立的應用程式將文字提交給辨識服務，並收到人氣分數 0 到 1，而應用程式將其顯示為百分比。
- 使用此連接器時，如果您開始在公式列中輸入 "Az"，則會看到 API 和可用的作業。
- 完整呼叫如下所示，其中我們從 TextInput 控制項傳入文字，並收到要在應用程式中顯示的分數︰
```
'AzureMachineLearning-TextAnalytics'.Sentiment({documents:Table({language:"en",id:"1",text:TextInput.Text})}).documents.score)
```
- 我們需要在應用程式中進行一些工作才能處理送回的資料，但這不會太複雜。