Microsoft Power PlatformCLI för kopplingar

Artikel
08/31/2021
7 minuter för att läsa

Anteckning

Versionsinformationen beskriver funktioner som kanske inte har släppts än. Om du vill se när den här funktionen planeras att släppas kan du läsa Senaste nytt för Common Data Model och dataintegrering. Tidslinjer för leverans och planerade funktioner kan ändras eller kanske inte levereras (se Microsofts policy).

Kommandoradsverktyget paconn har utformats för att hjälpa till med utveckling av anpassade anslutningsprogram för Microsoft Power Platform.

Installerar

Installera Python 3.5+ från https://www.python.org/downloads. Välj länken ”Ladda ned” för valfri version av Python senare än Python 3.5. För Linux och macOS X följer du motsvarande länk på sidan. Du kan också installera med valfri OS-specifik programpaketshanterare.
Kör installationsprogrammet för att påbörja installationen och se till att markera kryssrutan "Lägg till Python X.X i PATH".
Kontrollera att installationssökvägen finns i variabeln PATH genom att köra:

python --version
När Python har installerats installerar du paconn genom att köra:

pip install paconn

Katalog och filer för anpassat anslutningsprogram

Ett anpassat anslutningsprogram består av tre filer: en ikon för anslutningsprogrammet, en Open API-swaggerdefinition och en API-egenskapsfil. Filerna finns vanligtvis i en katalog med anslutningsprogrammets ID som namn på katalogen.

Ibland kan katalogen för det anpassade anslutningsprogrammet innehålla en settings.json-fil. Även om den här filen inte är en del av definitionen för anslutningsprogrammet, kan den användas som ett argument för CLI.

API-definitionsfil (Swagger)

API-definitionsfilen beskriver API:et för det anpassade anslutningsprogrammet med hjälp av OpenAPI-specifikationen. Den kallas även för Swagger-filen. Mer information om de API-definitioner som används för att skriva anpassade anslutningsprogram finns i dokumentationen om ämnet. Gå även igenom självstudien om att utöka en OpenApi-definition.

API-egenskapsfil

API-egenskapsfilen innehåller vissa egenskaper för det anpassade anslutningsprogrammet. De här egenskaperna är inte en del av API-definitionen. Den innehåller information som varumärkesfärg, autentiseringsinformation och så vidare. En typisk API-egenskapsfil ser ut som det här exemplet:

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

Mer information om var och en av egenskaperna anges nedan:

properties: Behållare för informationen.
connectionParameters: Definierar anslutningsparametern för tjänsten.
iconBrandColor: Ikonens varumärkesfärg i HTML-hexkod för den anpassade kopplingen.
capabilities: Beskriver funktionerna för anslutningen, till exempel endast molnet, lokal gateway och så vidare.
policyTemplateInstances: En valfri lista över instanser och värden för principmallar som används i den anpassade kopplingen.

Ikonfil

Ikonfilen är en liten bild som representerar ikonen för det anpassade anslutningsprogrammet.

Inställningsfil

I stället för att ange argumenten på kommandoraden kan en settings.json-fil användas för att ange dem. En typisk settings.json-fil ser ut som det här exemplet:

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

Följande objekt förväntas i inställningsfilen. Om ett alternativ saknas men är obligatoriskt, uppmanar konsolen att ange den information som saknas.

connectorId: Anslutnings-ID-strängen för den anpassade kopplingen. Den här parametern krävs för nedladdnings- och uppdateringsåtgärder, men inte för åtgärden skapa eftersom ett nytt anpassat anslutningsprogram med det nya ID:t kommer att skapas. Om du behöver uppdatera ett anpassat anslutningsprogram som precis har skapats med samma inställningsfil kontrollerar du att inställningsfilen är korrekt uppdaterad med det nya anslutningsprogram-ID:t från åtgärden skapa.
environment: Miljö-ID-strängen för den anpassade kopplingen. Den här parametern krävs för alla tre åtgärderna.
apiProperties: Sökvägen till filen med API-egenskaperna apiProperties.json. Den krävs för åtgärden skapa och uppdatera. När det här alternativet finns med under nedladdningen laddas filen ned till den angivna platsen.
apiDefinition: Sökvägen till Swagger-filen. Den krävs för åtgärden skapa och uppdatera. När det här alternativet finns med under nedladdningen skrivs informationen till filen på den angivna platsen.
icon: Sökvägen till ikonfilen. Den krävs för åtgärden skapa och uppdatera. När det här alternativet finns med under nedladdningen skrivs informationen till filen på den angivna platsen.
powerAppsApiVersion: API-versionen som ska användas för Power Apps. Detta objekt är valfritt och anges till 2016-11-01 som standard.
powerAppsUrl: API-URL för Power Apps. Detta objekt är valfritt och anges till https://preview.api.powerapps.com som standard.

Kommandoradsåtgärder

Logga in på Power Platform genom att köra:

paconn login

Kommandoraden uppmanar dig att logga in med inloggningsprocessen för enhetskod. Följ anvisningarna för inloggningen.

Ladda ned filerna för ditt anpassade anslutningsprogram

Filer för anslutningsprogram laddas alltid ned till en underkatalog med anslutningsprogram-ID:t som katalognamn. När en målkatalog anges skapas underkatalogen i den angivna katalogen. Annars skapas den i den aktuella katalogen. Förutom de tre filerna för anslutningsprogrammet skriver nedladdningsåtgärden även en fjärde fil med namnet settings.json som innehåller de parametrar som används för att ladda ned filerna.

Ladda ned filerna för det anpassade anslutningsprogrammet genom att köra:

paconn download

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

paconn download -s [Path to settings.json]

När miljö- eller anslutnings-ID:t inte anges kommer kommandot att fråga efter de argument som saknas. Med kommandot visas utdata om nedladdningsplatsen för anslutningsprogrammet om nedladdningen lyckas.

Alla argument kan också anges med hjälp av 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.

Skapa ett nytt anpassat anslutningsprogram

Du kan skapa ett nytt anpassat anslutningsprogram från de tre filerna som introducerades tidigare. Skapa ett anslutningsprogram genom att köra:

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

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]

paconn create -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Om miljön inte anges kommer kommandot att fråga efter den. API-definitionen, API-egenskaperna och ikonfilen måste dock anges som en del av kommandoradsargument eller en inställningsfil. OAuth2-hemligheten måste anges för ett anslutningsprogram med hjälp av OAuth2. Kommandot skriver ut anslutningsprogram-ID:t för det nyligen skapade anpassade anslutningsprogrammet när det har slutförts. Om du använder en settings.json för kommandot skapa, bör du se till att uppdatera det med det nya anslutningsprogram-ID:t innan du uppdaterar det nya anslutningsprogrammet.

Alla argument kan också anges med hjälp av 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.

Uppdatera ett befintligt anpassat anslutningsprogram

Precis som create-åtgärden kan ett befintligt anpassat anslutningsprogram uppdateras från de tre filerna som introducerades tidigare. Uppdatera ett anslutningsprogram genom att köra:

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

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]

paconn update -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

När miljö- eller anslutningsprogram-ID:t inte anges kommer kommandot att fråga efter det/de argument som saknas. API-definitionen, API-egenskaperna och ikonfilen måste dock anges som en del av kommandoradsargument eller en inställningsfil. OAuth2-hemligheten måste anges för ett anslutningsprogram med hjälp av OAuth2. Kommandot skriver ut det uppdaterade anslutningsprogram-ID:t när det slutförts. Om du använder en settings.json för uppdateringskommandot kontrollerar du att rätt miljö- och anslutningsprogram-ID har angetts.

Alla argument kan också anges med hjälp av 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.

Metodtips

Ladda ned alla anpassade anslutningsprogram och använd git eller andra källkontrollsystem för att spara filerna. Om du har en felaktig uppdatering distribuerar du om anslutningsprogrammet genom att köra uppdateringskommandot på nytt med rätt uppsättning filer från källkontrollsystemet.

Testa det anpassade anslutningsprogrammet och inställningsfilen i en testmiljö innan du distribuerar i produktionsmiljön. Kontrollera alltid att miljö- och anslutningsprogram-ID är korrekta.

Begränsningar

Projektet är begränsat till att skapa, uppdatera och ladda ned en anpassad koppling i Power Automate och Power Apps-miljön. Om en miljö inte har angetts visas bara Power Automate-miljöer som alternativ. För icke-anpassade anslutningsprogram returneras inte Swagger-filen.

Rapportera problem och feedback

Om du stöter på några buggar med verktyget kan du rapportera problemet i avsnittet Problem i vår GitHub-databas.

Om du tror att du har hittat ett säkerhetsproblem som uppfyller Microsofts definition av ett säkerhetsproblem kan du skicka rapporten till MSRC. Mer information finns under vanliga frågor och svar om rapportering för MSRC.

Microsoft Power PlatformCLI för kopplingar

Betygsätta din upplevelse

Installerar

Katalog och filer för anpassat anslutningsprogram

API-definitionsfil (Swagger)

API-egenskapsfil

Ikonfil

Inställningsfil

Kommandoradsåtgärder

Inloggning

Ladda ned filerna för ditt anpassade anslutningsprogram

Skapa ett nytt anpassat anslutningsprogram

Uppdatera ett befintligt anpassat anslutningsprogram

Metodtips

Begränsningar

Rapportera problem och feedback