Registrieren und Verwenden von benutzerdefinierten ConnectorsRegister and use custom connectors in PowerApps

Mithilfe von PowerApps können Sie Apps mit vollem Funktionsumfang ohne herkömmlichen Anwendungscode erstellen.PowerApps enables you to build full-featured apps with no traditional application code. In einigen Fällen müssen Sie die Möglichkeiten von PowerApps jedoch erweitern, und dafür bieten sich Webdienste in idealer Weise an.But in some cases you need to extend PowerApps capabilites, and web services are a natual fit for this. Ihre App kann eine Verbindung mit einem Dienst herstellen, Operationen ausführen und Daten zurück erhalten.Your app can connect to a service, perform operations, and get data back. Wenn Sie über einen Webdienst verfügen, den Sie mit PowerApps verbinden möchten, registrieren Sie den Dienst als benutzerdefinierten Connector.When you have a web service you want to connect to with PowerApps, you register the service as a custom connector. Dieser Vorgang ermöglicht es PowerApps, die Charakteristika Ihrer Web-API zu verstehen, einschließlich der erforderlichen Registrierung, der unterstützten Operationen und der Parameter und Ausgaben für jede dieser Operationen.This process enables PowerApps to understand the characteristics of your web API, including the authentication that it requires, the operations that it supports, and the parameters and outputs for each of those operations.

In diesem Thema gehen wir auf die für die Registrierung und Verwendung eines benutzerdefinierten Connectors erforderlichen Schritte ein und verwenden die Textanalyse-API aus den Azure Cognitive Services als Beispiel.In this topic, we'll look at the steps required to register and use a custom connector, and we'll use the Azure Cognitive Services Text Analytics API as an example. Diese API bestimmt die Sprache, die Stimmung und wichtige Aussagen in den Texten, die Sie ihr übergeben.This API identifies the language, sentiment, and key phrases in text that you pass to it. Das folgende Bild zeigt die Interaktion zwischen dem Dienst, dem benutzerdefinierten Connector, den wir daraus erstellen, und der App, die die API aufruft.The following image shows the interaction between the service, the custom connector we create from it, and the app that calls the API.

API, benutzerdefinierter Connector und App

VoraussetzungenPrerequisites

  • Ein PowerApps-Konto.A PowerApps account.
  • Eine OpenAPI-Datei im JSON-Format, eine URL, die auf eine OpenAPI-Definition verweist, oder eine Postman-Sammlung für Ihre API.An OpenAPI file in JSON format, a URL to an OpenAPI definition, or a Postman Collection for your API. Wenn Sie über keins dieser Elemente verfügen, geben wir Ihnen Hilfestellung.If you don't have any of these, we'll provide guidance for you.
  • Ein Bild, das Sie als Symbol für Ihren benutzerdefinierten Connector verwenden können (optional).An image to use as an icon for your custom connector (optional).

Schritte im Erstellungsprozess für den benutzerdefinierten ConnectorSteps in the custom connector process

