Een aangepaste connector maken met de CLI

Met het paconn opdrachtregelprogramma kunt u aangepaste connectors maken voor Copilot Studio en Power Platform.

Python en paconn installeren

1. Installeer Python 3.5 of hoger vanaf [https://www.python.org/downloads](Python downloads). Selecteer de koppeling Download voor elke versie van Python hoger dan Python 3.5. Voor Linux en macOS volgt u de juiste koppeling op de pagina. U kunt Python ook installeren met behulp van een besturingssysteemspecifieke pakketbeheerder van uw keuze.

2. Voer het installatieprogramma uit om de installatie te starten en schakel het selectievakje Python X.X toevoegen aan PATH in.

3. Zorg ervoor dat het installatiepad zich in de PATH variable 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 foutmeldingen krijgt met de melding Toegang geweigerd, kunt u overwegen de optie --user te gebruiken of de opdracht uit te voeren als beheerder (Windows).

Directory en bestanden voor aangepaste connectoren

Een aangepaste connector bestaat uit twee tot vier bestanden:

• een Open API- of Swagger-definitie
• een API-eigenschappenbestand
• een optioneel pictogram voor de connector
• een optioneel C#-scriptbestand

U vindt de bestanden in een map die de connector-id als naam gebruikt.

Soms bevat de aangepaste connectormap een settings.json bestand. Hoewel dit bestand geen deel uitmaakt van de definitie van de connector, kunt u dit als opslag voor argumenten voor de CLI gebruiken.

API-definitionbestand (Swagger)

In het API-definitiebestand wordt de API voor de aangepaste connector beschreven met behulp van de OpenAPI-specificatie. Deze specificatie wordt ook wel het Swagger-bestand genoemd. Zie Een aangepaste connector maken op basis van een OpenAPI-definitie voor meer informatie over hoe een API-definitiebestand u helpt bij het maken van een aangepaste connector. Bekijk ook de zelfstudie in het artikel Een OpenAPI-definitie uitbreiden voor een aangepaste connector.

API-eigenschappenbestand

Het API-eigenschappenbestand bevat eigenschappen voor de aangepaste connector die geen deel uitmaken van de API-definitie. Het bevat informatie zoals de merkkleur en verificatiegegevens. 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"
        }
      }
    ]    
  }
}

Hier vindt u meer informatie over elk kenmerk:

• properties: De container voor de informatie.

• connectionParameters: Definieert de verbindingsparameter voor de service.

• iconBrandColor: De merkkleur van het icoon in HTML-hex-code voor de aangepaste connector.

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

• capabilities: Beschrijving van de mogelijkheden van de connector, zoals alleen in de cloud en on-premises gateway.

• policyTemplateInstances: Een optionele lijst met beleidssjablooninstanties en waarden die door de aangepaste connector worden gebruikt.

Icoonbestand

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

Scriptbestand

