Einen benutzerdefinierten Connector auf der Grundlage einer Postman-Sammlung erstellen

Hinweis

Dieses Thema ist Teil einer Übungsreihe zur Erstellung und Verwendung von benutzerdefinierten Connectors in Azure Logic Apps, Power Automate und 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 Konnektor unter Verwendung einer Postman-Sammlung, der die Standpunkt-API für die Cognitive Services-Textanalyse beschreibt (unser Beispiel für diese Serie).

Weitere Möglichkeiten zur Beschreibung einer API finden Sie in den folgenden Themen:

Voraussetzungen

Postman-Sammlung importieren

Sie können nun die erstellte oder heruntergeladene Postman-Sammlung verwenden. Viele der erforderlichen Informationen sind in der Sammlung enthalten. Sie können diese Informationen auch beim Durchlaufen des Assistenten für benutzerdefinierte Connectors überprüfen und aktualisieren. Importieren Sie zunächst die Postman-Sammlung für Logic Apps oder für Power Automate und Power Apps.

Importieren der Postman-Sammlung für Logic Apps

  1. Gehen Sie zu Azure portal, und öffnen Sie den Konnektor Logic Apps, den Sie zuvor unter Einen benutzerdefinierten Konnektor für Azure Logic Apps erstellen erstellt haben.

  2. Wählen Sie im Menü Ihres Konnektors Logic Apps Konnektor und dann Bearbeiten.

    Logic Apps-Konnektor bearbeiten

  3. Wählen Sie unter Allgemein Postmann-Sammlung V1 hochladen, und navigieren Sie dann zu der von Ihnen erstellten Postmann-Sammlung.

    Screenshot, der die Option zum Hochladen von Postman Collection V1 zeigt.

    Der Assistent importiert die Sammlung und konvertiert sie dann in eine OpenAPI-Definition mit dem Namen generatedApiDefinition.swagger.json.

Hinweis

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

Die Postman-Sammlung für Power Automate und Power Apps importieren

  1. Navigieren Sie zu make.powerapps.com oder flow.microsoft.com.

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

  3. Wählen Sie Neuer benutzerdefinierte Connector und dann Postman-Sammlung importieren aus.

  4. Geben Sie einen Namen für den benutzerdefinierten Konnektor ein, navigieren Sie dann zu der Postman-Collection, die Sie heruntergeladen oder erstellt haben, und wählen Sie Fortsetzen.

    Screenshot, der die Schritte zum Importieren der Sammlung zeigt.

    Parameter Wert
    Titel des benutzerdefinierten Connectors „SentimentDemo“

    Der Assistent importiert die Sammlung und konvertiert sie dann in eine OpenAPI-Definition mit dem Namen generatedApiDefinition.swagger.json.

Allgemeine Informationen aktualisieren

Ab diesem Punkt zeigen wir die UI von Power Automate, aber die Schritte sind bei allen drei Technologien weitgehend gleich. Alle Unterschiede werden hervorgehoben.

  1. Überprüfen Sie auf der Seite Allgemein die Informationen, die aus der Postman-Sammlung importiert wurden (einschließlich Host und Basis-URL für die API). Der Connector verwendet den Host und die Basis-URL, um zu bestimmen, wie die API aufgerufen wird.

    Hinweis

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

  2. Geben Sie eine aussagekräftige Beschreibung ein. Anhand dieser Beschreibung, die in den Details des benutzerdefinierten Connectors angezeigt wird, können andere Benutzer ermitteln, ob der Connector für sie von Nutzen ist.

    Parameter Wert
    Beschreibung "Verwendet das Cognitive Services Text Analytics Sentiment API, um festzustellen, ob Text positiv oder negativ ist"

Authentifizierungsart angeben

In benutzerdefinierten Konnektoren stehen verschiedene Optionen für die Authentifizierung zur Verfügung. Die Cognitive Services-APIs verwenden Authentifizierung mit API-Schlüssel.

  1. Wählen Sie auf der Seite Sicherheit unter Authentifizierungstyp die Option API-Schlüssel aus.

  2. Geben Sie unter API-Schlüssel eine Beschreibung, einen Namen und einen Ort für den Parameter an. Wählen Sie eine aussagekräftige Beschriftung aus. Dieser Text wird Benutzern angezeigt, um sie beim Herstellen der Verbindung mit Ihrem benutzerdefinierten Connector anzuleiten. Der Parametername und der Speicherort müssen mit dem übereinstimmen, was die API erwartet (in diesem Fall der Header, den Sie in Postman angegeben haben). Wählen Sie Verbinden aus.

    API-Schlüsselparameter

    Parameter Wert
    Parameterbezeichnung „API-Schlüssel“
    Parametername „Ocp-Apim-Subscription-Key“
    Ort des Parameters „Header“
  3. Vergewissern Sie sich am Anfang des Assistenten, dass der Name auf "SentimentDemo" gesetzt ist, und wählen Sie dann Konnektor erstellen.

Konnektordefinition überprüfen und aktualisieren

