Einen benutzerdefinierten Connector auf der Grundlage einer OpenAPI-Definition erstellen

Anmerkung

Dieser Artikel ist Teil einer Tutorialreihe zum Erstellen und Verwenden benutzerdefinierter Connectors in Azure Logic Apps, Microsoft Power Automate und Microsoft Power Apps sowie zum Aufrufen von Connectors als Tools in Microsoft Copilot Studio. 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 mithilfe einer OpenAPI-Definition, die die Textanalyse-Sentiment-API der Cognitive Services beschreibt, einen benutzerdefinierten Konnektor (unser Beispiel in dieser Reihe).

Eine andere Möglichkeit zum Beschreiben einer API finden Sie unter Erstellen eines neuen benutzerdefinierten Connectors.

Anforderungen

  • Eine OpenAPI-Definition (OAD), die die Beispiel-API beschreibt. Beim Erstellen eines benutzerdefinierten Connectors muss die OpenAPI-Definition kleiner als 1 MB sein. Die OpenAPI-Definition muss sich im OpenAPI 2.0-Format (früher als Swagger) formatieren.

    Wenn mehrere Sicherheitsdefinitionen vorhanden sind, wählt der benutzerdefinierte Connector die oberste Sicherheitsdefinition aus. Die benutzerdefinierte Connector-Erstellung unterstützt keine Client-Anmeldeinformationen (z. B. Anwendung und Kennwort) in der OAuth-Sicherheitsdefinition.

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

  • Eines der folgenden Abonnements:

  • Wenn Sie Logic Apps verwenden, erstellen Sie zunächst einen benutzerdefinierten Konnektor von Azure Logic Apps.

Anmerkung

OpenAPI-Definition importieren

