CLI voor Microsoft Power Platform-connectors

Het opdrachtregelprogramma paconn is ontworpen ter ondersteuning van de ontwikkeling van aangepaste connectors voor Microsoft Power Platform.

Installeren

1. Installeer Python 3.5+ vanaf https://www.python.org/downloads. Selecteer de koppeling 'Downloaden' in een versie van Python hoger dan Python 3.5. Volg voor Linux en MacOS X de bijbehorende koppeling op de pagina. U kunt ook installeren met een OS-specifiek pakketbeheer naar keuze.

2. Voer het installatieprogramma uit om de installatie te starten. Zorg ervoor dat u het selectievakje om Python X.X aan PATH toe te voegen inschakelt.

3. Controleer of het installatiepad zich in de PATH-variabele bevindt door het volgende uit te voeren:

   python --version

4. Nadat Python is geïnstalleerd, installeert u paconn door het volgende uit te voeren:

   pip install paconn

Map en bestanden voor aangepaste connectors

Een aangepaste connector bestaat uit drie bestanden: een pictogram voor de connector, een OpenAPI-swaggerdefinitie en een API-eigenschappenbestand. De bestanden bevinden zich in het algemeen in een map met de connector-id als naam van de map.

Soms bevat de map met de aangepaste connector een settings.json-bestand. Hoewel dit bestand geen deel uitmaakt van de definitie van de connector, kan het worden gebruikt als argumentopslagplaats voor de CLI.

Bestand voor de API-definitie (Swagger)

In het API-definitiebestand wordt de API voor de aangepaste connector beschreven met behulp van de OpenAPI-specificatie. Het wordt ook wel het Swagger-bestand genoemd. Meer informatie over de API-definities die zijn gebruikt voor het schrijven van een aangepaste connector, vindt u in de documentatie van de connector over het onderwerp. Raadpleeg ook de zelfstudie over het uitbreiden van een OpenApi-definitie.

Bestand met API-eigenschappen

Het API-eigenschappenbestand bevat enkele eigenschappen voor de aangepaste connector. Deze eigenschappen maken geen deel uit van de API-definitie. Het bevat informatie zoals de merkkleur, verificatiegegevens, enzovoort. Een typisch API-eigenschappenbestand ziet eruit zoals in het volgende voorbeeld:

{
  "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",
    "policyTemplateInstances": [
      {
        "title": "MyPolicy",
        "templateId": "setqueryparameter",
        "parameters": {
            "x-ms-apimTemplateParameter.name": "queryParameterName",
            "x-ms-apimTemplateParameter.value": "queryParameterValue",
            "x-ms-apimTemplateParameter.existsAction": "override"
        }
      }
    ]    
  }
}

Meer informatie over elk van de eigenschappen vindt u hieronder:

• properties: de container voor de informatie.

• connectionParameters: hiermee wordt de verbindingsparameter voor de service gedefinieerd.

• iconBrandColor: de merkkleur van het pictogram in de hexadecimale HTML-code voor de aangepaste connector.

• capabilities: hiermee worden de mogelijkheden voor de connector beschreven, bijvoorbeeld alleen cloud, on-premises gateway, enzovoort.

• policyTemplateInstances: een optionele lijst met beleidssjablooninstanties en -waarden die in de aangepaste connector worden gebruikt.

Pictogrambestand

Het pictogrambestand is een kleine afbeelding die het pictogram van de aangepaste connector voorstelt.

Instellingenbestand

In plaats van de argumenten op te geven op de opdrachtregel kan er een settings.json-bestand worden gebruikt om ze op te geven. Een typisch settings.json-bestand ziet eruit zoals in het volgende voorbeeld:

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

In het instellingenbestand worden de volgende items verwacht. Als een optie ontbreekt maar wel is vereist, wordt om de ontbrekende gegevens gevraagd.

• connectorId: de connector-id-reeks voor de aangepaste connector. Deze parameter is vereist voor download- en bijwerkbewerkingen, maar niet voor de maakbewerking, omdat er een nieuwe aangepaste connector met de nieuwe id wordt gemaakt. Als u een pas gemaakte aangepaste connector wilt bijwerken met behulp van hetzelfde instellingenbestand, controleert u of het instellingenbestand op de juiste wijze is bijgewerkt met de nieuwe connector-id van de maakbewerking.

• environment: de omgevings-id-reeks voor de aangepaste connector. Deze parameter is vereist voor alle drie de bewerkingen.

• apiProperties: het pad naar het bestand apiProperties.json met de API-eigenschappen. Dit is vereist voor de maak- en bijwerkbewerking. Als deze optie tijdens het downloaden aanwezig is, wordt het bestand gedownload naar de opgegeven locatie.

• apiDefinition: het pad naar het Swagger-bestand. Dit is vereist voor de maak- en bijwerkbewerking. Als deze optie tijdens het downloaden aanwezig is, wordt naar het bestand op de opgegeven locatie geschreven.

• icon: het pad naar het pictogrambestand. Dit is vereist voor de maak- en bijwerkbewerking. Als deze optie tijdens het downloaden aanwezig is, wordt naar het bestand op de opgegeven locatie geschreven.