Het CSX-scriptbestand (Visual C# Script) wordt uitgerold voor de aangepaste connector en uitgevoerd voor elke aanroep van een subset van de bewerkingen van de connector.

Instellingenbestand

In plaats van de argumenten op te geven in de opdrachtregel, gebruikt u een settings.json bestand om deze op te geven. Een typisch settings.json bestand ziet er als volgt uit:

{
  "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"
}

Deze items kunt u in het instellingenbestand verwachten. Als een optie ontbreekt maar wel vereist is, vraagt de console om de ontbrekende informatie.

• connectorId: De connector-ID-tekenreeks voor de aangepaste connector. Download- en updatebewerkingen vereisen de parameter connector-id, terwijl de bewerkingen voor maken en valideren de parameter connector-id niet vereisen. Met de opdracht create maakt u een nieuwe aangepaste connector met een nieuwe ID. Als u een bestaande aangepaste connector wilt bijwerken met hetzelfde instellingenbestand, moet u ervoor zorgen dat u het instellingenbestand bijwerkt met de nieuwe connector-id van de maakactie.

• environment: De omgevings-ID-tekenreeks voor de aangepaste connector. Voor alle bewerkingen is deze parameter vereist, behalve de validatiebewerking.

• apiProperties: Het pad naar het API-eigenschappenbestand. Create- en update-bewerkingen vereisen het API-eigenschappenbestand. Als deze optie aanwezig is tijdens het downloaden, wordt het bestand naar de locatie ervan gedownload. Anders wordt het bestand opgeslagen als apiProperties.json.

• apiDefinition: Het pad naar het Swagger-bestand. Voor de bewerkingen create, update en validate zijn het API-definitiebestand vereist. Als deze optie aanwezig is tijdens het downloaden, wordt het bestand gedownload op de oorspronkelijke locatie. Anders wordt het bestand opgeslagen als apiDefinition.swagger.json.

• icon: Het pad naar het optionele pictogrambestand. Als er geen specificatie voor deze parameter is, gebruiken de bewerkingen maken en bijwerken het standaardpictogram. Als deze optie aanwezig is tijdens het downloaden, wordt het bestand naar de oorspronkelijke locatie gedownload. Anders wordt het bestand opgeslagen als icon.png.

• script: Het pad naar het optionele scriptbestand. De create en update bewerkingen gebruiken alleen de waarde binnen de opgegeven parameter. Als deze optie aanwezig is tijdens het downloaden, wordt het bestand naar de locatie ervan gedownload. Anders wordt het bestand opgeslagen als script.csx.

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

• powerAppsApiVersion: De API-versie die moet worden gebruikt voor Power Apps. Deze parameter is optioneel en standaard ingesteld op 2016-11-01 .

Bewerkingen op de opdrachtregel

Aanmelden

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

paconn login

Met deze opdracht wordt u gevraagd u aan te melden met behulp van het verificatieproces voor apparaatcode. Volg de prompt voor verificatie. Dit commando biedt geen ondersteuning voor authenticatie van service-principals.

Afmelden

Afmelden door het volgende uit te voeren:

paconn logout

Bestanden van aangepaste connectoren downloaden

Download de connectorbestanden altijd naar een submap met de connector-ID als mapnaam. Wanneer u een doelmap opgeeft, wordt deze map de bovenliggende map voor de nieuwe submap. Als u geen doelmap opgeeft, wordt de submap gemaakt in de huidige map. Naast de drie connectorbestanden maakt de downloadbewerking een vierde bestand genaamd settings.json dat de parameters bevat die worden gebruikt om de bestanden te downloaden.

Download de bestanden voor 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 u de omgevings- of connector-id niet opgeeft, wordt u door de opdracht gevraagd om de ontbrekende argumenten. Als het downloaden slaagt, geeft de opdracht de downloadlocatie voor de connector weer.

U kunt ook alle argumenten opgeven met behulp van een settings.json-bestand.

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

U kunt een nieuwe aangepaste connector maken 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]

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 u de omgeving niet opgeeft, vraagt de opdrachtregel hiernaar. U moet echter de API-definitie en het API-eigenschappenbestand opgeven als onderdeel van het opdrachtregelargument of een instellingenbestand. Geef het OAuth2-geheim voor een connector op met behulp van OAuth2. Met deze opdracht wordt bij succesvolle voltooiing de connector-ID voor de nieuw gemaakte aangepaste connector afgedrukt. Als u een settings.json bestand voor de opdracht maken gebruikt, moet u dit bijwerken met de nieuwe connector-id voordat u de zojuist 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 bij de create bewerking kunt u een bestaande aangepaste connector bijwerken 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]

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 u de omgevings- of connector-ID niet opgeeft, vraagt de opdracht om de ontbrekende argumenten. U moet echter de API-definitie en het API-eigenschappenbestand opgeven als onderdeel van het opdrachtregelargument of een instellingenbestand. Geef het OAuth2-geheim voor een connector op met behulp van OAuth2. Met dit commando wordt de bijgewerkte connector-ID afgedrukt als de bewerking succesvol is voltooid. Als u een settings.json bestand gebruikt voor de updateopdracht, moet u ervoor zorgen dat u de juiste omgeving en connector-id opgeeft.

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

De validatiebewerking neemt een swagger-bestand en controleert of het alle aanbevolen regels volgt. Valideer een swagger-bestand door het volgende uit te voeren:

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

or

paconn validate -s [Path to settings.json]

Afhankelijk van het resultaat van de validatie geeft de opdracht een fout-, waarschuwings- of succesbericht weer.

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.

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, rolt u de connector opnieuw uit 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

De paconn CLI is beperkt tot het maken, bijwerken en downloaden van een aangepaste connector in Copilot Studio, Power Automate en Power Apps omgevingen. Wanneer u geen omgeving opgeeft, hebt u alleen de optie om een Power Automate-omgeving te selecteren. Voor een niet-aangepaste connector wordt het Swagger-bestand niet geretourneerd.

Problemen melden en feedback

Als u bugs in de tool tegenkomt, kunt u een probleem melden in de sectie Issues van onze GitHub-repository.

Als u denkt dat u een beveiligingsprobleem hebt gevonden dat voldoet aan de definitie van een beveiligingsprobleem van Microsoft, dient u een rapport in bij MSRC. Zie MSRC-veelgestelde vragen over rapportage voor meer informatie.

Feedback geven

We stellen feedback over problemen met ons connectorplatform of ideeën voor nieuwe functies zeer op prijs. Als u feedback wilt geven, gaat u naar Problemen indienen of hulp krijgen met connectoren en selecteert u het type feedback.