Die Erstellung des benutzerdefinierten Connectors erfolgt in mehreren Schritten, die wir unten kurz beschreiben.The custom connector process has several steps, which we describe briefly below. Dieser Artikel geht von der Annahme aus, dass Sie bereits über eine RESTful-API mit einer Form von authentifiziertem Zugriff verfügen, daher legen wir den Schwerpunkt im restlichen Artikel auf die Schritte 3–6.This article assumes you already have a RESTful API with some type of authenticated access, so we'll focus on steps 3-6 in the rest of the article. Ein Beispiel für die Schritte 1 und 2 finden Sie unter Erstellen einer benutzerdefinierten Web-API für PowerApps.For an example of steps 1 and 2, see Create a custom Web API for PowerApps.

  1. Zunächst müssen Sie in der gewünschten Sprache und für die gewünschte Plattform eine RESTful-API erstellen.Build a RESTful API in the language and platform of your choice. Für Microsoft-Technologien empfehlen wir eine der folgenden.For Microsoft technologies, we recommend one of the following.

    • Azure FunctionsAzure Functions
    • Azure-Web-AppsAzure Web Apps
    • Azure API-AppsAzure API Apps
  2. Mithilfe eines der folgenden Authentifizierungsmechanismen können Sie Ihre API schützen.Secure your API using one of the following authentication mechanisms. Sie können den unauthentifizierten Zugriff auf die API zulassen, es wird von uns aber nicht empfohlen.You can allow unauthenticated access to your APIs, but we don't recommend it.

  3. Damit PowerApps Verbindungen damit herstellen kann, müssen Sie auf eine von zwei branchenüblichen Weisen Ihre API beschreiben.Describe your API in one of two industry-standard ways, so that PowerApps can connect to it.

    • Eine OpenAPI-Datei (auch als Swagger-Datei bezeichnet)An OpenAPI file (also known as a Swagger file)
    • Eine Postman-SammlungA Postman Collection

      Sie können eine OpenAPI-Datei auch in Schritt 4 als Teil des Registrierungsvorgangs erstellen.You can also build an OpenAPI file in step 4 as part of the registration process.

  4. Sie müssen Ihren benutzerdefinierten Connector registrieren und verwenden dazu einen Assistenten in PowerApps, wo Sie eine Beschreibung der API, Sicherheitsdetails und weitere Informationen angeben.Register your custom connector using a wizard in PowerApps, where you specify an API description, security details, and other information.
  5. Verwenden Sie Ihren benutzerdefinierten Connector in einer App.Use your custom connector in an app. Erstellen Sie in der App eine Verbindung mit der API, und rufen Sie die von der API bereitgestellten Operationen auf, ganz so, wie Sie native Funktionen in PowerApps aufrufen.Create a connection to the API in your app, and call any operations that the API provides, just like you call native functions in PowerApps.
  6. Sie können Ihren benutzerdefinierten Connector freigeben, wie Sie andere Datenverbindungen in PowerApps freigeben.Share your custom connector like you do other data connections in PowerApps. Dieser Schritt ist optional, es ist aber häufig sinnvoll, benutzerdefinierte Connectors für mehrere App-Ersteller freizugeben.This step is optional, but it often makes sense to share custom connectors across multiple app creators.

Beschreiben Ihrer APIDescribe your API

Angenommen, Sie verfügen über eine API mit einer Form von authentifiziertem Zugriff, so benötigen Sie eine Möglichkeit, die API so zu beschreiben, dass PowerApps Verbindungen mit ihr herstellen können.Assuming you have an API with some type of authenticated access, you need a way to describe the API so that PowerApps can connect to it. Zu diesem Zweck erstellen Sie eine OpenAPI-Datei oder eine Postman-Sammlung – das können Sie von jedem REST-API-Endpunkt aus vornehmen, darunter:To do this, you create an OpenAPI file or a Postman Collection – which you can do from any REST API endpoint, including:

  • Öffentlich verfügbare APIs.Publicly available APIs. Beispiele hierfür sind Spotify, Uber, Slack, Rackspace usw.Some examples include Spotify, Uber, Slack, Rackspace, and more.
  • Eine API, die Sie erstellen und für einen beliebigen Cloudhostinganbieter bereitstellen, z.B. Azure, Amazon Web Services (AWS), Heroku, Google Cloud usw.An API that you create and deploy to any cloud hosting provider, including Azure, Amazon Web Services (AWS), Heroku, Google Cloud, and more.
  • Eine benutzerdefinierte Branchen-API, die in Ihrem Netzwerk bereitgestellt wird, solange die API im öffentlichen Internet verfügbar gemacht wird.A custom line-of-business API deployed on your network as long as the API is exposed on the public internet.

OpenAPI-Dateien und Postman-Sammlungen verwenden verschiedene Formate, sind jedoch beide sprachunabhängig maschinenlesbare Dokumente, in denen die Operationen und Parameter Ihrer API beschrieben werden:OpenAPI files and Postman Collections use different formats, but both are language-agnostic machine-readable documents that describe your API's operations and parameters:

  • Sie können diese Dokumente mithilfe einer Vielzahl von Tools erstellen, abhängig von der Sprache und Plattform, die zur Erstellung Ihrer API verwendet wurden.You can generate these documents using a variety of tools depending on the language and platform that your API is built on. Ein Beispiel für eine OpenAPI-Datei finden Sie in der Dokumentation zur Textanalyse-API.See the Text Analytics API documentation for an example of an OpenAPI file.
  • Wenn Sie noch nicht über eine OpenAPI-Datei für Ihre API verfügen und auch keine erstellen möchten, können Sie mithilfe einer Postman-Sammlung trotzdem auf einfache Weise einen benutzerdefinierten Connector erstellen.If you don't already have an OpenAPI file for your API and don't want to create one, you can still easily create a custom connector by using a Postman Collection. Weitere Informationen finden Sie unter Erstellen einer Postman-Sammlung.See Create a Postman Collection for more information.
  • PowerApps verwendet letztlich hinter den Kulissen OpenAPI, daher wird eine Postman-Sammlung analysiert und in eine OpenAPI-Definitionsdatei übersetzt.PowerApps ultimately uses OpenAPI behind the scenes, so a Postman Collection is parsed and translated into an OpenAPI definition file.

