Einen benutzerdefinierten Connector von Grund auf neu erstellen

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 Konnektor von Grund auf, ohne eine Postman-Sammlung oder eine OpenAPI-Definition zu verwenden, um die Cognitive Services Text Analytics Sentiment API zu beschreiben (unser Beispiel für diese Serie). Stattdessen beschreiben Sie den Konnektor vollständig im Assistenten für benutzerdefinierte Konnektoren.

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

Hinweis

Derzeit können Sie einen benutzerdefinierten Konnektor von Grund auf neu erstellen (in Power Automate und Power Apps). Für Logic Apps müssen Sie mit mindestens einer grundlegenden OpenAPI-Definition oder Postman-Sammlung beginnen.

Voraussetzungen

Starten Sie den Assistenten für benutzerdefinierte Konnektoren

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

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

    Benutzerdefinierte Connectors auswählen

  3. Wählen Sie Neuer benutzerdefinierter Connector und dann Ohne Vorlage erstellen aus.

    Ohne Vorlage neu erstellen

  4. Geben Sie einen Namen für den benutzerdefinierten Connector ein, und wählen Sie dann Weiter aus.

    Namen des benutzerdefinierten Connectors eingeben

    Parameter Wert
    Titel des benutzerdefinierten Connectors „SentimentDemo“

Schritt 1: Allgemeine Angaben aktualisieren

Von diesem Punkt an zeigen wir die Benutzeroberfläche Power Automate, aber die Schritte sind bei allen Technologien weitgehend gleich. Wir werden auf eventuelle Unterschiede hinweisen.

  1. Auf der Seite Allgemein:

    • Geben Sie einen sinnvollen Wert für Beschreibung ein. Diese Beschreibung wird in den Details des benutzerdefinierten Konnektors angezeigt, und sie kann anderen helfen zu wissen, ob der Konnektor für sie nützlich sein könnte.

    • Aktualisieren Sie Host auf die Adresse für die Text Analytics API. Der Konnektor verwendet den API-Host und die Basis-URL, um zu bestimmen, wie die API aufgerufen werden soll.

    Benutzerdefinierter Konnektor - Allgemeine Seite

    Parameter Wert
    Beschreibung "Verwendet das Cognitive Services Text Analytics Sentiment API, um festzustellen, ob Text positiv oder negativ ist"
    Host "westus.api.kognitiv.microsoft.com"

    Hinweis

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

Schritt 2: Authentifizierungstyp festlegen

In benutzerdefinierten Konnektoren stehen verschiedene Optionen für die Authentifizierung zur Verfügung. Die APIs für kognitive Dienste verwenden die API-Schlüssel-Authentifizierung, sodass Sie dies für dieses Tutorial festlegen.

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

    Authentifizierungstyp

  2. Geben Sie unter API-Schlüssel eine Beschreibung, einen Namen und einen Ort für den Parameter an. Geben Sie eine aussagekräftige Beschreibung an. Diese wird angezeigt, wenn ein Benutzer zum ersten Mal eine Verbindung mit dem benutzerdefinierten Konnektor herstellt. Der Parametername und der Speicherort müssen mit dem übereinstimmen, was die API erwartet. 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.

Schritt 3: Konnektor-Definition erstellen

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.

Erstellen von Aktionen

