Einen benutzerdefinierten Connector auf der Grundlage einer Postman-Sammlung erstellen

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:

• Einen benutzerdefinierten Connector auf der Grundlage einer OpenAPI-Definition erstellen

• Erstellen Sie einen benutzerdefinierten Konnektor von Grund auf neu

Voraussetzungen

• Eine Postman-Sammlung, die die Beispiel-API beschreibt:

  • Die von uns erstellte Postman-Sammlung herunterladen
    oder
  • Absolvieren Sie das Thema Eine Postman-Sammlung für einen benutzerdefinierten Connector erstellen. Beim Erstellen eines benutzerdefinierten Connectors darf die Postman-Sammlung nicht größer als 1 MB sein.

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

• Eines der folgenden Abonnements:

  • Azure, wenn Sie Logic Apps verwenden
  • Power Automate
  • Power Apps

• Wenn Sie Logic Apps verwenden, erstellen Sie zunächst einen benutzerdefinierten Azure Logic Apps-Connector.

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.

   

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

   

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

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.

   

   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.

   

   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.

   

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.

   

   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.

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.

   

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.

• Einen benutzerdefinierten Connector in einem Flow verwenden
• Benutzen Sie einen benutzerdefinierten Konnektor aus einer Anwendung
• Einen benutzerdefinierten Connector aus einer Logik-App 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.

• Ihren Konnektor mit anderen teilen
• Zertifizieren Sie Ihren Konnektor

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.