Microsoft Power Platform-Connectors-CLI

Artikel
06/23/2023

Hinweis

In diesen Versionshinweisen werden Funktionen beschrieben, die möglicherweise noch nicht veröffentlicht wurden. Informationen zum geplanten Zeitpunkt der Veröffentlichung dieser Funktionen finden Sie unter Neuerungen und geplante Funktionen für Common Data Model und Datenintegration. Die Bereitstellungszeitpunkte und geplanten Funktionen werden möglicherweise geändert, oder Funktionen werden nicht bereitgestellt (gehen Sie zu Microsoft-Richtlinien).

Das Kommandozeilen-Werkzeug paconn soll die Entwicklung von Microsoft Power Platform kundenspezifischen Connectors unterstützen.

Wird installiert...

Installieren Sie Python 3.5 oder höher von [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.
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.
Stellen Sie sicher, dass sich der Installationspfad in der PATH-Variablen befindet, indem Sie folgenden Befehl ausführen:

python --version
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 Option --user in Betracht oder Ausführen des Befehls als Administrator (Windows).

Verzeichnis und Dateien für den benutzerdefiniertes Connector

Ein benutzerdefinierter Konnektor besteht aus zwei bis vier Dateien: einer Open-API-Swagger-Definition, einer API-Eigenschaftendatei, einem optionalen Symbol für den Konnektor und einer optionalen 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, kann 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. Sie wird auch als Swagger-Datei bezeichnet. Weitere Informationen zu API-Definitionen, die zum Schreiben benutzerdefinierter Connectors verwendet werden, 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 Connector. Diese Eigenschaften sind nicht Teil der API-Definition. Sie 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"
        }
      }
    ]    
  }
}

Weitere Informationen zu den einzelnen Eigenschaften finden Sie unten:

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: Beschreibt die Fähigkeiten für den Konnektor, z. B. nur Cloud, On-Prem-Gateway usw.
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 Skript ist eine 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 das folgende 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"
}

In der Einstellungsdatei werden die folgenden Elemente erwartet. 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. Dieser Parameter ist für Download- und Aktualisierungsvorgänge erforderlich, jedoch nicht für den Erstellungs- oder Validierungsvorgang. Für den Erstellungsbefehl wird ein neuer benutzerdefinierter Konnektor mit der neuen ID erstellt. Wenn Sie einen 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. Dieser Parameter ist für alle Vorgänge erforderlich, mit Ausnahme des Validierungsvorgangs.
apiProperties: Der Pfad zu der API-Eigenschaften-Datei apiProperties.json. Er ist für den Erstellungs- und Aktualisierungsvorgang erforderlich. Wenn diese Option während des Downloads vorhanden ist, wird die Datei an den angegebenen Speicherort heruntergeladen; andernfalls wird sie als apiProperties.json gespeichert.
apiDefinition: Der Pfad zur Swagger-Datei. Ist für die Vorgänge Erstellen, Aktualisieren und Validieren erforderlich. Wenn diese Option während des Downloadvorgangs vorhanden ist, wird die Datei an dem angegebenen Ort beschrieben; andernfalls wird sie als apiDefinition.swagger.json gespeichert.
icon: Der Pfad zur optionalen Symboldatei. Die Erstellungs- und Aktualisierungsvorgänge verwenden das Standardsymbol, wenn dieser Parameter nicht angegeben ist. Wenn diese Option während des Downloadvorgangs vorhanden ist, wird die Datei an dem angegebenen Ort beschrieben; andernfalls wird sie als icon.png 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 Downloadvorgangs vorhanden ist, wird die Datei an dem angegebenen Ort beschrieben; andernfalls wird sie als script.csx 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

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

paconn login

Dieser Befehl fordert Sie auf, sich mithilfe des Gerätecodes 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 ein Zielverzeichnis angegeben wird, 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

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

paconn download -s [Path to settings.json]

Wenn die Umgebungs- oder Connector-ID nicht angegeben wird, fordert der Befehl 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

Ein neuer benutzerdefinierter Connector kann aus den Connector-Dateien erstellt werden, 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]

oder

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]

oder

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

Wenn die Umgebung nicht angegeben wird, wird ihre Angabe durch den Befehl angefordert. Jedoch müssen die API-Definitionsdatei und die API-Eigenschaftendatei und die Symboldatei im Befehlszeilenargument oder in einer Einstellungsdatei angegeben werden. 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]

oder

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]

oder

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

Wenn die Umgebungs- oder Connector-ID nicht angegeben wird, fordert der Befehl die fehlenden Argumente an. Jedoch müssen die API-Definitionsdatei und die API-Eigenschaftendatei und die Symboldatei im Befehlszeilenargument oder in einer Einstellungsdatei angegeben werden. 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]

oder

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 Power Automate- und Power Apps-Umgebung beschränkt. Wenn keine Umgebung angegeben ist, stehen nur die Power Automate-Umgebungen zur Auswahl. Für einen nicht benutzerdefinierten Connector wird keine Swagger-Datei zurückgegeben.

Stack Owner Property & apiProperties-Datei:

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 Ihrem apiProperties.json Datei vorhanden ist. Um dies zu umgehen, erstellen Sie zwei Versionen Ihrer Connector-Artefakte: Die erste ist die Version, die zur Zertifizierung eingereicht wird und die stackOwner Eigenschaft enthält. Der zweite hat die stackOwner Eigenschaft weggelassen, um die Aktualisierung in Ihrer Umgebung zu ermöglichen. 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.

Microsoft Power Platform-Connectors-CLI

Wird installiert...

Verzeichnis und Dateien für den benutzerdefiniertes Connector

API-Definitionsdatei (Swagger-Definitionsdatei)

API-Eigenschaftendatei

Symboldatei

Skriptdatei

Einstellungsdatei

Befehlszeilenvorgänge

Anmeldung

Abmelden

Benutzerdefinierte Connectordateien herunterladen

Einen neuen benutzerdefinierten Connector erstellen

Einen vorhandenen benutzerdefinierten Connector aktualisieren

Eine Swagger JSON prüfen

Bewährte Methode

Einschränkungen

Probleme und Feedback melden

Feedback senden

Zusätzliche Ressourcen