Hinweis: Die Dateigröße muss weniger als 1 MB betragen.Note: Your file size must be less than 1MB.

Erste Schritte mit OpenAPI und PostmanGetting started with OpenAPI and Postman

Registrieren des benutzerdefinierten ConnectorsRegister your custom connector

Jetzt verwenden Sie die OpenAPI-Datei oder die Postman-Sammlung, um Ihren benutzerdefinierten Connector in PowerApps zu registrieren.You will now use the OpenAPI file or Postman Collection to register your custom connector in PowerApps.

  1. Wählen Sie in powerapps.com im linken Menü Verbindungen aus.In powerapps.com, in the left menu, select Connections. Wählen Sie die Auslassungspunkte (...) und dann in der oberen rechten Ecke Benutzerdefinierte Connectors verwalten aus.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Tipp: Wenn Sie die Option zum Verwalten benutzerdefinierter Connectors in einem mobilen Browser nicht finden können, befindet sie sich möglicherweise unter einem Menü in der oberen linken Ecke.Tip: If you can't find where to manage custom connectors in a mobile browser, it might be under a menu in the upper left corner.

    Erstellen des benutzerdefinierten Connectors

  2. Wählen Sie Benutzerdefinierten Connector erstellen aus.Select Create custom connector.

    Eigenschaften für benutzerdefinierte Connectors

  3. Wählen Sie auf der Registerkarte Allgemein aus, wie Sie den benutzerdefinierten Connector erstellen möchten.In the General tab, choose how you want to create the custom connector.

    • Hochladen einer OpenAPI-DateiUpload an OpenAPI file
    • Verwenden einer OpenAPI-URLUse an OpenAPI URL
    • Hochladen von Postman Collection V1Upload Postman Collection V1

      So erstellen Sie einen benutzerdefinierten Connector

      Laden Sie ein Symbol für den benutzerdefinierten Connector hoch.Upload an icon for your custom connector. Die Felder „Beschreibung“, „Host“ und „Basis-URL“ werden normalerweise automatisch aus den Informationen aus der OpenAPI-Datei aufgefüllt.Description, Host, and Base URL fields are typically auto-populated with the information from the OpenAPI file. Wenn sie nicht automatisch aufgefüllt werden, können Sie diesen Feldern Informationen hinzufügen.If they are not auto-populated, you can add information to those fields. Wählen Sie Weiter aus.Select Continue.

  4. Geben Sie auf der Registerkarte Sicherheit alle Authentifizierungseigenschaften ein.In the Security tab, enter any authentication properties.

    Authentifizierungstypen

    • Der Authentifizierungstyp wird automatisch auf der Grundlage der Definition in Ihrem OpenAPI-Objekt securityDefinitions aufgefüllt.The authentication type is auto-populated based on what is defined in your OpenAPI securityDefinitions object. Unten finden Sie ein OAuth2.0-Beispiel.Below is an OAuth2.0 example.

      "securityDefinitions": {
          "AAD": {
          "type": "oauth2",
          "flow": "accessCode",
          "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
          "scopes": {}
          }
      },
      
    • Wenn die OpenAPI-Datei das securityDefintions-Objekt nicht verwendet, werden keine weiteren Werte benötigt.If the OpenAPI file does not use the securityDefintions object, then no additional values are needed.
    • Wenn eine Postman-Sammlung verwendet wird, wird der Authentifizierungstyp nur bei unterstützten Authentifizierungstypen automatisch aufgefüllt, wie OAuth 2.0 oder Standardauthentifizierung.When using a Postman Collection, authentication type is auto-populated only when using supported authentication types, such as OAuth 2.0 or Basic.
    • Ein Beispiel zur Einrichtung von AAD-Authentifizierung (Azure Active Directory) finden Sie unter Erstellen einer benutzerdefinierten Web-API für PowerApps.For an example of setting up Azure Active Directory (AAD) authenthication, see Create a custom Web API for PowerApps.
  5. Auf der Registerkarte Definitionen werden alle in Ihre OpenAPI-Datei oder Postman-Sammlung definierten Operationen, zusammen mit den Anforderungs- und Antwortwerten, automatisch aufgefüllt.In the Definitions tab, all the operations defined in your OpenAPI file or Postman Collection, along with request and response values, are auto-populated. Wenn alle erforderlichen Operationen definiert sind, können Sie mit Schritt 6 im Registrierungsprozess fortfahren, ohne Änderungen auf diesem Bildschirm vorzunehmen.If all your required operations are defined, you can go to step 6 in the registration process without making changes on this screen.

    Registerkarte „Definition“

    Wenn Sie vorhandene Aktionen bearbeiten oder Ihrem benutzerdefinierten Connector neue Aktionen hinzufügen möchten, lesen Sie weiter.If you want to edit existing actions or add new actions to your custom connector, continue reading below.

    1. Wenn Sie eine neue Aktion hinzufügen möchten, die noch nicht in Ihrer OpenAPI-Datei oder Postman-Sammlung definiert wurde, wählen Sie im linken Bereich Neue Aktion aus, und setzen Sie im Abschnitt Allgemein den Namen, die Beschreibung und die Sichtbarkeit Ihrer Operation ein.If you want to add a new action that was not already in your OpenAPI file or Postman Collection, select New action in the left pane and fill in the General section with the name, description, and visibility of your operation.
    2. Wählen Sie im Abschnitt Anfordern oben rechts Aus Beispiel importieren aus.In the Request section, select Import from sample on the top right. Fügen Sie im Formular rechts eine Beispielanforderung ein.In the form on the right, paste in a sample request. Beispielanforderungen stehen normalerweise in der Dokumentation der API zur Verfügung, wo Sie Informationen zum Ausfüllen der Felder Aktionsart, Anforderungs-URL, Header und Textkörper abrufen können.Sample requests are usually available in the API documentation, where you can get information to fill out the Verb, Request URL, Headers, and Body fields. Ein Beispiel finden Sie in der Dokumentation zur Textanalyse-API.See the Text Analytics API documentation for an example.

      Importieren aus einem Beispiel

    3. Wählen Sie Importieren aus, um die Anforderungsdefinition abzuschließen.Select Import to complete the request definition. Definieren Sie die Antwort auf ähnliche Weise.Define the response in a similar way.
  6. Nachdem Sie alle Operationen definiert haben, wählen Sie Erstellen aus, um Ihren benutzerdefinierten Connector zu erstellen.Once you have all your operations defined, select Create to create your custom connector.
  7. Sobald Sie Ihren benutzerdefinierten Connector erstellt haben, wechseln Sie zur Registerkarte Test, um die in der API definierten Operationen zu testen.Once you have created your custom connector, go to the Test tab to test the operations defined in the API. Wählen Sie eine Verbindung aus, und geben Sie Eingabeparameter ein, um eine Operation zu testen.Choose a connection, and provide input parameters to test an operation.

    Testen des benutzerdefinierten Connectors

    Wenn der Aufruf erfolgreich ist, erhalten Sie eine gültige Antwort.If the call is successful, you get a valid response.

    Testen der API-Antwort

