Einen benutzerdefinierten Connector von Grund auf neu erstellen

Zum Erstellen eines benutzerdefinierten Connectors müssen Sie die API definieren, mit der Sie eine Verbindung herstellen möchten, damit der Connector die Vorgänge und Datenstrukturen der API versteht. In diesem Artikel erstellen Sie einen benutzerdefinierten Connector von Grund auf neu, ohne ein OpenAPI-Definitionsformat zu verwenden, um den Text Analytics-API-Stimmungsvorgang von Azure Cognitive Services zu beschreiben (unser Beispiel für diese Reihe). Stattdessen definieren Sie den Connector vollständig im benutzerdefinierten Connector-Assistenten.

Eine andere Möglichkeit zum Beschreiben einer API finden Sie unter Erstellen eines benutzerdefinierten Connectors aus einer OpenAPI-Definition.

Anforderungen

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

• Eines der folgenden Abonnements:

  • Power Automate
  • Power Apps

Starten Sie den Assistenten für benutzerdefinierte Connectors

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

2. Wählen Sie im linken Bereich Lösungen aus.

3. Bearbeiten oder erstellen Sie eine nicht verwaltete Lösung für Ihren benutzerdefinierten Connector. Erfahren Sie, wie Sie eine Lösung erstellen.

4. Wählen Sie die Dropdownliste "Neuer benutzerdefinierter Connector " aus, und wählen Sie "Erstellen aus leer" aus.

5. Geben Sie den Connectornamen ein, z. B. SentimentDemo. Wählen Sie "Weiter" , um Ihren Connector-Assistenten zu öffnen, in dem Sie diese fünf Abschnitte in Power Automate abschließen:

   • Allgemein

   • Sicherheit

   • Definition

   • Code (optional)

   • Test

     

Schritt 1: Allgemeine Angaben aktualisieren

Im Abschnitt "Allgemein " geben Sie Connectorinformationen wie Symbol, Beschreibung, Schema, Host und Basis-URL an. Führen Sie die folgenden Schritte aus:

1. Wählen Sie Symbol "Connector hochladen" oder Hochladen im Symbolfeld aus, um ein PNG- oder JPG-Symbol Ihres Verbinders hochzuladen. Achten Sie darauf, dass es weniger als 1 MB ist. Sie können auch eine Hintergrundfarbe für Ihr Symbol festlegen.

2. Geben Sie in das Feld Beschreibung einen aussagekräftigen Wert ein. Diese Beschreibung erscheint in den Details des benutzerdefinierten Connectors und kann anderen helfen, zu entscheiden, ob der Connector ihnen helfen könnte.

3. Wählen Sie das URL-Schema, HTTPS oder HTTP, für Ihren Connector aus.

4. Aktualisieren Sie das Feld Host auf die Adresse für die Textanalyse-API. Der Connector verwendet den API-Host und die Basis-URL, um zu bestimmen, wie die API aufgerufen werden soll.

   Parameter	Wert
   Beschreibung	Verwendet die Stimmungs-API für die Cognitive Services-Textanalyse, um festzustellen, ob der Text positiv oder negativ ist
   Host	westus.api.cognitive.microsoft.com

5. Aktualisieren Sie die Basis-URL, den Ausgangspunkt für alle API-Aufrufe an einen bestimmten Dienst.

6. Wählen Sie unten "Sicherheit" aus, um zum nächsten Abschnitt zu wechseln.

Schritt 2: Authentifizierungstyp festlegen

In benutzerdefinierten Konnektoren stehen verschiedene Optionen für die Authentifizierung zur Verfügung. Die Cognitive Services-APIs verwenden eine API-Schlüsselauthentifizierung, die Sie also für dieses Tutorial angeben.

1. Wählen Sie im Abschnitt "Sicherheit " unter "Authentifizierungstyp " den API-Schlüssel aus der Dropdownliste aus.

2. Geben Sie unter API-Schlüssel eine Parameterbezeichnung, einen Namen und einen Speicherort an. Geben Sie eine aussagekräftige Bezeichnung an, da dies angezeigt wird, wenn jemand zuerst eine Verbindung mit dem benutzerdefinierten Verbinder erstellt. Der Parametername und der Speicherort müssen mit dem übereinstimmen, was die API erwartet.

   Parameter	Wert
   Parameterbezeichnung	API-Schlüssel
   Parametername	Ocp-Apim-Subscription-Key
   Parameterstandort	Header

3. Stellen Sie oben im Assistenten sicher, dass der Name auf SentimentDemo festgelegt ist, und wählen Sie dann Create connector aus.

4. Wählen Sie " Definition " unten aus, um zum nächsten Abschnitt zu wechseln.

Schritt 3: Connector-Definition erstellen

Der Assistent für benutzerdefinierte Verbinder bietet Ihnen viele Optionen, um zu beschreiben, wie Ihr Verbinder funktioniert und wie er in Logik-Apps, Workflows, Anwendungen und Agenten verfügbar gemacht wird. Sie können Aktionen, Trigger, Verweise und Richtlinien definieren. In diesem Abschnitt erklären wir die Benutzeroberfläche und behandeln einige Optionen, Sie sollten sich aber auch unbedingt selbst umsehen.

Erstellen von Aktionen

Als Erstes müssen Sie eine Aktion erstellen, die den Stimmungsvorgang für die Textanalyse-API aufruft. Auf der Registerkarte "Definition " werden im linken Bereich alle Aktionen, Trigger (für Logik-Apps, Power Automate und Copilot Studio), Verweise und Richtlinien angezeigt, die für den Connector definiert sind.

1. Wählen Sie Neue Aktion aus.

2. Im Bereich Allgemein fügen Sie eine Zusammenfassung, eine Beschreibung und eine Vorgangs-ID für diese Aktion hinzu.

   Parameter	Wert
   Übersicht	Gibt eine numerische Bewertung zurück, die die erkannte Stimmung darstellt
   Beschreibung	Die API gibt einen numerischen Wert zwischen 0 und 1 zurück. Werte nahe 1 zeigen eine positive Stimmung an, Werte nahe 0 zeigen eine negative Stimmung an.
   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:

   • keiner: Wird normalerweise in der logischen Anwendung oder im Flow angezeigt
   • erweitert: Verborgen unter einem anderen Menü
   • intern: Verborgen für den Benutzer
   • Wichtig: Wird dem Benutzer immer zuerst angezeigt

3. Im Bereich Anfrage wählen Sie von Beispiel importieren aus.

4. Geben Sie die Informationen an, die für die Verbindung mit der API erforderlich sind, sowie den Anfragetext (wird nach der Tabelle bereitgestellt) und wählen Sie dann Importieren.

   Wir stellen diese Informationen für Sie bereit, aber für eine öffentliche API erhalten Sie diese Informationen normalerweise aus der Dokumentationen wie z. B. Textanalyse-API (v2.0).

   Parameter	Wert
   Verb	NACHRICHT
   URL	https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment
   Body	Verwenden Sie das Beispiel JSON.

   Beispiel:

   {
     "documents": [
       {
         "language": "string",
         "id": "string",
         "text": "string"
       }
     ]
   }
   

5. Wählen Sie im Bereich Antwort die Option Standardantwort hinzufügen aus.

6. Geben Sie den Antworttext an und wählen Sie dann Importieren aus. Wie beim Anforderungstext stellen wir Ihnen diese Information zur Verfügung, aber sie steht normalerweise in der API-Dokumentation bereit.

   Beispiel:

   {
    "documents": [
      {
        "score": 0.0,
        "id": "string"
      }
    ],
    "errors": [
      {
        "id": "string",
        "message": "string"
      }
    ]
   }
   

   Der Bereich Prüfung zeigt alle Probleme an, die in der API-Definition erkannt werden.

7. Beheben Sie alle Probleme. Ein grünes Häkchen sollte angezeigt werden, wenn die Definitionsüberprüfung erfolgreich war.

8. Wählen Sie in der oberen rechten Ecke des Assistenten die Option Konnektor aktualisieren aus.

Aktualisieren Sie die Definition

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

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

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.

3. Aktualisieren Sie im Bereich Schemaeigenschaft die Werte für den Parameter und wählen Sie dann Zurück aus.

   Parameter	Wert
   Title	Kennung
   Beschreibung	Ein Bezeichner für jedes übermittelte Dokument
   Standardwert	1
   Ist erforderlich	Ja

4. Wählen Sie im Bereich Parameter die Option Sprache>Bearbeiten, und wiederholen Sie den für id verwendeten Prozess mit den folgenden language Werten:

   Parameter	Wert
   Title	Language
   Beschreibung	Der zwei- oder vierstellige Sprachcode für den Text
   Standardwert	en
   Ist erforderlich	Ja

5. Wählen Sie im Bereich Parameter die Option Text>Bearbeiten, und wiederholen Sie den für id und language verwendeten Prozess mit den folgenden text Werten:

   Parameter	Wert
   Title	Text
   Beschreibung	Der Text für die Stimmungsanalyse
   Standardwert	Ohne
   Ist erforderlich	Ja

6. Im Bereich Parameter wählen Sie Zurück, um zur Hauptregisterkarte Definition zurückzukehren.

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

8. Wählen Sie unten Den Code aus, um zum nächsten Abschnitt zu wechseln.

Schritt 4: (Optional) Verwenden Sie die Unterstützung für angepassten Code

Benutzerdefinierter Code transformiert Anforderungs- und Antwortnutzlasten über den Umfang vorhandener Richtlinienvorlagen hinaus. Transformationen umfassen das Senden externer Anforderungen zum Abrufen zusätzlicher Daten. Wenn Code verwendet wird, hat er Vorrang vor der codelosen Definition. Das bedeutet, dass der Code ausgeführt wird und wir die Anfrage nicht an das Back-End senden.

Sie können entweder Ihren Code einfügen oder eine Datei mit Ihrem Code hochladen. Ihr Code muss:

• In C# geschrieben sein.
• Eine maximale Ausführungszeit von fünf Sekunden haben.
• Eine Dateigröße von nicht mehr als 1 MB haben.

Anweisungen und Beispiele zum Schreiben von Code finden Sie unter Code in einen benutzerdefinierten Connector schreiben.

Häufig gestellte Fragen zu benutzerdefiniertem Code finden Sie unter FAQ zu angepasstem Code.

1. Auf der Registerkarte Code fügen Sie Ihren benutzerdefinierten Code mit einer der folgenden Optionen ein:

   • Kopieren/einfügen
   • Wählen Sie die Schaltfläche Hochladen aus.

   Wenn Sie Ihren benutzerdefinierten Code hochladen, sind nur Dateien mit der Erweiterung .cs oder .csx verfügbar.

   

   Wichtig

   Derzeit unterstützen wir nur die Syntaxhervorhebung im Code-Editor. Stellen Sie sicher, dass Sie Ihren Code lokal testen.

2. Nachdem Sie Ihren Code eingefügt oder hochgeladen haben, wählen Sie die Umschalttaste neben Code deaktiviert, um Ihren Code zu aktivieren. Der Name der Umschalttaste ändert sich in Code aktiviert.

   Sie können Ihren Code jederzeit aktivieren oder deaktivieren. Wenn der Umschalter auf Code deaktiviert steht, wird Ihr Code gelöscht.

3. Wählen Sie die Aktionen und Auslöser aus, die auf Ihren benutzerdefinierten Code angewendet werden sollen, indem Sie eine Option im Dropdownmenü auswählen. Wenn kein Vorgang ausgewählt ist, werden die Aktionen und Auslöser auf alle Vorgänge angewendet.

   

Schritt 5: Testen des Connectors

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 Registerkarte TestNeue Verbindung aus.

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

   Anmerkung

   Bei APIs, die eine Bearer-Authentifizierung erfordern, fügen Sie Bearer und ein Leerzeichen vor dem API-Schlüssel hinzu.

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

   • (In Power Automate) Sie gelangen zurück zur Registerkarte Test. Wählen Sie das Aktualisieren-Symbol, damit die Verbindungsinformationen aktualisiert werden.

     

   • (In Power Apps) Sie gelangen zu der Liste der in der aktuellen Umgebung verfügbaren Verbindungen. Wählen Sie im linken Bereich Benutzerdefinierte Connectors aus. Wählen Sie den Connector, den Sie erstellt haben, und gehen Sie dann zurück zur Registerkarte Test.

4. Geben Sie auf der Registerkarte Test einen Wert für das Feld Text ein (die anderen Felder verwenden die Standardwerte, die Sie zuvor festgelegt haben). Wählen Sie dann Testvorgang aus.

   Der Konnektor ruft die API auf.

5. Überprüfen Sie die Antwort mit dem Stimmungswert.

   

Bewährte Methoden für CLI-Benutzer

• Laden Sie alle Ihre Connectors herunter, und verwenden Sie Git oder ein anderes Quellcodemanagementsystem, um die Dateien zu speichern.

• Stellen Sie bei einem fehlerhaften Update den Connector erneut bereit, indem Sie den Aktualisierungsbefehl mit dem richtigen Satz von Dateien aus dem Quellcodemanagementsystem erneut ausführen.

• Testen Sie den benutzerdefinierten Connector und die Einstellungsdatei in einer Testumgebung, bevor Sie ihn in der Produktionsumgebung bereitstellen.

• Überprüfen Sie immer, ob die Umgebungs- und Connector-ID korrekt sind.

Nächste Schritte,

Sie haben jetzt einen benutzerdefinierten Connector erstellt und sein Verhalten festgelegt. Nun können Sie ihn verwenden über:

• Power Automate
• Power Apps
• Logik-Apps
• Copilot Studio

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.

• Ihren Connector mit anderen teilen
• Ihren Connector zertifizieren

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.