Einen benutzerdefinierten Connector auf der Grundlage einer OpenAPI-Definition erstellen

  • Artikel

Hinweis

Dieses Thema ist Teil einer Übungsreihe zur Erstellung und Verwendung von benutzerdefinierten Konnektoren in Azure Logic Apps, Microsoft Power Automate und Microsoft Power Apps. Stellen Sie sicher, dass Sie die Übersicht über kundenspezifische Konnektoren lesen, um den Prozess zu verstehen.

Um einen benutzerdefinierten Konnektor zu erstellen, müssen Sie die API beschreiben, mit der Sie eine Verbindung herstellen möchten, damit der Konnektor die Operationen und Datenstrukturen der API versteht. In diesem Thema erstellen Sie einen benutzerdefinierten Connector unter Verwendung einer OpenAPI-Definition, der die Stimmungs-API für die Cognitive Services-Textanalyse beschreibt (unser Beispiel für diese Serie).

Eine andere Möglichkeit zum Beschreiben einer API finden Sie unter Erstellen eines neuen benutzerdefinierten Connectors.

Anforderungen

  • Eine OpenAPI-Definition, die die Beispiel-API beschreibt. Beim Erstellen eines benutzerdefinierten Connectors muss die OpenAPI-Definition kleiner als 1 MB sein. Die OpenAPI-Definition muss das OpenAPI 2.0-Format haben (früher als Swagger bekannt).

    Wenn mehrere Sicherheitsdefinitionen vorhanden sind, wählt der benutzerdefinierte Connector die oberste Sicherheitsdefinition aus. Die benutzerdefinierte Connector-Erstellung unterstützt keine Client-Anmeldeinformationen (z. B. Anwendung und Kennwort) in der OAuth-Sicherheitsdefinition.

  • Ein API-Schlüssel für die Cognitive Services-API zur Textanalyse.

  • Eines der folgenden Abonnements:

  • Wenn Sie Logic Apps verwenden, erstellen Sie zunächst einen benutzerdefinierten Konnektor von Azure Logic Apps.

OpenAPI-Definition importieren

Sie können jetzt mit der OpenAPI-Definition arbeiten, die Sie heruntergeladen haben. Alle erforderlichen Informationen sind in der Definition enthalten, und Sie können diese Informationen überprüfen und aktualisieren, während Sie den Assistenten für benutzerdefinierte Konnektoren durchlaufen.

Beginnen Sie mit dem Importieren der OpenAPI-Definition für Logic Apps oder für Power Automate und Power Apps.

Hinweis

Eine OpenAPI-Definition muss das OpenAPI 2.0-Format haben (früher als Swagger bekannt). OpenAPI-Definitionen, die das OpenAPI 3.0-Format haben, werden nicht unterstützt.

OpenAPI-Definition für Logic Apps importieren

  1. Gehen Sie zum Azure-Portal und öffnen Sie den Logik-Apps-Connector, den Sie zuvor unter Erstellen eines benutzerdefinierten Azure Logic Apps-Connectors erstellt haben.

  2. Wählen Sie im Menü Ihres Connectors Logik-Apps-Connector und dann Bearbeiten aus.

    Logik-Apps-Connector bearbeiten.

  3. Wählen Sie unter Allgemein OpenAPI-Datei hochladen aus und gehen Sie dann zur OpenAPI-Definition, die Sie erstellt haben.

    OpenAPI-Datei hochladen.

Hinweis

Dieses Lernprogramm konzentriert sich auf eine REST-API, aber Sie können auch eine SOAP-API mit Logik-Apps verwenden.

OpenAPI-Definition für Power Automate und Power Apps importieren

  1. Melden Sie sich bei Power Apps oder Power Automate an.

  2. Wählen Sie im linken Bereich Daten > Benutzerdefinierte Connectors aus.

    Benutzerdefinierten Connector auswählen.

  3. Wählen Sie Neuer benutzerdefinierter Connector und dann OpenAPI-Datei importieren aus.

    Eine OpenAPI-Datei importieren.

  4. Geben Sie einen Namen für den benutzerdefinierten Connector ein, gehen Sie zu der von Ihnen heruntergeladenen oder erstellten OpenAPI-Definition und wählen Sie dann Fortsetzen aus.

    Laden Sie eine Sammlung hoch.

    Parameter Wert
    Titel des benutzerdefinierten Connectors SentimentDemo

Allgemeine Einzelheiten überprüfen