Der Assistent für benutzerdefinierte Konnektoren bietet Ihnen eine Vielzahl von Optionen, um zu definieren, wie Ihr Konnektor funktioniert und wie er in Logik-Apps, Flows und Applikationen dargestellt wird. In diesem Abschnitt erläutern wir die UI und behandeln einige Optionen, aber wir ermutigen Sie auch dazu, selbst nachzuforschen.

Benutzeroberfläche und Definition überprüfen

Bevor wir zu einigen spezifischen Schritten auf der Seite Definition kommen, werfen wir zunächst einen Blick auf die Benutzeroberfläche.

  1. Dieser Bereich enthält alle Aktionen, Trigger (für Logic Apps und Power Automate) und Verweise, die für den Connector definiert sind. In diesem Fall wird die Aktion DetectSentiment aus der Postman-Sammlung 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 Auslöser

  2. Der Bereich Allgemein enthält Informationen zur derzeit ausgewählten Aktion bzw. zum derzeit ausgewählten Trigger. Diese Informationen stammen aus der Postman-Sammlung. 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:

    • wichtig: wird dem Benutzer immer zuerst angezeigt
    • kein Wert: wird normalerweise in der logischen Anwendung oder im logischen Ablauf angezeigt
    • erweitert: zunächst in einem zusätzlichen Menü verborgen
    • intern: wird für den Benutzer nicht angezeigt
  3. Der Bereich Anforderung zeigt Informationen an, die auf der HTTP-Anforderung basieren, die in der Postman-Sammlung enthalten ist. 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.

  4. Der Bereich Antwort zeigt Informationen an, die auf der HTTP-Antwort basieren, die in der Postman-Sammlung enthalten ist. In diesem Fall ist nur eine Antwort für „200“ (erfolgreiche Antwort) angegeben. Sie können jedoch zusätzliche Antworten festlegen.

  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.

Aktualisieren Sie die Definition

Wir ändern nun einige Angaben, sodass der Connector in einer Logic App, in Power Automate oder Power Apps einfacher zu verwenden ist.

  1. Aktualisieren Sie die Zusammenfassung im Bereich Allgemein auf „Gibt einen numerischen Wert für die ermittelte Stimmung zurück“.

  2. Im Bereich Anforderung wählen Sie Body dann Bearbeiten.

  3. Im Bereich Parameter sehen Sie nun die drei Parameter, die die API erwartet: id, language und text. Wählen Sie ID und dann Bearbeiten.

  4. Aktualisieren Sie im Bereich Schemaeigenschaft Werte für den Parameter, und wählen Sie dann Zurück.

    Schema-Eigenschaft bearbeiten

    Parameter Wert
    Titel „ID“
    Beschreibung "Eine Kennung für jedes Dokument, das Sie einreichen"
    Standardwert „1“
    Ist erforderlich „Ja“
  5. Klicken Sie im Bereich Parameter auf Sprache und dann auf Bearbeiten, und wiederholen Sie den Vorgang, den Sie weiter oben angewendet haben, mit den folgenden Werten.

    Parameter Wert
    Titel „Sprache“
    Beschreibung "Der 2- oder 4-stellige Sprachcode für den Text"
    Standardwert „de“
    Ist erforderlich „Ja“
  6. Klicken Sie im Bereich Parameter auf Text und dann auf Bearbeiten, und wiederholen Sie den Vorgang, den Sie weiter oben angewendet haben, mit den folgenden Werten.

    Parameter Wert
    Titel "Text"
    Beschreibung "Der Text, der auf Stimmung zu analysieren ist"
    Standardwert keine
    Ist erforderlich „Ja“
  7. Wählen Sie im Bereich Parameter die Option Zurück aus, um zurück zur Hauptseite für die Definition zu wechseln.

  8. Wählen Sie oben rechts im Assistenten Konnektor aktualisieren.

Konnektor testen

Nun, da Sie den Konnektor 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 Konnektor 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.

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

  3. Zurück zur Seite Testseite:

    • In Power Automate werden Sie zur Seite Test zurückgeführt. Wählen Sie das Aktualisierungssymbol, um sicherzustellen, dass die Verbindungsinformationen aktualisiert werden.
    • Unter Power Apps gelangen Sie zur Liste der in der aktuellen Umgebung verfügbaren Verbindungen. Wählen Sie in der oberen rechten Ecke das Zahnradsymbol und wählen Sie dann Benutzerdefinierte Konnektoren. Wählen Sie den Konnektor, den Sie erstellt haben, und gehen Sie dann zurück zur Seite Test.
  4. Geben Sie auf der Seite Test einen Wert für das Feld Text ein (die anderen Felder verwenden die von Ihnen zuvor festgelegten Standardwerte), und wählen Sie dann Testbetrieb.

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

    Connector-Antwort

Einschränkungen

Wenn Sie in Power Automate und Power Apps einen vorhandenen benutzerdefinierten Connector mithilfe einer Postman-Sammlung aktualisieren, müssen Sie alle vorherigen Anpassungen erneut vornehmen, bevor Sie den Connector speichern. Beispielsweise müssen Sie den Authentifizierungstyp, die Standardwerte der Parameter für die Aktionen und anderes neu konfigurieren.

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 und/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.