Als erstes müssen Sie eine Aktion erstellen, die die Text Analytics Sentiment API aufruft.

  1. Auf der Seite Definition zeigt der linke Bereich alle Aktionen, Trigger (für Logic Apps und Power Automate) und Referenzen an, die für den Konnektor definiert sind. Wählen Sie Neue Aktion.

    Definitionsseite - Aktionen und Auslöser

    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. Fügen Sie eine Zusammenfassung, Beschreibung und Operations-ID für diese Aktion hinzu.

    Definitionsseite - Allgemein

    Parameter Wert
    Zusammenfassung "Gibt eine numerische Punktzahl zurück, die die erkannte Stimmung repräsentiert"
    Beschreibung "Die API gibt eine numerische Punktzahl zwischen 0 und 1 zurück. Werte nahe 1 deuten auf eine positive Stimmung hin, während Werte nahe 0 eine negative Stimmung anzeigen"
    Betriebs-ID „DetectSentiment“

    Lassen Sie die Eigenschaft Sichtbarkeit auf keine gesetzt. Diese Eigenschaft für Operationen und Parameter in einer logischen Anwendung oder einem logischen Ablauf hat die folgenden Optionen:

    • 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
  3. Der Bereich Anforderung zeigt Informationen an, die auf der HTTP-Anforderung für die Aktion basieren. Wählen Sie Importieren aus Beispiel.

    Definitionsseite – „Importieren aus Beispiel“ im Anforderungsbereich

  4. Geben Sie die für die Verbindung mit der API erforderlichen Informationen und den Anfragetext an und wählen Sie dann Importieren. Wir stellen diese Informationen für Sie bereit (unter dem Bild). Für eine öffentliche API erhalten Sie diese normalerweise aus der Dokumentation, wie z.B. Text Analytics Sentiment API.

    Definitionsseite - Import aus Muster

    Parameter Wert
    Verb „BUCHEN“
    URL https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment
    Textkörper Siehe unten
    {
      "documents": [
        {
          "language": "string",
          "id": "string",
          "text": "string"
        }
      ]
    }
    
  5. Der Bereich Antwort zeigt Informationen an, die auf der HTTP-Antwort für die Aktion basieren. Wählen Sie Standardantwort hinzufügen.

    Definitionsseite – „Standardantwort hinzufügen“

  6. Geben Sie den Antwort-Body an und wählen Sie dann Importieren. Wie bei der Anfrage stellen wir diese Informationen für Sie bereit, aber normalerweise finden Sie sie in der API-Dokumentation.

    Definitionsseite - Antwort

    {
     "documents": [
       {
         "score": 0.0,
         "id": "string"
       }
     ],
     "errors": [
       {
         "id": "string",
         "message": "string"
       }
     ]
    }
    
  7. Der Bereich Validierung zeigt alle Probleme an, die in der API-Definition erkannt werden. Überprüfen Sie den Status und wählen Sie dann oben rechts im Assistenten Konnektor aktualisieren.

    Definitionsseite - Validierung

Definition aktualisieren

Wir ändern nun einige Angaben, sodass der Konnektor in einer Logik-App, einem Flow oder einer App einfacher zu verwenden ist.

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

    Anforderungs-Body 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.

    Anforderungs-Body-ID bearbeiten

  3. 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“
  4. Wählen Sie im Bereich Parameter die Option Sprache und dann Bearbeiten, und wiederholen Sie den für id verwendeten Prozess mit den folgenden Werten.

    Parameter Wert
    Titel „Sprache“
    Beschreibung "Der 2- oder 4-stellige Sprachcode für den Text"
    Standardwert „de“
    Ist erforderlich „Ja“
  5. Im Bereich Parameter wählen Sie Text dann Bearbeiten, und wiederholen Sie das Verfahren, das Sie für id und language verwendet haben, mit den folgenden Werten.

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

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

Schritt 4: Testen des Konnektors

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 einige Minuten dauern, bis der Konnektor bereit ist, sich mit der API zu verbinden.

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

    Neue Verbindung

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

    Verbindung herstellen

Hinweis

Fügen Sie für APIs, für die eine Bearer-Authentifizierung erforderlich ist, „Bearer“ und ein Leerzeichen vor dem API-Schlüssel hinzu.

  1. 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.

      Verbindung aktualisieren

    • Unter Power Apps gelangen Sie zur Liste der in der aktuellen Umgebung verfügbaren Verbindungen. Wählen Sie im Navigationsbereich Daten > Benutzerdefinierte Connectors aus. Wählen Sie den Konnektor, den Sie erstellt haben, und gehen Sie dann zurück zur Seite Test.

      Benutzerdefinierte Connectors auswählen

  2. 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.

    Test-Betrieb

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

    Reaktion des Konnektors

Nächste Schritte

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

Sie können auch einen Konnektor innerhalb Ihrer Organisation gemeinsam nutzen und/oder den Konnektor zertifizieren lassen, damit auch Personen außerhalb Ihrer Organisation ihn verwenden können: