Einen benutzerdefinierten Connector von Grund auf neu erstellen
Dieser Artikel ist Teil einer Tutorialreihe zur Erstellung und Verwendung von benutzerdefinierten Connectoren in Azure Logic Apps, Microsoft Power Automate und Microsoft Power Apps.
Hinweis
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 von Grund auf neu, ohne Verwendung einer Postman-Sammlung oder einer OpenAPI-Definition zur Beschreibung des Stimmungsvorgangs für die Azure Cognitive Services-Textanalyse-API (unser Beispiel für diese Serie). Stattdessen beschreiben Sie den Connector vollständig im Assistenten für benutzerdefinierte Connectors.
Weitere Möglichkeiten zur Beschreibung einer API finden Sie in den folgenden Themen:
- Einen benutzerdefinierten Connector auf der Grundlage einer OpenAPI-Definition erstellen
- Einen benutzerdefinierten Connector auf der Grundlage einer Postman-Sammlung erstellen
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 mindestens mit einer Basisvariante der OpenAPI-Definition oder Postman-Sammlung beginnen.
Voraussetzungen
Ein API-Schlüssel für die Cognitive Services-API zur Textanalyse
Eines der folgenden Abonnements:
Starten Sie den Assistenten für benutzerdefinierte Connectors
Melden Sie sich bei Power Apps oder Power Automate an.
Wählen Sie im linken Bereich Daten > Benutzerdefinierte Connectors aus.
Wählen Sie Neuer benutzerdefinierter Connector > Ohne Vorlage erstellen.
Geben Sie einen Namen für den benutzerdefinierten Connector ein und wählen Sie dann Weiter aus.
Parameter Wert Titel des benutzerdefinierten Connectors SentimentDemo
Schritt 1: Allgemeine Angaben aktualisieren
Ab diesem Punkt zeigen wir die Power Automate-Oberfläche, aber die Schritte sind bei allen Technologien weitgehend gleich. Wir weisen Sie auf alle Unterschiede hin.
Auf der Registerkarte Allgemein führen Sie die folgenden Schritt aus:
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 für sie nützlich sein könnte.
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
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.
Wählen Sie auf der Registerkarte Sicherheit unter Authentifizierungstyp die Option API-Schlüssel aus.
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.
Parameter Wert Parameterbezeichnung API-Schlüssel Parametername Ocp-Apim-Subscription-Key Parameterstandort Header Stellen Sie oben im Assistenten sicher, dass als Name SentimentDemo festgelegt ist und wählen Sie dann Connector erstellen aus.
Schritt 3: Connector-Definition erstellen
Im Assistenten für benutzerdefinierte Konnektoren stehen zahlreiche Optionen zur Verfügung, um festzulegen, wie der Konnektor funktioniert und wie er in Logic Apps, Flows und Azure Logic Apps verfügbar gemacht 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 den Stimmungsvorgang für die Textanalyse-API aufruft.
Auf der Registerkarte Definition werden im linken Bereich alle Aktionen, Auslöser (für Logic Apps und Power Automate) und Referenzen angezeigt, die für den Connector definiert sind. Wählen Sie Neue Aktion aus.
Es gibt keine Auslöser in diesem Connector. Um mehr über Trigger für benutzerdefinierte Connectors zu erfahren, gehen Sie zu Verwenden eines Webhook als Trigger für Azure Logic Apps und Power Automate.
Der Bereich Allgemein enthält Informationen zur derzeit ausgewählten Aktion bzw. zum derzeit ausgewählten Trigger. 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:
- kein Wert: wird normalerweise in der logischen Anwendung oder im logischen Ablauf angezeigt
- erweitert: unter einem anderen Menü versteckt
- intern: für den Benutzer verborgen
- wichtig: wird dem Benutzer immer zuerst angezeigt
Der Bereich Anfrage zeigt Informationen an, die auf der HTTP-Anforderung für die Aktion basieren. Wählen Sie Aus Beispiel importieren aus.
Geben Sie die Informationen, die für die Verbindung mit der API erforderlich sind, sowie den Anforderungstext an (dieser wird nach dem folgenden Bild 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 den folgenden JSON-Code Beispiel:
{ "documents": [ { "language": "string", "id": "string", "text": "string" } ] }Der Bereich Antwort zeigt Informationen an, die auf der HTTP-Antwort für die Aktion basieren. Wählen Sie Standardantwort hinzufügen aus.
Geben Sie den Antworttext an und wählen Sie dann Importieren aus. Wie beim Anforderungstext stellen wir Ihnen diese Information nach dem Bild zur Verfügung, aber sie wird normalerweise in der API-Dokumentation bereitgestellt.
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. Überprüfen Sie den Status und wählen Sie dann in der oberen rechten Ecke des Assistenten Connector aktualisieren aus.
Aktualisieren Sie die Definition
Lassen Sie uns nun ein paar Dinge ändern, damit der Connector freundlicher ist, wenn jemand ihn in einer Logic App, einem Flow oder einer App verwendet.
Wählen Sie im Bereich Anforderung die Option Text und dann Bearbeiten aus.
Im Bereich Parameter sehen Sie nun die drei Parameter, die die API erwartet:
id,languageundtext. Wählen Sie id und dann Bearbeiten.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 Default value 1 Ist erforderlich Ja Wählen Sie im Bereich Parameter Sprache > Bearbeiten aus und wiederholen Sie den Vorgang, den Sie für die
idin den Schritten 2 und 3 dieses Verfahrens verwendet haben, mit den folgenden Werten.Parameter Wert Title Language Beschreibung Der zwei- oder vierstellige Sprachcode für den Text Default value en Ist erforderlich Ja Wählen Sie im Bereich Parameter Text > Bearbeiten aus und wiederholen Sie den Vorgang, den Sie für die
idin den Schritten 2 und 3 dieses Verfahrens verwendet haben, mit den folgenden Werten.Parameter Wert Titel Text Beschreibung Der Text für die Stimmungsanalyse Standardwert Keiner Ist erforderlich Ja Wählen Sie im Bereich Parameter Zurück, um zur Hauptregisterkarte Definition zurückzukehren.
Wählen Sie oben rechts im Assistenten Connector aktualisieren aus.
Schritt 4: (Optional) Aktivieren Sie Ihren Connector als KI-Plug-In
Verwenden Sie die Registerkarte KI-Plug-In (Vorschauversion) für einen Connector nur, wenn Sie planen, Ihren Connector zu zertifizieren. Damit ein Connector als KI-Plug-In verwendet werden kann, muss der Connector zertifiziert sein.
Bevor Sie Ihren Connector als KI-Plug-In aktivieren, stellen Sie sicher, dass Sie den Anwendungsfall für KI-Plug-In-Szenarien verstehen und andere Überlegungen wie Unterstützbarkeit, Best Practices und Empfehlungen überprüft haben. Weitere Informationen: Ein KI-Plug-In erstellen (Vorschauversion)
Wählen Sie im linken Navigationsbereich Benutzerdefinierte Connectors aus.
Wenn Benutzerdefinierte Connectors nicht angezeigt wird, wählen Sie Mehr > Alle entdecken > Benutzerdefinierte Connectors. Die Option wird im linken Navigationsbereich angezeigt.
Wählen Sie in der oberen rechten Ecke eine Option aus dem Menü Neuer benutzerdefinierter Connector aus.
Stellen Sie sicher, dass Sie Schritt 1, Schritt 2 und Schritt 3 in diesem Artikel abgeschlossen haben.
Wählen Sie die Registerkarte KI-Plug-In (Vorschauversion) aus.
Geben Sie im Abschnitt Plug-In-Manifest Details ein, um diesen Connector als KI-Plug-In zu aktivieren.
Feld Description Plug-In-Manifest: Name Name des KI-Plug-Ins. Plug-In-Manifest: Beschreibung Beschreibung des KI-Plug-Ins. Weitere Informationen: Ein KI-Plug-In erstellen (Vorschauversion) Plug-In-Manifest: Kontakt-E-Mail E-Mail-Adresse des Kontakts für dieses KI-Plug-In. Plug-In-Manifest: URL mit rechtlichen Informationen Ein öffentlich zugänglicher Ort, an dem die rechtlichen Informationen zu Ihrem KI-Plug-In veröffentlicht werden. Scrollen Sie nach unten zum Abschnitt Plug-In-Aktionsdetails und geben Sie die Aktionsdetails für jede Aktion in Ihrem Connector-KI-Plug-In ein.
Feld Description Details zur Plug-In-Aktion: Zusammenfassung Zusammenfassung über jede KI-Plug-In-Aktion, die die Benutzer ausführen können. Details zur Plug-In-Aktion: Beschreibung Beschreibung jeder Aktion, die Benutzer in Bezug auf diesen spezifischen KI-Plug-In-Aktionsschritt ausführen können. Kontrollkästchen: Als Copilot-Plug-In-Vorgang aktivieren Wenn sich im Kontrollkästchen ein Häkchen befindet, ist der KI-Plug-In-Vorgang aktiviert. Kontrollkästchen: Benutzerbestätigung erforderlich? Wenn das Kontrollkästchen aktiviert ist, ist eine Bestätigung durch den Benutzer erforderlich. Tipp
Wenn Sie Hilfe beim Definieren Ihrer Aktionen benötigen, aktivieren Sie den Schalter Swagger-Editor.
Scrollen Sie nach unten zum Abschnitt Parameter und geben Sie die Parameterdetails für Ihr Connector-KI-Plug-In ein.
Feld Description Parameter: Name Name des Parameters. Verwenden Sie identifizierbare Namen wie Kontobezeichner anstelle von ID. Parameter: Beschreibung Beschreibung des Parameters. Verwenden Sie eine beschreibende Erklärung wie Geburtsdatum für einen Kontakt im Format MM/TT/JJJJ anstelle von G_Datum. Solche Namen und Beschreibungen helfen LLMs (großen Sprachmodellen), effektiv mit dem KI-Plug-In zu interagieren. Parameter: Zusammenfassung Zusammenfassende Informationen zum Parameter. Parameter: Standardwert Standardwert des Parameters. Wählen Sie im Abschnitt Anforderung unter den Abschnitten KI-Plug-In (Vorschauversion) den Eingabeparameter aus und geben Sie dann eine Beschreibung ein.
Schritt 5: (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.
Hinweis
- Dieser Schritt ist optional. Sie können die codelose Umgebung zum Erstellen Ihres Konnektors abschließen, indem Sie diesen Schritt ignorieren und zu Schritt 6: Testen des Konnektors gehen.
- Support für benutzerdefinierten Code ist in der öffentlichen Vorschauversion verfügbar.
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.
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.
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 die Umschalttaste auf Code deaktiviert steht, wird Ihr Code gelöscht.
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 6: Testen des Connectors
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.
Wählen Sie auf der Registerkarte Test Neue Verbindung aus.
Geben Sie den API-Schlüssel aus der Textanalyse-API ein und wählen Sie dann Verbindung erstellen aus.
Hinweis
Bei APIs, die eine Bearer-Authentifizierung erfordern, fügen Sie Bearer und ein Leerzeichen vor dem API-Schlüssel hinzu.
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 Daten > Benutzerdefinierte Connectors aus. Wählen Sie den Connector, den Sie erstellt haben, und gehen Sie dann zurück zur Registerkarte Test.
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 Connector ruft die API auf, und Sie können die Antwort überprüfen, die die Stimmungsbewertung enthält.
(Für CLI-Benutzer) Best Practices
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 einen benutzerdefinierten Connector erstellt und sein Verhalten definiert. Nun können Sie den Connector verwenden von:
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.