Verwenden des benutzerdefinierten ConnectorsUse your custom connector

Fügen Sie nach der erfolgten Registrierung Ihrer API den benutzerdefinierten Connector hinzu, ganz wie eine beliebige andere Datenquelle.Now that you've registered your API, add the custom connector to your app like you would any other data source. Wir stellen hier schrittweise ein kurzes Beispiel vor.We'll go through a brief example here. Weitere Informationen zu Datenverbindungen finden Sie unter Hinzufügen einer Datenverbindung in PowerApps.For more information about data connections, see Add a data connection in PowerApps.

  1. Klicken oder tippen Sie in PowerApps Studio im rechten Bereich auf Datenquelle hinzufügen.In PowerApps Studio, in the right pane, click or tap Add data source.

  2. Klicken oder tippen Sie auf den erstellten benutzerdefinierten Connector.Click or tap the custom connector that you created.

  3. Führen Sie alle für die Anmeldung beim gewünschten Dienst erforderlichen Schritte aus.Complete any steps necessary to sign in to the service you're connecting to. Wenn Ihre API OAuth-Authentifizierung verwendet, wird Ihnen möglicherweise ein Anmeldebildschirm angezeigt.If your API uses OAuth authentication, you might be presented a sign-in screen. Bei der API-Schlüssel-Authentifizierung werden Sie möglicherweise zur Eingabe eines Schlüsselwerts aufgefordert.For API key authentication, you might be prompted for a key value.
  4. Rufen Sie die API in Ihrer App auf.Call the API in your app. Für das Beispiel haben wir eine App erstellt, die Text an Cognitive Services übergibt und einen Stimmungswert zwischen 0 und 1 zurück erhält, der von der App als Prozentwert angezeigt wird.For our example, we created an app that submits text to Cognitive Services and gets back a sentiment score of 0 to 1, which the app shows as a percentage.

    • Wenn Sie bei diesem Connector mit der Eingabe von „Az“ in der Bearbeitungsleiste beginnen, werden die API und die von ihr verfügbar gemachten Operationen angezeigt.With this connector, if you start typing "Az" in the formula bar, you see the API and the operations that it makes available.

    • Der vollständige Aufruf sieht wie folgt aus, wobei wir Text aus dem TextInput-Steuerelement übergeben und einen Punktwert zum Anzeigen in der App zurück erhalten:The complete call looks like this, where we pass in text from the TextInput control and get back a score to display in the app:

      'AzureMachineLearning-TextAnalytics'.Sentiment({documents:Table({language:"en",id:"1",text:TextInput.Text})}).documents.score)
      
    • Wir führen weitere Arbeiten in der App aus, um die zurück erhaltenen Daten zu verarbeiten, das ist aber nicht allzu kompliziert.We do a little more work in the app to handle the data that comes back, but it's not too complicated.

