Microsoft Power PlatformCLI-adresse til connectorer

  • Artikel
  • 7 minutter til læsning

Bemærk

Disse produktbemærkninger indeholder beskrivelser af funktionalitet, som muligvis ikke er frigivet endnu. Hvis du vil se, hvornår denne funktionalitet er planlagt til at blive frigivet, skal du se Nyheder og planlagte funktioner for Common Data Model og Data Integration. Tidslinjer for levering og forventet funktionalitet kan ændres eller leveres måske ikke (se Microsofts politik).

Kommandolinjeværktøjet paconn er designet som hjælp til udvikling af brugerdefinerede connectorer til Microsoft Power Platform.

Installerer

  1. Installer Python 3.5+ fra https://www.python.org/downloads. Vælg linket "Download" i en hvilken som helst version af Python, der er nyere end Python 3.5. For Linux og macOS X skal du følge det relevante link på siden. Du kan også installere ved hjælp af en OS-specifik pakkeadministrator efter eget valg.

  2. Kør installationsprogrammet for at begynde installationen, og sørg for at markere afkrydsningsfeltet "Føj Python X.X til PATH".

  3. Sørg for, at installationsstien er i variablen PATH, ved at køre:

    python --version

  4. Når Python er installeret, skal du installere paconn ved at køre:

    pip install paconn

Brugerdefineret connector-mappe og -filer

En brugerdefineret connector består af tre filer: et ikon for connectoren, en Swagger-definition med OpenAPI og en fil med API-egenskaber. Generelt placeres filerne i en mappe, hvor connector-id'et er navnet på mappen.

Nogle gange kan den brugerdefinerede connector-mappe indeholde en settings.json-fil. Selvom denne fil ikke er en del af connectordefinitionen, kan den bruges som et argumentlager til CLI.

API-definitionsfil (Swagger)

API-definitionsfilen indeholder beskrivelsen af API'en for den brugerdefinerede connector, der bruger OpenAPI-specifikationen. Den kaldes også for Swagger-filen. Du kan finde flere oplysninger om API-definitioner, der bruges til at skrive brugerdefinerede connectorer, i dokumentationen til connectorer om emnet. Du kan også gennemgå selvstudiet om udvidelse af en OpenApi-definition.

Fil med API-egenskaber

Filen med API-egenskaber indeholder nogle egenskaber for den brugerdefinerede connector. Disse egenskaber er ikke en del af API-definitionen. Den indeholder oplysninger som farven på mærket, godkendelsesoplysninger osv. En typisk fil med API-egenskaber ser ud som følgende eksempel:

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

Der er flere oplysninger om de enkelte egenskaber nedenfor:

  • properties: Objektbeholderen for oplysningerne.

  • connectionParameters: Definerer forbindelsesparameteren for tjenesten.

  • iconBrandColor: Ikonfarven på mærket i HTML-heksadecimal kode for den brugerdefinerede connector.

  • capabilities: Beskriver egenskaberne for connectoren, f.eks. kun cloud, gateway i det lokale miljø osv.

  • policyTemplateInstances: En valgfri liste over instanser og værdier for politikskabeloner, der bruges i den brugerdefinerede connector.

Ikonfil

Ikonfilen er et lille billede, der repræsenterer ikonet for den brugerdefinerede connector.

Indstillingsfil

I stedet for at angive argumenterne på kommandolinjen kan der bruges en fil af typen settings.json til at angive dem. En typisk settings.json-fil ser ud som følgende eksempel:

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

I indstillingsfilen forventes følgende elementer. Hvis der mangler en indstilling, men den kræves, bliver du bedt om at angive de manglende oplysninger i konsollen.

  • connectorId: Strengen for connector-id'et for den brugerdefinerede connector. Denne parameter kræves til download- og opdateringshandlinger, men ikke til oprettelseshandlingen, da der oprettes en ny brugerdefineret connector med det nye id. Hvis du har brug for at opdatere en brugerdefineret connector, der lige er oprettet ved hjælp af den samme indstillingsfil, skal du sørge for, at indstillingsfilen opdateres korrekt med det nye connector-id fra oprettelseshandlingen.

  • environment: Strengen for miljø-id'et for den brugerdefinerede connector. Denne parameter kræves til alle tre handlinger.

  • apiProperties: Stien til filen apiProperties.json med API-egenskaberne. Den kræves til oprettelses- og opdateringshandlingen. Når denne indstilling er til stede under download, downloades filen til den angivne placering.

  • apiDefinition: Stien til Swagger-filen. Den kræves til oprettelses- og opdateringshandlingen. Når denne indstilling er til stede under download, skrives filen til den angivne placering.

  • icon: Stien til ikonfilen. Den kræves til oprettelses- og opdateringshandlingen. Når denne indstilling er til stede under download, skrives filen til den angivne placering.

  • powerAppsApiVersion: Den API-version, der skal bruges til Power Apps. Dette element er valgfrit og angivet til 2016-11-01 som standard.

  • powerAppsUrl: API-URL-adressen til Power Apps. Dette element er valgfrit og angivet til https://preview.api.powerapps.com som standard.

