Delen via

Een aangepaste connector maken met de CLI

  • Artikel

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

Notitie

Installatie

  1. Installeer Python 3.5+ vanaf [https://www.python.org/downloads](Python 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

    Als u foutberichten krijgt met de melding 'toegang geweigerd', overweeg dan om de optie --user te gebruiken of de opdracht als een beheerder (Windows) uit te voeren.

Map en bestanden voor aangepaste connectoren

Een aangepaste connector bestaat uit twee tot vier bestanden: een Open API-swaggerdefinitie, een API-eigenschappenbestand, een optioneel pictogram voor de connector en een optioneel csharp-scriptbestand. 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. Ga voor meer informatie over API-definities die worden gebruikt om de aangepaste connector te schrijven naar Een aangepaste connector maken op basis van een OpenAPI-definitie. Bekijk ook de zelfstudie in het artikel Een OpenAPI-definitie uitbreiden voor een aangepaste connector.

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",
    "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"
        }
      }
    ]    
  }
}

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.

  • scriptOperations: een lijst met de bewerkingen die met het scriptbestand worden uitgevoerd. Een lege scriptOperations-lijst geeft aan dat alle bewerkingen worden uitgevoerd met het scriptbestand.

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

Scriptbestand

Het script is een CSX-scriptbestand dat wordt geïmplementeerd voor de aangepaste connector en wordt uitgevoerd voor elke aanroep naar een subset van de bewerkingen van de connector.

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",
  "script": "script.csx",
  "powerAppsApiVersion": "2016-11-01",
  "powerAppsUrl": "https://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 updatebewerkingen, maar niet voor de bewerking voor maken of valideren. Er wordt een nieuwe aangepaste connector met de nieuwe id gemaakt voor de maakopdracht. 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 bewerkingen, behalve de valideerbewerking.

  • 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. Anders wordt het opgeslagen als apiProperties.json.

  • apiDefinition: het pad naar het Swagger-bestand. Dit is vereist voor de maak-, bijwerk- en valideerbewerking. Als deze optie tijdens de downloadbewerking aanwezig is, wordt naar het bestand op de opgegeven locatie geschreven. Anders wordt het opgeslagen als apiDefinition.swagger.json.

  • icon: het pad naar het optionele pictogrambestand. De maak- en bijwerkbewerkingen gebruiken het standaardpictogram als deze parameter niet is opgegeven. Als deze optie tijdens de downloadbewerking aanwezig is, wordt naar het bestand op de opgegeven locatie geschreven. Anders wordt het opgeslagen als icon.png.

  • script: het pad naar het optionele scriptbestand. De maak- en bijwerkbewerkingen gebruiken alleen de waarde binnen de opgegeven parameter. Als deze optie tijdens de downloadbewerking aanwezig is, wordt naar het bestand op de opgegeven locatie geschreven. Anders wordt het opgeslagen als script.csx.

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

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

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. Service Principal-verificatie wordt op dit moment niet ondersteund.

Afmelden

Afmelden door het volgende uit te voeren:

paconn logout

Bestanden van aangepaste connectoren 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.
   --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.

Een nieuwe aangepaste connector maken

Een nieuwe aangepaste connector kan worden gemaakt op basis van de connectorbestanden door de bewerking create uit te voeren. Maak een connector door het volgende uit te voeren:

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

of

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]

of

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 en de API-eigenschappen 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 bij een succesvolle voltooiing 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.

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.

Een bestaande aangepaste connector bijwerken

Net als decreate-bewerking kan een bestaande aangepaste connector worden bijgewerkt met behulp van de update-bewerking. 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]

of

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]

of

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 en de API-eigenschappen 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 bij een succesvolle voltooiing de bijgewerkte connector-id afgedrukt. Als u een settings.json-bestand gebruikt voor de bijwerkopdracht, moet u de juiste omgevings- en connector-id opgeven.

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.

Een Swagger-JSON valideren

Bij de valideerbewerking wordt een swagger-bestand gebruikt en wordt gecontroleerd of het aan alle aanbevolen regels voldoet. Valideer een swagger-bestand door het volgende uit te voeren:

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

of

paconn validate -s [Path to settings.json]

Met de opdracht wordt het fout-, waarschuwings- of succesbericht afgedrukt, afhankelijk van het resultaat van de validatie.

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.

Best practice

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.

bestand met stackOwner en apiProperties

Momenteel is er een beperking waardoor u de artefacten van uw connector in uw omgeving niet kunt bijwerken met Paconn wanneer de eigenschap stackOwner aanwezig is in uw apiProperties.json-bestand. Als tijdelijke oplossing hiervoor maakt u twee versies van uw connectorartefacten: de eerste is de versie die is ingediend voor certificering en de eigenschap stackOwner bevat. Bij de tweede is de eigenschap stackOwner weggelaten om updates in uw omgeving mogelijk te maken. We werken eraan om de beperking op te heffen en zullen deze sectie bijwerken zodra deze is voltooid.

Rapportageproblemen en feedback

Als er fouten optreden bij het gebruik van het hulpprogramma, kunt u dit melden via de sectie Issues 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).

Feedback geven

We stellen feedback over problemen met ons connectorplatform of ideeën voor nieuwe functies zeer op prijs. Om feedback te geven, gaat u naar Problemen melden of hulp krijgen met connectoren en selecteer uw feedbacktype.