Skapa ett anpassat anslutningsprogram med CLI

Artikel
04/24/2024

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

Anteckning

Denna Viktiga information beskriver funktioner som kanske inte har frisläppts ännu.
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 (finns i Microsofts policy).

Installera

Installera Python 3.5+ från [https://www.python.org/downloads](Python 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

Om du får felmeddelanden om att "Åtkomst nekas" kan du överväga att använda alternativet --user eller köra kommandot som en administratör (Windows).

Katalog för anpassat anslutningsprogram och filer

Ett anpassat anslutningsprogram består av två till fyra filer: en Open API swagger-definition, en API-egenskapsfil, en valfri ikon för anslutningsprogrammet och en csharp-skriptfil (tillval). 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:t för anpassat anslutningsprogram med hjälp av OpenAPI-specifikationen. Den kallas också för "swagger"-filen. Mer information om API-definitioner som används för att skriva anpassade anslutningsprogram finns i Skapa ett anpassat anslutningsprogram från en OpenAPI-definition. Granska också stjälvstudierna i artikeln Utöka en OpenAPI-definition för ett anpassat anslutningsprogram.

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

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 det anpassde anslutningsprogrammet.
scriptOperations: En lista över de åtgärder som körs med skriptfilen. En tom scriptOperations-lista anger att alla åtgärder körs med skriptfilen.
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 det anpassde anslutningsprogrammet.

Ikonfil

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

Skriptfil

Skriptet är en CSX-skriptfil som har distribuerats för det anpassade anslutningsprogrammet och som körs för varje anrop till en deluppsättning av åtgärderna i 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",
  "script": "script.csx",
  "powerAppsApiVersion": "2016-11-01",
  "powerAppsUrl": "https://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 det anpassde anslutningsprogrammet. Den här parametern krävs för hämtning och uppdatering, men inte för att skapa eller verifiera åtgärden. Ett nytt anpassat anslutningsprogram med det nya ID:t skapas för att skapa kommandot. 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 det anpassde anslutningsprogrammet. Den här parametern krävs för alla åtgärder, förutom valideringsåtgärden.
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, annars sparas den som apiProperties.json.
apiDefinition: Sökvägen till Swagger-filen. Den krävs för åtgärden skapa, uppdatera och validera åtgärder. När det här alternativet finns med under nedladdningen skrivs filen på den angivna platsen över, annars sparas den som apiDefinition.swagger.json.
icon: Sökvägen till den valfria ikonfilen. För åtgärder som skapar och uppdaterar används standardikonen när den här parametern inte anges. När det här alternativet finns med under nedladdningen skrivs filen på den angivna platsen över, annars sparas den som icon.png.
script: Sökvägen till den valfria skriptfilen. För åtgärder som skapar och uppdaterar används bara värden i den angivna parametern. När det här alternativet finns med under nedladdningen skrivs filen på den angivna platsen över, annars sparas den som script.csx.
powerAppsUrl: API-URL för Power Apps. Den här parametern är valfri och anges som standard till https://api.powerapps.com.
powerAppsApiVersion: API-versionen som ska användas för Power Apps. Den här parametern är valfri och anges som standard till 2016-11-01.

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. Autentisering av tjänstprinciper stöds inte för närvarande.

Utloggning

Logga ut genom att köra:

paconn logout

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

Skapa ett nytt anpassat anslutningsprogram

Du kan skapa ett nytt anpassat anslutningsprogram från anslutningsprogramfilerna genom att köra åtgärden create. Skapa ett anslutningsprogram genom att köra:

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

eller

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]

eller

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 och API-egenskaperna måste dock anges som en del av kommandoradsargumentet 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-fil för skapakommandot, bör du se till att uppdatera det med det nya anslutnings-ID:t innan du uppdaterar den nya anslutningen.

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.

Uppdatera ett befintligt anpassat anslutningsprogram

Precis som med åtgärden create kan ett befintligt anpassat anslutningsprogram uppdateras med hjälp av åtgärden update. Uppdatera ett anslutningsprogram genom att köra:

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

eller

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]

eller

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 och API-egenskaperna måste dock anges som en del av kommandoradsargumentet 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-fil för uppdateringskommandot kontrollerar du att rätt miljö- och anslutnings-ID har angetts.

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.

Verifiera en Swagger JSON-fil

Verifieringsåtgärden använder en swagger-fil och kontrollerar om den följer alla rekommenderade regler. Verifiera en swagger-fil genom att köra:

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

eller

paconn validate -s [Path to settings.json]

Kommandot skriver ut felmeddelandet, varningen eller framgångsmeddelandet beroende på resultatet av valideringen.

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.

Bästa metod för

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 anslutningsappen 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 ett anpassat anslutningsprogram 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.

Egenskap för stackägare och filen apiProperties:

För tillfället finns det en begränsning som gör att du inte kan uppdatera anslutningsprogrammets artefakter i miljön med hjälp Paconn när egenskapen stackOwner finns i apiProperties.json-fil. Du kan undvika det här problemet genom att skapa två versioner av anslutningsprogrammets artefakter: Den första är den version som har skickats in till certifieringen och som innehåller egenskapen stackOwner. I den andra ingår inte egenskapen stackOwner vilket gör att det går att uppdatera i miljön. Vi arbetar med att ta bort begränsningen och kommer att uppdatera det här avsnittet när det är klarat.

Rapportera problem och feedback

Om du stöter på några buggar med verktyget kan du skicka ett ärende 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.

Ge feedback

Vi uppskattar feedback på problem med vår plattform för anslutningsprogram eller förslag på nya funktioner. Om du vill lämna feedback går du till Skicka problem eller få hjälp med anslutningsprogram och väljer typ av feedback.

Dela via

Skapa ett anpassat anslutningsprogram med CLI

Installera

Katalog för anpassat anslutningsprogram och filer

API-definitionsfil (Swagger)

API-egenskapsfil

Ikonfil

Skriptfil

Inställningsfil

Kommandoradsåtgärder

Utloggning

Ladda ned filerna för ditt anpassade anslutningsprogram

Skapa ett nytt anpassat anslutningsprogram

Uppdatera ett befintligt anpassat anslutningsprogram

Verifiera en Swagger JSON-fil

Bästa metod för

Begränsningar

Rapportera problem och feedback

Ge feedback

Ytterligare resurser

Dela via

Skapa ett anpassat anslutningsprogram med CLI

Installera

Katalog för anpassat anslutningsprogram och filer

API-definitionsfil (Swagger)

API-egenskapsfil

Ikonfil

Skriptfil

Inställningsfil

Kommandoradsåtgärder

Inloggning

Utloggning

Ladda ned filerna för ditt anpassade anslutningsprogram

Skapa ett nytt anpassat anslutningsprogram

Uppdatera ett befintligt anpassat anslutningsprogram

Verifiera en Swagger JSON-fil

Bästa metod för

Begränsningar

Rapportera problem och feedback

Ge feedback

Ytterligare resurser