Von diesem Punkt an zeigen wir die Benutzeroberfläche Power Automate, aber die Schritte sind bei allen drei Technologien weitgehend gleich. Wir werden auf eventuelle Unterschiede hinweisen. In diesem Teil des Thema werden wir hauptsächlich die Benutzeroberfläche überprüfen und Ihnen zeigen, wie die Werte den Abschnitten der OpenAPI-Datei entsprechen.

  1. Stellen Sie oben im Assistenten sicher, dass als Name SentimentDemo festgelegt ist und wählen Sie dann Connector erstellen aus.

  2. Überprüfen Sie auf der Seite Allgemein die Informationen, die aus der OpenAPI-Definition importiert wurden, einschließlich API-Host und Basis-URL für die API. Der Connector verwendet den API-Host und die Basis-URL, um zu bestimmen, wie die API aufgerufen werden soll.

    Benutzerdefinierter Connector – Seite „Allgemein“.

    Hinweis

    Weitere Informationen über die Verbindung zu lokalen APIs finden Sie unter Verbindung zu lokalen APIs über das Daten-Gateway.

    Der folgende Abschnitt der OpenAPI-Definition enthält Informationen für diese Seite der Benutzeroberfläche:

      "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"
  ]

Authentifizierungstyp überprüfen

In benutzerdefinierten Konnektoren stehen verschiedene Optionen für die Authentifizierung zur Verfügung. Die Cognitive Services-APIs verwenden die API-Schlüsselauthentifizierung, das ist also in der OpenAPI-Definition angegeben.

Überprüfen Sie auf der Seite Sicherheit die Authentifizierungsinformationen für den API-Schlüssel.

API-Schlüsselparameter.

Die Beschriftung wird angezeigt, wenn jemand zum ersten Mal eine Verbindung mit dem benutzerdefinierten Connector herstellt. Sie können Bearbeiten wählen und diesen Wert ändern. Der Parametername und der Speicherort müssen mit dem übereinstimmen, was die API erwartet, in diesem Fall Ocp-Apim-Subscription-Key und Header.

Der folgende Abschnitt der OpenAPI-Definition enthält Informationen für diese Seite der Benutzeroberfläche:

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

Überprüfen Sie die Definition des Konnektors