Die fertig gestellte App sieht wie in der folgenden Abbildung dargestellt aus.The finished app looks like the following image. Es ist eine einfache App, sie erhält aber durch die Möglichkeit, Cognitive Services mithilfe eines benutzerdefinierten Connectors aufzurufen, leistungsstarke Funktionen.It's a simple app, but it gains powerful functionality by being able to call Cognitive Services through a custom connector.

Kontingent und DrosselungQuota and throttling

  • Details zu Kontingenten für die Erstellung von benutzerdefinierten Connectors finden Sie auf der Seite PowerApps – Preise.See the PowerApps Pricing page for details about custom connector creation quotas. Benutzerdefinierte Connectors, die für Sie freigegeben wurden, werden nicht auf dieses Kontingent angerechnet.Custom connectors that are shared with you don't count against this quota.
  • Für jede Verbindung, die auf einem benutzerdefinierten Connector erstellt wird, können Benutzer bis zu 500 Anforderungen pro Minute vornehmen.For each connection created on a custom connector, users can make up to 500 requests per minute.

Freigeben Ihres benutzerdefinierten ConnectorsShare your custom connector

Da Sie jetzt über einen benutzerdefinierten Connector verfügen, können Sie ihn für andere Benutzer in Ihrer Organisation freigeben.Now that you have a custom connector, you can share it with other users in your organization. Beachten Sie beim Freigeben von APIs, dass andere Benutzer in Abhängigkeit von diesen geraten können und das Löschen eines benutzerdefinierten Connectors alle Verbindungen mit der API entfernt.Keep in mind that when you share an API, others might start to depend on it, and deleting a custom connector deletes all the connections to the API. Informationen zum Bereitstellen von Connectors für Benutzer außerhalb Ihrer Organisation finden Sie unter Übersicht zum Zertifizieren von benutzerdefinierten Connectors in PowerApps (Overview of certifying custom connectors in PowerApps).If you want to provide a connector for users outside your organization, see Overview of certifying custom connectors in PowerApps.

  1. Wählen Sie in powerapps.com im linken Menü Verbindungen aus.In powerapps.com, in the left menu, select Connections. Wählen Sie die Auslassungspunkte (...) und dann in der oberen rechten Ecke Benutzerdefinierte Connectors verwalten aus.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Neue Verbindung

  2. Wählen Sie die Schaltfläche mit den Auslassungspunkten (. . .) für Ihren Connector aus, und wählen Sie dann Eigenschaften anzeigen aus.Select the ellipsis (. . .) button for your connector, then select View properties.

    Anzeigen von Connectoreigenschaften

  3. Wählen Sie Ihre API aus, wählen Sie die Option Freigeben, und geben Sie dann die Benutzer oder Gruppen ein, denen Sie Zugriff auf Ihre API gewähren möchten.Select your API, select Share, and then enter the users or groups to whom you want to grant access to your API.

    Freigeben des benutzerdefinierten Connectors

  4. Wählen Sie Speichern.Select Save.

Nächste SchritteNext steps

Informationen zum Erstellen einer Postman-SammlungLearn how to create a Postman Collection

Use an ASP.NET Web API (Verwenden einer ASP.NET-Web-API)Use an ASP.NET Web API.

Register an Azure Resource Manager API (Registrieren einer Azure Resource Manager-API)Register an Azure Resource Manager API.