Freigeben über

Einen benutzerdefinierten Connector von Grund auf neu erstellen

Anmerkung

Dieser Artikel gehört zu einer Tutorialreihe zur Erstellung und Verwendung benutzerdefinierter Connectors in Azure Logic Apps, Microsoft Power Automate und Microsoft Power Apps und mithilfe von Copilot-Konnektoren und Aktionen in Microsoft Copilot Studio. Stellen Sie sicher, dass Sie die Übersicht über kundenspezifische Konnektoren lesen, um den Prozess zu verstehen.

Gehen Sie zu Power Platform-Connectors in Copilot Studio verwenden um zu erfahren, wie Sie die Connectors als Connector-Aktionen in Ihrem Microsoft Copilot-Agenten aufrufen können.

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 Artikel erstellen Sie einen benutzerdefinierten Connector von Grund auf neu, ohne eine OpenAPI-Definition zur Beschreibung des Standpunktvorgangs für die Textanalyse-API von Azure Cognitive Services (unser Beispiel für diese Serie) zu verwenden. Stattdessen beschreiben Sie den Connector vollständig im Assistenten für benutzerdefinierte Connectors.

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

Anmerkung

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

Anforderungen

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, die Ihren benutzerdefinierten Konnektor enthält. Erfahren Sie, wie eine Lösung erstellt wird

  4. Wählen Sie das Dropdown-Menü Neu und Autimation>Kundenkonnektor.

    Der Assistent für neue Konnektoren wird geöffnet.

  5. Geben Sie den Konnektor-Namen ein, z. B. SentimentDemo.

    Führen Sie die restlichen Schritte anhand der folgenden Anweisungen aus.

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:

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

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

  1. Wählen Sie auf der Registerkarte 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. 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.

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

  3. 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 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, Auslöser (für Logic Apps, Power Automate und Copilot Studio ) und Referenzen angezeigt, die für den Connector definiert sind.

Anmerkung

Es gibt keine Auslöser in diesem Connector. Mehr Informationen zu Trigger für benutzerdefinierte Connectors unter Verwenden eines Webhook als Trigger für Azure Logic Apps und Power Automate.

  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
    Default value 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
    Eigenschaft Der zwei- oder vierstellige Sprachcode für den Text
    Default value en
    Ist erforderlich Ja

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

    Parameter Wert
    Title Text
    Eigenschaft Der Text für die Stimmungsanalyse
    Default value 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.

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.

Anmerkung

  • Dieser Schritt ist optional. Sie können die codelose Umgebung zum Erstellen Ihres Konnektors abschließen, indem Sie diesen Schritt ignorieren und zu Schritt 5: 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.

  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.

    Screenshot von „Ihren benutzerdefinierten Code hochladen“.

    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.

    Screenshot von „Aktionen und Auslöser auswählen“.

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.

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.

  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.

      Screenshot der Schaltfläche „Verbindung aktualisieren“

    • (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.

    Screenshot der Connectorantwort.

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:

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.