Die Seite Definition im Assistenten für benutzerdefinierte Connector bietet zahlreiche Optionen, um zu definieren, wie Ihr Connector funktioniert und wie er in Logik-Apps, Flows und Apps sichtbar gemacht wird. In diesem Abschnitt erläutern wir die UI und behandeln einige Optionen, aber wir ermutigen Sie auch dazu, selbst nachzuforschen. Informationen zur Neudefinition von Objekten in dieser UI finden Sie unter Connector-Definition erstellen.

  1. Im folgenden Bereich werden alle Aktionen, Trigger (für Logik-Apps und Power Automate) und Verweise angezeigt, die für den Connector definiert sind. In diesem Fall wird die Aktion DetectSentiment aus der OpenAPI-Definition angezeigt. Dieser Connector enthält keine Trigger. Sie finden Informationen zu Triggern für benutzerdefinierte Connectors unter Verwenden eines Webhooks als Trigger für Azure Logic Apps und Power Automate.

    Definitionsseite – Aktionen und Trigger.

  2. Der Bereich Allgemein enthält Informationen zur derzeit ausgewählten Aktion bzw. zum derzeit ausgewählten Trigger. Sie können die hier angezeigten Informationen bearbeiten, u. a. die Eigenschaft für die Visibility von Vorgängen und Parametern in einer Logik-App oder einem Flow:

    • kein Wert: wird normalerweise in der logischen Anwendung oder im logischen Ablauf angezeigt

    • Erweitert: versteckt unter einem zusätzlichen Menü

    • intern: für den Benutzer verborgen

    • Wichtig: wird dem Benutzer immer zuerst angezeigt

      Definitionsseite – Allgemein.

  3. Im Bereich Anforderung werden Informationen basierend auf der in der OpenAPI-Definition enthaltenen HTTP-Anforderung angezeigt. In diesem Fall sehen Sie, dass das HTTP-Verb POST ist und die URL /text/analytics/v2.0/sentiment lautet (die vollständige URL zur API ist <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Wir werden uns den Parameter Textkörper in Kürze näher ansehen.

    Definitionsseite – Anforderung.

    Der folgende Abschnitt der OpenAPI-Definition enthält Informationen für die Bereiche Allgemein und Anforderung der Benutzeroberfläche:

    "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. Im Bereich Antwort werden Informationen basierend auf der in der OpenAPI-Definition enthaltenen HTTP-Antwort angezeigt. In diesem Fall ist nur eine Antwort für 200 (erfolgreiche Antwort) angegeben. Sie können jedoch zusätzliche Antworten festlegen.

    Definitionsseite – Antwort.

    Der folgende Abschnitt der OpenAPI-Definition enthält einige Informationen im Bezug auf die Antwort:

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

    Dieser Abschnitt zeigt die beiden Werte, die vom Connector zurückgegeben werden: id und score. Er enthält ihre Datentypen und das Feld x-ms-summary, das ist eine OpenAPI-Erweiterung. Weitere Informationen zu dieser und anderen Erweiterungen finden Sie unter Eine OpenAPI-Definition für einen benutzerdefinierten Connector erweitern.

  5. Der Bereich Prüfung zeigt alle Probleme an, die in der API-Definition erkannt werden. Überprüfen Sie die Informationen in diesem Bereich, bevor Sie einen Connector speichern.

    Definitionsseite – Prüfung.

Aktualisieren Sie die Definition

Die heruntergeladene OpenAPI-Definition ist zwar ein gutes allgemeines Beispiel, Sie verwenden jedoch vielleicht Definitionen, die umfassend aktualisiert werden müssen, damit der Connector in einer Logik-App, einem Flow oder einer App einfacher zu verwenden ist. Wir werden Ihnen zeigen, wie Sie eine Änderung an der Definition vornehmen können.

  1. Wählen Sie im Bereich Anforderung die Option Text und dann Bearbeiten aus.

    Anforderungstext bearbeiten.

  2. Im Bereich Parameter sehen Sie nun die drei Parameter, die die API erwartet: ID, Language und Text. Wählen Sie ID und dann Bearbeiten.

    Anforderungstext-ID bearbeiten.

  3. Im Bereich Schema-Eigenschaft aktualisieren Sie die Beschreibung des Parameters und wählen dann Zurück.

    Schema-Eigenschaft bearbeiten.

    Parameter Wert
    Beschreibung Eine numerische Kennung für jedes von Ihnen eingereichte Dokument

  4. Wählen Sie im Bereich Parameter die Option Zurück aus, um zurück zur Hauptseite der Definition zu wechseln.

  5. Wählen Sie oben rechts im Assistenten Connector aktualisieren aus.

Aktualisierte OpenAPI-Datei herunterladen

Derzeit können Sie einen benutzerdefinierten Connector aus einer OpenAPI-Datei oder von Grund auf neu erstellen (in Power Automate und Power Apps). Unabhängig davon, wie Sie den Connector erstellen, können Sie die vom Dienst intern verwendete OpenAPI-Definition herunterladen.

  • Laden Sie die Definition in Logik-Apps über den benutzerdefinierten Connector herunter.

    OpenAPI-Definition für Logik-Apps herunterladen.

  • Unter Power Automate oder Power Apps können Sie aus der Liste der benutzerdefinierten Connectors herunterladen.

    OpenAPI Definition für Power Automate herunterladen.

Connector testen

Nun, da Sie den Connector erstellt haben, testen Sie ihn, um sicherzustellen, dass er ordnungsgemäß funktioniert. Tests sind derzeit nur in Power Automate und Power Apps verfügbar.

Wichtig

Wenn Sie einen API-Schlüssel verwenden, empfehlen wir, den Connector nicht unmittelbar nach seiner Erstellung zu testen. Es kann ein paar Minuten dauern, bis der Connector bereit ist, eine Verbindung zur API herzustellen.

  1. Wählen Sie auf der Seite Test die Option Neue Verbindung aus.

    Neue Verbindung

  2. Geben Sie den API-Schlüssel aus der Textanalyse-API ein und wählen Sie dann Verbindung erstellen aus.

    Erstellen Sie eine Verbindung.

  3. Gehen Sie zur Seite Test und führen Sie einen der folgenden Schritte aus:

    • Unter Power Automate gelangen Sie zurück zur Seite Test. Wählen Sie das Aktualisierungssymbol, um sicherzustellen, dass die Verbindungsinformationen aktualisiert werden.

      Verbindung aktualisieren.

    • Unter Power Apps gelangen Sie zu der Liste der in der aktuellen Umgebung verfügbaren Verbindungen. Wählen Sie in der rechten oberen Ecke erst das Zahnradsymbol und dann Benutzerdefinierte Connectors aus. Wählen Sie den Connector, den Sie erstellt haben, und gehen Sie dann zurück zur Seite Test.

      Zahnradsymbol im Dienst.

  4. Geben Sie auf der Seite Test einen Wert für das Feld Text ein (die anderen Felder enthalten die von Ihnen zuvor festgelegten Standardwerte), und wählen Sie Vorgang testen aus.

    Vorgang testen.

  5. Der Connector ruft die API auf, und Sie können die Antwort überprüfen, die die Stimmungsbewertung enthält.

    Connector-Antwort.

Nächste Schritte

Nun, da Sie einen benutzerdefinierten Connector erstellt und sein Verhalten definiert haben, können Sie den Connector verwenden.

Sie können auch einen Connector innerhalb Ihrer Organisation gemeinsam nutzen oder den Connector zertifizieren lassen, damit auch Personen außerhalb Ihrer Organisation ihn verwenden können.

Feedback senden

Wir freuen uns sehr über Feedback zu Problemen mit unserer Connector-Plattform oder neuen Feature-Ideen. Wenn Sie Feedback geben möchten, gehen Sie zu Probleme melden oder Hilfe zu Connectors und wählen Sie einen Feedbacktyp aus.