Freigeben über

Einen benutzerdefinierten Konnektor mit der CLI erstellen

Das Kommandozeilen-Werkzeug paconn soll die Erstellung von kundenspezifischen Connectors für Copilot Studio und Power Platform unterstützen.

Anmerkung

installieren

  1. Installieren Sie Python 3.5 oder höher über [https://www.python.org/downloads](Python downloads). Wählen Sie für jede höhere Version als Python 3.5 den Download link aus. Folgen Sie für Linux und Mac OS X dem entsprechenden Link auf der Seite. Sie können die Installation auch mit einem betriebssystemspezifischen Paket-Manager Ihrer Wahl durchführen.

  2. Führen Sie das Installationsprogramm aus, um die Installation zu starten, und aktivieren Sie das Kontrollkästchen für das Hinzufügen von Python zu PATH.

  3. Stellen Sie sicher, dass sich der Installationspfad in der PATH-Variablen befindet, indem Sie folgenden Befehl ausführen:

    python --version

  4. Installieren Sie nach der Installation von Python paconn, indem Sie folgenden Befehl ausführen:

    pip install paconn

    Wenn Sie die Fehlermeldung Zugriff verweigert erhalten, ziehen Sie die Verwendung der --user Option in Betracht oder Ausführen des Befehls als Administrator (Windows).

Verzeichnis und Dateien für den benutzerdefiniertes Connector

Ein benutzerdefinierter Connector besteht aus zwei bis vier Dateien:

  • eine Offene API/Swaggr-Definition
  • eine API-Eigenschaftendatei
  • ein optionales Symbol für den Konnektor
  • optionale CSharp-Skriptdatei

Die Dateien befinden sich in der Regel in einem Verzeichnis, dessen Name die Connector-ID ist.

Manchmal kann das Verzeichnis des benutzerdefinierten Connectors die Datei settings.json enthalten. Obwohl diese Datei nicht Teil der Connectordefinition ist, können Sie sie als Argumentspeicher für die CLI verwendet werden.

API-Definitionsdatei (Swagger-Definitionsdatei)

Die API-Definitionsdatei beschreibt die API für den benutzerdefinierten Connector mithilfe der OpenAPI-Spezifikation, auch als Swagger-Datei bekannt. Weitere Informationen, wie API-Definitionen helfen, einen benutzerdefinierten Connector zu verwenden, finden Sie unter Einen benutzerdefinierten Connector auf der Grundlage einer OpenAPI-Definition erstellen. Sehen Sie sich auch das Tutorial im Artikel Eine OpenAPI-Definition für einen benutzerdefinierten Connector erweitern an.

API-Eigenschaftendatei

Die API-Eigenschaftendatei enthält einige Eigenschaften für den benutzerdefinierten Konnektor, die nicht Teil der API-Definition sind. Die API Eigenschaftendatei enthält Informationen wie die Markenfarbe, Authentifizierungsinformationen usw. Eine typische API-Eigenschaftendatei sieht wie das folgende Beispiel aus:

{
  "properties": {
    "capabilities": [],
    "connectionParameters": {
      "api_key": {
        "type": "securestring",
        "uiDefinition": {
          "constraints": {
            "clearText": false,
            "required": "true",
            "tabIndex": 2
          },
          "description": "The KEY for this API",
          "displayName": "KEY",
          "tooltip": "Provide your KEY"
        }
      }
    },
    "iconBrandColor": "#007EE6",
    "scriptOperations": [
        "getCall",
        "postCall",
        "putCall"
    ],
    "policyTemplateInstances": [
      {
        "title": "MyPolicy",
        "templateId": "setqueryparameter",
        "parameters": {
            "x-ms-apimTemplateParameter.name": "queryParameterName",
            "x-ms-apimTemplateParameter.value": "queryParameterValue",
            "x-ms-apimTemplateParameter.existsAction": "override"
        }
      }
    ]    
  }
}

Hier finden Sie weitere Informationen zu den einzelnen Eigenschaften:

  • properties: Der Container für die Informationen.

  • connectionParameters: Definiert den Verbindungsparameter für den Dienst.

  • iconBrandColor: Die Icon-Markenfarbe im HTML-Hex-Code für den benutzerdefinierten Konnektor.

  • scriptOperations: Eine Liste der Operationen, die mit der Skriptdatei ausgeführt werden. Eine leere scriptOperations-Liste zeigt an, dass alle Operationen mit der Skriptdatei ausgeführt werden.

  • capabilities: Beschreibung der Funktionen des Konnektors. Zum Beispiel reine Cloud- und On-Premises-Gateways.

  • policyTemplateInstances: Eine optionale Liste von Instanzen von Richtlinienvorlagen und Werten, die im benutzerdefinierten Konnektor verwendet werden.

Symboldatei

Die Symboldatei ist ein kleines Bild, das das Symbol für den benutzerdefinierten Connector darstellt.

Skriptdatei

Das Visual C# Skript (CSX)-Skriptdatei, die für den benutzerdefinierten Connector bereitgestellt und bei jedem Aufruf einer Teilmenge der Vorgänge des Connectors ausgeführt wird.

Einstellungsdatei

Statt die Argumente in der Befehlszeile bereitzustellen, können sie in der Datei settings.json angegeben werden. Eine typische settings.json-Datei sieht wie dieses Beispiel aus:

{
  "connectorId": "CONNECTOR-ID",
  "environment": "ENVIRONMENT-GUID",
  "apiProperties": "apiProperties.json",
  "apiDefinition": "apiDefinition.swagger.json",
  "icon": "icon.png",
  "script": "script.csx",
  "powerAppsApiVersion": "2016-11-01",
  "powerAppsUrl": "https://api.powerapps.com"
}

Diese Elemente finden Sie in der Einstellungsdatei. Wenn eine Option fehlt, jedoch erforderlich ist, wird in der Konsole zur Angabe der fehlenden Informationen aufgefordert.

  • connectorId: Die Konnektor-ID-Zeichenfolge für den benutzerdefinierten Konnektor. Download und Update-Vorgänge erfordern den Konnektor-ID-Parameter, im Gegensatz zu den Erstellen und Validieren-Vorgänge. Der Erstellen-Befehl erstellt einen neuen benutzerdefinierten Konnektor mit einer neuen ID. Wenn Sie einen bestehenden benutzerdefinierten Connector aktualisieren müssen, der gerade mit der gleichen Einstellungsdatei erstellt wurde, stellen Sie sicher, dass die Einstellungsdatei ordnungsgemäß mit der neuen Connector-ID aus dem Erstellungsvorgang aktualisiert wird.

  • environment: Die Umgebungs-ID-Zeichenfolge für den benutzerdefinierten Konnektor. Alle Vorgänge erfordern diesen Parameter, mit Ausnahme des Validierungsvorgangs.

  • apiProperties: Der Pfad zu der API-Eigenschaften-Datei . Für Erstellungs- und Aktualisierungsvorgänge ist die API-Eigenschaftendatei erforderlich. Wenn diese Option während des Downloads vorhanden ist, wird die Datei an den angegebenen Speicherort heruntergeladen; andernfalls wird sie als apiProperties.json Datei gespeichert.

  • apiDefinition: Der Pfad zur Swagger-Datei. Die Vorgänge Erstellen, Aktualisieren und Validieren erfordern die API-Definitionsdatei. Wenn diese Option während des Downloads vorhanden ist, wird die Datei an den angegebenen Speicherort heruntergeladen; andernfalls wird sie als apiDefinition.swagger.json Datei gespeichert.

  • icon: Der Pfad zur optionalen Symboldatei. Wenn kein bestimmter Parameter vorhanden ist, verwenden die Erstellungs- und Aktualisierungsvorgänge das Standardsymbol. Wenn diese Option während des Downloads vorhanden ist, wird die Datei an den angegebenen Speicherort heruntergeladen; andernfalls wird sie als icon.png Datei gespeichert.

  • script: Der Pfad zur optionalen Skriptdatei. Die Erstellungs- und Aktualisierungsvorgänge verwenden nur den Wert innerhalb des festgelegten Parameters. Wenn diese Option während des Downloads vorhanden ist, wird die Datei an den angegebenen Speicherort heruntergeladen; andernfalls wird sie als script.csx Datei gespeichert.

  • powerAppsUrl: Die API-URL für Power Apps. Dieser Parameter ist optional und standardmäßig auf https://api.powerapps.com festgelegt.

  • powerAppsApiVersion: Die zu verwendende API-Version für Power Apps. Dieser Parameter ist optional und standardmäßig auf 2016-11-01 festgelegt.

Befehlszeilenvorgänge

Anmeldung

Melden Sie sich bei Power Platform an, indem Sie den folgenden Befehl ausführen:

paconn login

Mit diesem Befehl werden Sie aufgefordert, sich mit dem Gerätecode-Anmeldevorgang anzumelden. Befolgen Sie die Eingabeaufforderung für die Anmeldung. Die Dienstprinzipauthentifizierung wird derzeit nicht unterstützt.

Abmelden

Abmelden durch Ausführen von:

paconn logout

Benutzerdefinierte Connectordateien herunterladen

Die Connectordateien werden immer in ein Unterverzeichnis heruntergeladen, dessen Name die Connector-ID ist. Wenn Sie ein Zielverzeichnis angegeben, wird das Unterverzeichnis im angegebenen Zielverzeichnis erstellt. Andernfalls wird es im aktuellen Verzeichnis erstellt. Beim Herunterladen wird zusätzlich zu den drei Connectordateien eine vierte Datei mit dem Namen settings.json geschrieben. Diese enthält die Parameter, die zum Herunterladen der Dateien verwendet werden.

Laden Sie die benutzerdefinierten Connectordateien mit einem der folgenden Befehle herunter:

paconn download

or

paconn download -e [Power Platform Environment GUID] -c [Connector ID]

or

paconn download -s [Path to settings.json]

Wenn die Umgebungs- oder Connector-ID nicht angegeben wird, fordert die Eingabeaufforderung die fehlenden Argumente an. Durch den Befehl wird der Downloadspeicherort für den Connector ausgegeben, wenn er erfolgreich heruntergeladen wird.

Alle Argumente können auch mithilfe der Datei „settings.json“ angegeben werden.

Arguments
   --cid -c       : The custom connector ID.
   --dest -d      : Destination directory.
   --env -e       : Power Platform environment GUID.
   --overwrite -w : Overwrite all the existing connector and settings files.
   --pau -u       : Power Platform URL.
   --pav -v       : Power Platform API version.
   --settings -s  : A settings file containing required parameters.
                    When a settings file is specified some command 
                    line parameters are ignored.

Einen neuen benutzerdefinierten Connector erstellen

Sie können einen neuen benutzerdefinierten Connector aus den Connector-Dateien erstellen, indem Sie die create Operation ausführen. Erstellen Sie einen Connector, indem Sie einen der folgenden Befehle ausführen:

paconn create --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

or

paconn create -e [Power Platform Environment GUID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

or

paconn create -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Wenn Sie die Umgebung nicht angegeben, wird ihre Eingabeaufforderung angefordert. Jedoch müssen Sie die API-Definitionsdatei und die API-Eigenschaftendatei und die Symboldatei im Befehlszeilenargument oder in einer Einstellungsdatei angegeben. Für einen Connector muss mit OAuth2 das OAuth2-Geheimnis angegeben werden. Der Befehl gibt bei erfolgreichem Abschluss die Connector-ID für den neu erstellten benutzerdefinierten Connector aus. Wenn Sie für den Erstellungsbefehl die Datei settings.json verwenden, müssen Sie diese mit der neuen Connector-ID aktualisieren, bevor Sie den neu erstellten Connector aktualisieren.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Einen vorhandenen benutzerdefinierten Connector aktualisieren

Wie der create Vorgang kann ein vorhandener benutzerdefinierter Connector mit update Vorgang aktualisiert werden. Aktualisieren Sie einen Connector, indem Sie einen der folgenden Befehle ausführen:

paconn update --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

or

paconn update -e [Power Platform Environment GUID] -c [Connector ID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

or

paconn update -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Wenn Sie die Umgebungs- oder Connector-ID nicht angegeben, fordert die Eingabeaufforderung die fehlenden Argumente an. Jedoch müssen Sie die API-Definitionsdatei und die API-Eigenschaftendatei und die Symboldatei im Befehlszeilenargument oder in einer Einstellungsdatei angegeben. Für einen Connector muss mit OAuth2 das OAuth2-Geheimnis angegeben werden. Der Befehl gibt nach erfolgreichem Abschluss die aktualisierte Connector-ID aus. Wenn Sie für den Aktualisierungsbefehl die Datei settings.json verwenden, stellen Sie sicher, dass die richtige Umgebungs- und Connector-ID angegeben werden.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --cid -c      : The custom connector ID.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Eine Swagger-JSON prüfen

Die Validierungsoperation nimmt eine Swagger-Datei und überprüft, ob sie allen empfohlenen Regeln entspricht. Validieren Sie eine Swagger-Datei, indem Sie Folgendes ausführen:

paconn validate --api-def [Path to apiDefinition.swagger.json]

or

paconn validate -s [Path to settings.json]

Der Befehl gibt je nach Ergebnis der Überprüfung die Fehler-, Warn- oder Erfolgsmeldung aus.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Bewährte Methode

Laden Sie alle benutzerdefinierten Connectors herunter, und verwenden Sie Git oder ein anderes Quellcodeverwaltungssystem, 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 Quellcodeverwaltungssystem 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.

Einschränkungen

Das Projekt ist auf die Erstellung, Aktualisierung und den Download eines benutzerdefinierten Konnektors in der Copilot Studio, Power Automate und Power Apps-Umgebung beschränkt. Wenn keine Umgebung angegeben ist, steht nur die Power Automate-Umgebungen zur Auswahl. Für einen nicht benutzerdefinierten Connector wird keine Swagger-Datei zurückgegeben.

Anmerkung

stackOwner Eigenschaft und API Eigenschaftendatei

Derzeit gibt es eine Einschränkung, die Sie daran hindert, die Artefakte Ihres Connectors in Ihrer Umgebung mit Paconn zu aktualisieren, wenn die stackOwner Eigenschaft in Ihrer API Eigenschaften-Datei vorhanden ist. Erstellen Sie zur Problemumgehung zwei Versionen Ihrer Konnektorartefakte:

  • Erstellen Sie eine Version, die die stackOwner Eigenschaft enthält, und reichen Sie sie zur Zertifizierung ein.
  • Erstellen Sie eine zweite Version, die stackOwner weglässt, um es Ihnen zu ermöglichen, Aktualisierungen in Ihrer eigenen Umgebung vorzunehmen.

Wir arbeiten daran, die Einschränkung aufzuheben, und werden diesen Abschnitt aktualisieren, sobald er fertig ist.

Probleme und Feedback melden

Wenn bei dem Tool Fehler auftreten, melden Sie bitte im Bereich Issues (Probleme) des GitHub-Repositorys ein Problem.

Wenn Sie glauben, dass Sie ein Sicherheitsrisiko gefunden haben, das der Microsoft-Definition eines Sicherheitsrisikos entspricht, senden Sie einen Bericht an MSRC. Weitere Informationen finden Sie in den Häufig gestellten Fragen zum Melden von Problemen beim MSRC.

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.