In diesem Lernprogramm wird eine OpenAPI-Beispieldefinition für die Cognitive Services Textanalyse Sentiment-API verwendet. Um nachzuvollziehen, erstellen Sie eine lokale JSON-Datei mit dem Namen SentimentDemo.json und fügen Sie die folgende OpenAPI 2.0-Definition ein:

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "SentimentDemo",
    "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
  },
  "host": "westus.api.cognitive.microsoft.com",
  "basePath": "/",
  "schemes": ["https"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  },
  "security": [{"api_key": []}],
  "paths": {
    "/text/analytics/v2.0/sentiment": {
      "post": {
        "summary": "Returns a numeric score representing the sentiment detected",
        "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
        "operationId": "DetectSentiment",
        "parameters": [{
          "in": "body",
          "name": "body",
          "schema": {
            "type": "object",
            "properties": {
              "documents": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "string", "x-ms-summary": "id"},
                    "language": {"type": "string", "x-ms-summary": "language"},
                    "text": {"type": "string", "x-ms-summary": "text"}
                  }
                }
              }
            }
          }
        }],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "type": "object",
              "properties": {
                "documents": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "score": {"type": "number", "format": "float", "description": "score", "x-ms-summary": "score"},
                      "id": {"type": "string", "description": "id", "x-ms-summary": "id"}
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Sie können diese OpenAPI-Definition jetzt importieren. Die Definition enthält alle erforderlichen Informationen. Sie können diese Informationen überprüfen und aktualisieren, während Sie den benutzerdefinierten Connector-Assistenten durchlaufen.

Beginnen Sie mit dem Importieren der OpenAPI-Definition für Logic Apps oder für Power Automate und Power Apps.

OpenAPI-Definition für Logic Apps importieren

  1. Gehen Sie zum Azure-Portal und öffnen Sie den Logik-Apps-Connector, den Sie zuvor unter Erstellen eines benutzerdefinierten Azure Logic Apps-Connectors erstellt haben.

  2. Wählen Sie im Menü Ihres Connectors Logik-Apps-Connector und dann Bearbeiten aus.

    Logik-Apps-Connector bearbeiten.

  3. Wählen Sie unter AllgemeinOpenAPI-Datei hochladen aus und gehen Sie dann zur OpenAPI-Definition, die Sie erstellt haben.

    OpenAPI-Datei hochladen.

Anmerkung

Dieses Lernprogramm konzentriert sich auf eine REST-API, aber Sie können auch eine SOAP-API mit Logik-Apps verwenden.

OpenAPI-Definition für Power Automate und Power Apps importieren

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

  2. Wählen Sie im linken Bereich "Lösungen" und dann die gewünschte Lösung aus, oder erstellen Sie eine neue Lösung.

  3. Wählen Sie Neu>Automatisierung>Angepasster Konnektor.

  4. Wählen Sie "OpenAPI-Datei importieren" aus.

  5. Geben Sie einen Namen für den benutzerdefinierten Connector ein, wählen Sie die SentimentDemo.json erstellte Datei aus, und wählen Sie dann "Weiter" aus.

    Laden Sie eine Sammlung hoch.

    Parameter Wert
    Name des benutzerdefinierten Connectors SentimentDemo

Allgemeine Einzelheiten überprüfen

Von diesem Punkt an zeigen wir die Benutzeroberfläche Power Automate, aber die Schritte sind bei allen drei Technologien weitgehend gleich. Wir werden auf eventuelle Unterschiede hinweisen. In diesem Teil des Thema werden wir hauptsächlich die Benutzeroberfläche überprüfen und Ihnen zeigen, wie die Werte den Abschnitten der OpenAPI-Datei entsprechen.

  1. Stellen Sie oben im Assistenten sicher, dass als Name SentimentDemo festgelegt ist, und wählen Sie dann Connector erstellen aus.

  2. Überprüfen Sie auf der Seite Allgemein die Informationen, die aus der OpenAPI-Definition importiert wurden, einschließlich API-Host und Basis-URL für die API. Der Connector verwendet den API-Host und die Basis-URL, um zu bestimmen, wie die API aufgerufen werden soll.

    Benutzerdefinierter Konnektor – Seite „Allgemein“.

    Anmerkung

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

    Der folgende Abschnitt der OpenAPI-Definition enthält Informationen für diese Seite der Benutzeroberfläche:

      "info": {
    "version": "1.0.0",
    "title": "SentimentDemo",
    "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
  },
  "host": "westus.api.cognitive.microsoft.com",
  "basePath": "/",
  "schemes": [
    "https"
  ]

Authentifizierungstyp überprüfen

In benutzerdefinierten Konnektoren stehen verschiedene Optionen für die Authentifizierung zur Verfügung. Die Cognitive Services-APIs verwenden die API-Schlüsselauthentifizierung, das ist also in der OpenAPI-Definition angegeben.

Überprüfen Sie auf der Seite Sicherheit die Authentifizierungsinformationen für den API-Schlüssel.

API-Schlüsselparameter.

Die Beschriftung wird angezeigt, wenn jemand zum ersten Mal eine Verbindung mit dem benutzerdefinierten Connector herstellt. Sie können Bearbeiten wählen und diesen Wert ändern. Der Parametername und der Speicherort müssen mit dem übereinstimmen, was die API erwartet, in diesem Fall Ocp-Apim-Subscription-Key und Header.

Der folgende Abschnitt der OpenAPI-Definition enthält Informationen für diese Seite der Benutzeroberfläche:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

Überprüfen Sie die Definition des Konnektors

Die Seite Definition im Assistenten für benutzerdefinierte Connector bietet zahlreiche Optionen, um zu definieren, wie Ihr Connector funktioniert und wie er in Logik-Apps, Flows und Apps sichtbar gemacht wird. In diesem Abschnitt erläutern wir die UI und behandeln einige Optionen, aber wir ermutigen Sie auch dazu, selbst nachzuforschen. Informationen zur Neudefinition von Objekten in dieser UI finden Sie unter Connector-Definition erstellen.

  1. Im folgenden Bereich werden alle Aktionen, Trigger (für Logik-Apps und Power Automate) und Verweise angezeigt, die für den Connector definiert sind. In diesem Fall wird die Aktion DetectSentiment aus der OpenAPI-Definition 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.

    Definitionsseite – Aktionen und Trigger.

  2. Der Bereich Allgemein enthält Informationen zur derzeit ausgewählten Aktion bzw. zum derzeit ausgewählten Trigger. Sie können die Informationen hier bearbeiten, einschließlich der Eigenschaft Visibility für Vorgänge und Parameter in einer Logik-App oder einem Flow:

    • Keine: wird in der Logic App oder im Flow normal dargestellt

    • Erweitert: versteckt unter einem zusätzlichen Menü

    • intern: für den Benutzer verborgen

    • Wichtig: wird dem Benutzer immer zuerst angezeigt

      Definitionsseite – Allgemein.

  3. Im Bereich Anforderung werden Informationen basierend auf der in der OpenAPI-Definition enthaltenen HTTP-Anforderung angezeigt. 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 body in Kürze näher ansehen.

    Definitionsseite – Anforderung.

    Der folgende Abschnitt der OpenAPI-Definition enthält Informationen für die Bereiche Allgemein und Anforderung der Benutzeroberfläche:

    "paths": {
  "/text/analytics/v2.0/sentiment": {
    "post": {
      "summary": "Returns a numeric score representing the sentiment detected",
      "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
      "operationId": "DetectSentiment"

  4. Im Bereich Antwort werden Informationen basierend auf der in der OpenAPI-Definition enthaltenen HTTP-Antwort angezeigt. In diesem Fall ist nur eine Antwort für 200 (erfolgreiche Antwort) angegeben. Sie können jedoch zusätzliche Antworten festlegen.

    Definitionsseite – Antwort.

    Der folgende Abschnitt der OpenAPI-Definition enthält einige Informationen im Bezug auf die Antwort:

    "score": {
 "type": "number",
 "format": "float",
 "description": "score",
 "x-ms-summary": "score"
},
"id": {
 "type": "string",
 "description": "id",
 "x-ms-summary": "id"
}

    Dieser Abschnitt zeigt die beiden Werte, die vom Connector zurückgegeben werden: id und score. Er enthält ihre Datentypen und das Feld x-ms-summary, das ist eine OpenAPI-Erweiterung. Weitere Informationen zu dieser und anderen Erweiterungen finden Sie unter Eine OpenAPI-Definition für einen benutzerdefinierten Connector erweitern.

  5. Der Bereich Prüfung zeigt alle Probleme an, die in der API-Definition erkannt werden. Überprüfen Sie diesen Bereich, bevor Sie einen Connector speichern.

    Definitionsseite – Prüfung.

Aktualisieren Sie die Definition

Die heruntergeladene OpenAPI-Definition ist zwar ein gutes allgemeines Beispiel, Sie verwenden jedoch vielleicht Definitionen, die umfassend aktualisiert werden müssen, damit der Connector in einer Logik-App, einem Flow oder einer App einfacher zu verwenden ist. Wir werden Ihnen zeigen, wie Sie eine Änderung an der Definition vornehmen können.

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

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

    Anforderungstext-ID bearbeiten.

  3. Im Bereich Schema-Eigenschaft aktualisieren Sie die Beschreibung des Parameters und wählen dann Zurück.

    Schema-Eigenschaft bearbeiten.

    Parameter Wert
    Beschreibung Eine numerische Kennung für jedes von Ihnen eingereichte Dokument

  4. Wählen Sie im Bereich Parameter die Option Zurück aus, um zurück zur Hauptseite der Definition zu wechseln.

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

Aktualisierte OpenAPI-Datei herunterladen

Sie können einen benutzerdefinierten Connector aus einer OpenAPI-Datei oder von Grund auf erstellen (in Power Automate und Power Apps). Unabhängig davon, wie Sie den Connector erstellen, können Sie die vom Dienst intern verwendete OpenAPI-Definition herunterladen.

  • Laden Sie in Logic Apps vom benutzerdefinierten Konnektor herunter.

    OpenAPI-Definition für Logik-Apps herunterladen.

  • Unter Power Automate oder Power Apps können Sie aus der Liste der benutzerdefinierten Connectors herunterladen.

    OpenAPI Definition für Power Automate herunterladen.

Den Konnektor testen

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.

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

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

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

    • Unter Power Automate gelangen Sie zurück zur Seite Test. Wählen Sie das Aktualisierungssymbol, um sicherzustellen, dass die Verbindungsinformationen aktualisiert werden.

      Verbindung aktualisieren.

    • Unter Power Apps gelangen Sie zu der Liste der in der aktuellen Umgebung verfügbaren Verbindungen. Wählen Sie oben rechts das Zahnradsymbol und dann Benutzerdefinierte Konnektoren aus. Wählen Sie den Connector, den Sie erstellt haben, und gehen Sie dann zurück zur Seite Test.

      Zahnradsymbol im Dienst.

  4. Geben Sie auf der Seite Test einen Wert für das Feld Text ein (die anderen Felder enthalten die von Ihnen zuvor festgelegten Standardwerte), und wählen Sie Vorgang testen aus.

    Vorgang testen.

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

    Connector-Antwort.

Den benutzerdefinierten Konnektor verwenden

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

Einen benutzerdefinierten Connector und eine Connector-Aktion für Microsoft 365 Copilot für Vertrieb erstellen

Sie können einen benutzerdefinierten Connector aus einer OpenAPI-Definition in Power Apps oder Power Automate erstellen, der dann für Microsoft 365 Copilot für Vertrieb verwendet werden kann. Wechseln Sie zu Erstellen eines benutzerdefinierten Connectors und einer Connector-Aktion, um zu erfahren, wie Sie beginnen.

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 mit Connectors erhalten und wählen Sie die Art Ihres Feedbacks aus.

  • Last updated on