• powerAppsApiVersion: de API-versie om voor Power Apps te gebruiken. Dit item is optioneel en is standaard ingesteld op 2016-11-01.

• powerAppsUrl: de API-URL voor Power Apps. Dit item is optioneel en is standaard ingesteld op https://preview.api.powerapps.com.

Opdrachtregelbewerkingen

Aanmelden

Meld u aan bij Power Platform door het volgende uit te voeren:

paconn login

Deze opdracht vraagt u zich aan te melden met behulp van de aanmeldingsprocedure voor het apparaat. Volg de prompt om u aan te melden.

Bestanden van aangepaste connectors downloaden

De connectorbestanden worden altijd gedownload naar een submap met de connector-id als de mapnaam. Als er een doelmap is opgegeven, wordt de submap in de opgegeven doelmap gemaakt. Anders wordt de submap in de huidige map gemaakt. Naast de drie connectorbestanden wordt er ook een vierde bestand geschreven. Dit bestand heeft de naam settings.json en bevat de parameters waarmee de bestanden worden gedownload.

Download de bestanden van aangepaste connectors door het volgende uit te voeren:

paconn download

or

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

or

paconn download -s [Path to settings.json]

Als de omgevings- of connector-id niet is opgegeven, wordt in de opdracht om de ontbrekende argumenten gevraagd. Met de opdracht wordt bij een geslaagde download de downloadlocatie voor de connector uitgevoerd.

Alle argumenten kunnen ook worden opgegeven met behulp van het bestand settings.json.

Arguments
   --cid -c      : The custom connector ID.
   --dest -d     : Destination directory.
   --env -e      : Power Platform environment GUID.
   --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.

Een nieuwe aangepaste connector maken

Er kan een nieuwe aangepaste connector worden gemaakt met behulp van de drie eerder geïntroduceerde bestanden. Maak een connector door het volgende uit te voeren:

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

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]

Als de omgeving niet wordt opgegeven, wordt er in de opdracht om gevraagd. De API-definitie, de API-eigenschappen en het pictogrambestand moeten echter worden opgegeven als onderdeel van het opdrachtregelargument of een instellingenbestand. Het OAuth2-geheim moet worden opgegeven voor een connector die gebruikmaakt van OAuth2. Met de opdracht wordt, indien voltooid, de connector-id voor de nieuw gemaakte, aangepaste connector afgedrukt. Als u een settings.json-bestand gebruikt voor de maakopdracht, moet u deze bijwerken met de nieuwe connector-id voordat u de nieuw gemaakte connector bijwerkt.

Alle argumenten kunnen ook worden opgegeven met behulp van het bestand settings.json.

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

Een bestaande aangepaste connector bijwerken

Een bestaande aangepaste connector kan net als de create-bewerking worden bijgewerkt met behulp van de drie eerder geïntroduceerde bestanden. Werk een connector bij door het volgende uit te voeren:

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

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]

Als de omgevings- of connector-id niet is opgegeven, wordt in de opdracht om de ontbrekende argumenten gevraagd. De API-definitie, de API-eigenschappen en het pictogrambestand moeten echter worden opgegeven als onderdeel van het opdrachtregelargument of een instellingenbestand. Het OAuth2-geheim moet worden opgegeven voor een connector die gebruikmaakt van OAuth2. Met de opdracht wordt, indien voltooid, de bijgewerkte connector-id afgedrukt. Als u een settings.json-bestand gebruikt voor de bijwerkopdracht, moet u de juiste omgevings- en connector-id opgeven.

Alle argumenten kunnen ook worden opgegeven met behulp van het bestand settings.json.

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

Aanbevolen procedure

Download alle aangepaste connectors en gebruik git of een ander broncodebeheersysteem om de bestanden op te slaan. In het geval van een onjuiste update, implementeert u de connector opnieuw door de bijwerkopdracht opnieuw uit te voeren met de juiste set bestanden van het broncodebeheersysteem.

Test de aangepaste connector en het instellingenbestand in een testomgeving voordat u deze implementeert in de productieomgeving. Controleer altijd of de omgevings- en connector-id juist zijn.

Beperkingen

Het project is beperkt tot het maken, bijwerken en downloaden van een aangepaste connector in de omgeving van Power Automate en Power Apps. Wanneer geen omgeving is opgegeven, worden alleen de Power Automate-omgevingen weergegeven om uit te kiezen. Voor een niet-aangepaste connector wordt het Swagger-bestand niet geretourneerd.

Rapportageproblemen en feedback

Als er fouten optreden bij het gebruik van het hulpprogramma, kunt u dit melden via de sectie Issues (Problemen) van onze GitHub-repo.

Als u van mening bent dat u een beveiligingsprobleem hebt gevonden dat voldoet aan de definitie van een beveiligingsprobleem van Microsoft, kunt u een rapport indienen bij MSRC. Meer informatie vindt u op MSRC frequently asked questions on reporting (Veelgestelde vragen over rapporteren bij MSRC).