Een aangepaste connector maken met de CLI

De opdrachtregeltool is ontworpen om te helpen bij het maken van aangepaste connectoren voor paconn en Copilot Studio . Power Platform

Installatie

1. Installeer Python 3.5+ vanaf [https://www.python.org/downloads](Python downloads). Selecteer de Download link op elke 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 en zorg ervoor dat u het vakje Voeg Python X.X toe aan PATH aanvinkt.

3. Zorg ervoor dat het installatiepad zich in de PATH-variabele bevindt door het volgende uit te voeren:

   python --version

4. Nadat Python is geïnstalleerd, voer je het volgende uit: paconn

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

Map en bestanden voor aangepaste connectoren

Een aangepaste connector bestaat uit twee tot vier bestanden:

• een Open API/swagger-definitie
• een API-eigenschappenbestand
• een optioneel pictogram voor de connector
• optioneel csharp-scriptbestand

De bestanden bevinden zich in een map met de connector-ID als naam van de map.

Soms bevat de aangepaste connectormap een settings.json bestand. Hoewel dit bestand geen deel uitmaakt van de connectordefinitie, kunt u het gebruiken als argumentenopslag voor de CLI.

Bestand voor de API-definitie (Swagger)

Het API-definitiebestand beschrijft de API voor de aangepaste connector met behulp van de OpenAPI -specificatie, ook wel het Swagger-bestand genoemd. Ga naar 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 tutorial in het artikel Een OpenAPI definitie voor een aangepaste connector uitbreiden .

Bestand met API-eigenschappen

Het API-eigenschappenbestand bevat een aantal eigenschappen voor de aangepaste connector die geen deel uitmaken van de API-definitie. Het API-eigenschappenbestand bevat informatie zoals de merknaamkleur, authenticatiegegevens, 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"
        }
      }
    ]    
  }
}

Hier vindt u meer informatie over elk van de eigenschappen:

• properties: De container voor de informatie.

• connectionParameters: Definieert de verbindingsparameter voor de service.

• iconBrandColor: De merkkleur van het pictogram in HTML hex-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: Beschrijving van de mogelijkheden van de connector. Bijvoorbeeld alleen in de cloud en on-premise gateway.

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

Pictogrambestand

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

Scriptbestand

Het CSX-scriptbestand (Visual C# Script) wordt geïmplementeerd 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 de opdrachtregel op te geven, kunt u ook een settings.json bestand gebruiken om ze 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. Voor de bewerkingen downloaden en updaten is de connector-ID-parameter vereist, terwijl dit niet het geval is voor de bewerkingen maken en valideren. Met de opdracht create maakt u een nieuwe aangepaste connector met een nieuwe ID. Als u een bestaande aangepaste connector moet bijwerken met hetzelfde instellingenbestand, zorg er dan voor dat u het instellingenbestand bijwerkt met de nieuwe connector-ID uit de aanmaakbewerking.

• 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. Voor en update bewerkingen is het API-eigenschappenbestand vereist. Als deze optie aanwezig is tijdens het downloaden, wordt het bestand naar de gewenste locatie gedownload. Anders wordt het bestand opgeslagen als apiProperties.json.

• apiDefinition: Het pad naar het Swagger-bestand. Voor de bewerkingen create, update en validate is het API-definitiebestand vereist. Als deze optie aanwezig is tijdens het downloaden, wordt het bestand gedownload naar de locatie waar het zich bevindt. 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 create - en update -bewerkingen het standaardpictogram. Als deze optie aanwezig is tijdens het downloaden, wordt het bestand gedownload naar de locatie waar het zich bevindt. 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 gewenste locatie 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 .

Opdrachtregelbewerkingen

Aanmelden

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

paconn login

Met deze opdracht wordt u gevraagd om u aan te melden via het apparaatcode-aanmeldproces. Volg de prompt om u aan te melden. Op dit moment is er geen ondersteuning voor Service Principle-authenticatie.

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 er een submap in de opgegeven map gemaakt. Anders wordt het in de huidige map gemaakt. Naast de drie connectorbestanden schrijft de downloadbewerking ook een vierde bestand met de naam settings.json . Dit bestand bevat de parameters die worden gebruikt om de bestanden te downloaden.

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, vraagt de opdracht om de ontbrekende argumenten. De opdracht geeft de downloadlocatie voor de connector weer als deze succesvol is gedownload.

Alle argumenten kunnen ook worden opgegeven 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 vanuit 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 opdracht hiernaar. U moet echter de API-definitie en het API-eigenschappenbestand opgeven als onderdeel van het opdrachtregelargument of een instellingenbestand. Geef het OAuth2-geheim op voor een connector die OAuth2 gebruikt. Met deze opdracht wordt bij succesvolle voltooiing de connector-ID voor de nieuw gemaakte aangepaste connector afgedrukt. Als u een settings.json bestand gebruikt voor de aanmaakopdracht, zorg er dan voor dat u dit bijwerkt 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 met de bewerking create kunt u een bestaande aangepaste connector bijwerken met de bewerking update . 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 op voor een connector die OAuth2 gebruikt. Met deze opdracht wordt de bijgewerkte connector-ID afgedrukt als de bewerking succesvol is voltooid. Als u een settings.json bestand gebruikt voor de update-opdracht, zorg er dan voor 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

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]

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.

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 Copilot Studio-, Power Automate - en Power Apps -omgevingen. Wanneer er geen omgeving is opgegeven, kunt u alleen een Power Automate omgeving selecteren. Voor een niet-aangepaste connector wordt het Swagger-bestand niet geretourneerd.

Rapportageproblemen en feedback

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

Als u denkt dat u een beveiligingslek hebt gevonden dat voldoet aan de Microsoft-definitie van een beveiligingslek, dient u een rapport in bij MSRC. Meer informatie vindt u op MSRC veelgestelde vragen over rapportage.

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.