Kommandolinjehandlinger

Logon

Log på Power Platform ved at køre:

paconn login

Du bliver bedt om at logge på ved hjælp af logonprocessen med enhedskoden. Følg logonprompten.

Download brugerdefinerede connectorfiler

Connectorfilerne downloades altid til en undermappe, hvor connector-id'et er navnet på mappen. Når der er angivet en destinationsmappe, oprettes undermappen i den angivne mappe. Ellers oprettes den i den aktuelle mappe. Ud over de tre connectorfiler skrives der også en fjerde fil med navnet setting.json i forbindelse med downloadhandlingen, som indeholder de parametre, der bruges til at downloade filerne.

Download de brugerdefinerede connectorfiler ved at køre:

paconn download

or

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

or

paconn download -s [Path to settings.json]

Når miljø- eller connector-id'et ikke er angivet, bliver du af kommandoen bedt om det eller de manglende argumenter. Kommandoen viser downloadplaceringen for connectoren, hvis den downloades korrekt.

Alle argumenterne kan også angives ved hjælp af en settings.json-fil.

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.

Opret en ny brugerdefineret connector

Der kan oprettes en ny brugerdefineret connector ud fra de tre filer, der blev introduceret tidligere. Opret en connector ved at køre:

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]

Når miljøet ikke er angivet, bliver du bedt om det af kommandoen. API-definitionen, API-egenskaberne og ikonfilen skal dog angives som en del af kommandolinjeargumentet eller en indstillingsfil. OAuth2-hemmeligheden skal være angivet for en connector, der bruger OAuth2. Kommandoen udskriver connector-id'et for den nyligt oprettede brugerdefinerede connector, når den er oprettet korrekt. Hvis du bruger en settings.json til at oprette kommandoen, skal du sørge for at opdatere den med det nye connector-id, før du opdaterer den nyligt oprettede connector.

Alle argumenterne kan også angives ved hjælp af en settings.json-fil.

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.

Opdater en eksisterende brugerdefineret connector

Ligesom med handlingen create kan en eksisterende brugerdefineret connector opdateres ud fra de tre filer, der blev introduceret tidligere. Opdater en connector ved at køre:

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]

Når miljø- eller connector-id'et ikke er angivet, bliver du af kommandoen bedt om det eller de manglende argumenter. API-definitionen, API-egenskaberne og ikonfilen skal dog angives som en del af kommandolinjeargumentet eller en indstillingsfil. OAuth2-hemmeligheden skal være angivet for en connector, der bruger OAuth2. Kommandoen udskriver det opdaterede connector-id, når den er oprettet. Hvis du bruger en settings.json til den opdaterede kommando, skal du sørge for, at det korrekte miljø- og connector-id angives.

Alle argumenterne kan også angives ved hjælp af en settings.json-fil.

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.

Bedste praksis

Download alle de brugerdefinerede connectors, og brug Git eller et andet kildekontrolsystem til at gemme filerne. I tilfælde af en forkert opdatering skal du udrulle connectoren igen ved at køre opdateringskommandoen igen med det korrekte sæt filer fra kildekontrolsystemet.

Test den brugerdefinerede connector og indstillingsfilen i et testmiljø, før du udruller i produktionsmiljøet. Dobbelttjek altid, at miljø- og connector-id'et er korrekt.

Begrænsninger

Projektet er begrænset til oprettelse, opdatering og download af en brugerdefineret connector i Power Automate- og Power Apps-miljøet. Når der ikke er angivet et miljø, er det kun Power Automate-miljøerne, der vises på listen, og som du kan vælge imellem. For en connector, der ikke er brugerdefineret, returneres Swagger-filen ikke.

Rapportering om problemer og feedback

Hvis du oplever fejl med værktøjet, kan du oprette et problem under afsnittet Problemer i vores GitHub-lager.

Hvis du mener, at du har fundet en sikkerhedsrisiko, der opfylder Microsofts definition af en sikkerhedsrisiko, skal du sende en rapport til MSRC. Du kan finde flere oplysninger under Ofte stillede spørgsmål om rapportering i MSRC.