Condividi tramite

Interfaccia della riga di comando dei connettori Microsoft Power Platform

  • Articolo

Nota

Queste note sulla versione descrivono funzionalità che potrebbero non essere state ancora rilasciate. Per trovare quando è pianificato il rilascio di queste funzionalità, vedi Novità e pianificazioni per Common Data Model e integrazione dei dati. Le tempistiche di distribuzione e le funzionalità previste potrebbero cambiare o non essere rese disponibili. Vedi i criteri Microsoft.

Lo strumento da riga di comando paconn è progettato per facilitare lo sviluppo di connettori personalizzati di Microsoft Power Platform.

Installazione

  1. Installa Python 3.5 o versione successiva da [https://www.python.org/downloads](Python downloads). Seleziona il collegamento Download in qualsiasi versione di Python superiore a Python 3.5. Per Linux e macOS X, segui il collegamento appropriato nella pagina. È anche possibile eseguire l'installazione usando un gestore di pacchetti a scelta specifico del sistema operativo in uso.

  2. Esegui il programma di installazione e assicurati di selezionare la casella 'Aggiungi Python X.X a PATH'.

  3. Assicurati che il percorso di installazione sia incluso nella variabile PATH eseguendo:

    python --version

  4. Dopo l'installazione di Python, installa paconn eseguendo:

    pip install paconn

    Se ricevi errori che dicono "Accesso negato", prendi in considerazione l'utilizzo dell'opzione --user o l'esecuzione del comando come amministratore (Windows).

Directory e file dei connettori personalizzati

Un connettore personalizzato è costituito da due o quattro file: una definizione swagger Open API, un file delle proprietà API, un'icona facoltativa per il connettore e un file script csharp facoltativo. I file si trovano in genere in una directory con un nome uguale all'ID connettore.

In alcuni casi, la directory del connettore personalizzato può includere un file settings.json. Anche se non fa parte della definizione del connettore, questo file può essere usato come archivio di argomenti per l'interfaccia della riga di comando.

File (Swagger) di definizione dell'API

Il file di definizione dell'API descrive l'API per il connettore personalizzato usando la specifica OpenAPI. È anche noto come file Swagger. Per ulteriori informazioni sulle definizioni API utilizzate per scrivere il connettore personalizzato, vai a Creare un connettore personalizzato da una definizione OpenAPI. Rivedi anche l'esercitazione nell'articolo Estendere una definizione OpenAPI per un connettore personalizzato.

File delle proprietà dell'API

Il file delle proprietà dell'API contiene alcune proprietà per il connettore personalizzato. Queste proprietà non fanno parte della definizione dell'API. Contiene informazioni relative al colore del marchio, all'autenticazione e così via. Un tipico file delle proprietà dell'API ha l'aspetto seguente:

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

Di seguito sono riportate altre informazioni su ogni proprietà:

  • properties: il contenitore per le informazioni.

  • connectionParameters: definisce il parametro di connessione per il servizio.

  • iconBrandColor: il colore del marchio dell'icona in codice esadecimale HTML per il connettore personalizzato.

  • scriptOperations: un elenco delle operazioni eseguite con il file script. Un elenco scriptOperations vuoto indica che tutte le operazioni vengono eseguite con il file script.

  • capabilities: descrive le funzionalità per il connettore, ad esempio solo cloud, gateway locale e così via.

  • policyTemplateInstances: un elenco facoltativo di istanze e valori di modelli di criteri usati nel connettore personalizzato.

File di icona

Il file dell'icona è un'immagine di dimensioni ridotte che rappresenta l'icona del connettore personalizzato.

File script

Lo script è un file script CSX distribuito per il connettore personalizzato ed eseguito per ogni chiamata a un sottoinsieme delle operazioni del connettore.

File di impostazioni

Invece di specificare gli argomenti nella riga di comando, è possibile usare un file settings.json. Un tipico file settings.json ha l'aspetto seguente:

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

Nel file di impostazioni sono previsti gli elementi seguenti. Se un'opzione obbligatoria è mancante, la console richiederà di specificarla.

  • connectorId: la stringa dell'ID del connettore personalizzato. Questo parametro è necessario per le operazioni di download e aggiornamento, ma non per l'operazione di creazione o convalida. Verrà creato un nuovo connettore personalizzato con il nuovo ID per il comando crea. Se è necessario aggiornare un connettore personalizzato appena creato usando lo stesso file di impostazioni, verificare che il file di impostazioni venga aggiornato correttamente con il nuovo ID connettore dall'operazione di creazione.

  • environment: la stringa dell'ID ambiente per il connettore personalizzato. Questo parametro è obbligatorio per tutte le operazioni, ad eccezione dell'operazione di convalida.

  • apiProperties: il percorso del file apiProperties.json delle proprietà dell'API. È obbligatorio per le operazioni di creazione e aggiornamento. Se questa opzione è presente durante il download, il file verrà scaricato nella posizione specificata, in caso contrario viene salvato come apiProperties.json.

  • apiDefinition: il percorso del file Swagger. È obbligatorio per le operazioni di creazione, aggiornamento e convalida. Se questa opzione è presente durante l'operazione download, il file verrà scritto nella posizione specificata, in caso contrario viene salvato come apiDefinition.swagger.json.

  • icon: il percorso del file dell'icona facoltativo. Le operazioni di creazione e aggiornamento utilizzeranno l'icona predefinita quando questo parametro non è specificato. Se questa opzione è presente durante l'operazione download, il file verrà scritto nella posizione specificata, in caso contrario viene salvato come icon.png.

  • script: il percorso del file script facoltativo. Le operazioni di creazione e aggiornamento utilizzeranno solo il valore all'interno del parametro specificato. Se questa opzione è presente durante l'operazione download, il file verrà scritto nella posizione specificata, in caso contrario viene salvato come script.csx.

  • powerAppsUrl: l'URL dell'API per Power Apps. Per impostazione predefinita, questo parametro è facoltativo e impostato su https://api.powerapps.com.

  • powerAppsApiVersion: la versione dell'API da utilizzare per Power Apps. Per impostazione predefinita, questo parametro è facoltativo e impostato su 2016-11-01.

Operazioni da riga di comando

Account di accesso

Accedi a Power Platform eseguendo:

paconn login

Questo comando richiederà di eseguire l'accesso usando la procedura di accesso al codice del dispositivo. Segui le istruzioni per l'accesso. L'autenticazione dell'entità servizio non è supportata a questo punto.

Disconnessione

Esci eseguendo:

paconn logout

Scarica i file del connettore personalizzato

I file del connettore vengono sempre scaricati in una sottodirectory con il nome uguale all'ID connettore. Se si specifica una directory di destinazione, la sottodirectory verrà creata al suo interno. In caso contrario, verrà creata nella directory corrente. Oltre ai tre file del connettore, l'operazione di download scriverà anche un quarto file denominato settings.json che contiene i parametri usati per scaricare i file.

Scarica i file del connettore personalizzato eseguendo:

paconn download

o

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

o

paconn download -s [Path to settings.json]

Se l'ID ambiente o l'ID connettore non viene specificato, il comando chiederà di fornire gli argomenti mancanti. Il comando restituirà la posizione di download del connettore se viene scaricato correttamente.

Tutti gli argomenti possono essere specificati anche usando un file settings.json.

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.

Creare un nuovo connettore personalizzato

È possibile creare un nuovo connettore personalizzato dai file dei connettori eseguendo l'operazione create. Crea un connettore eseguendo:

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

oppure

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]

oppure

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

Se l'ambiente non viene specificato, il comando chiederà di fornirlo. Tuttavia, la definizione dell'API e il file delle proprietà dell'API devono essere forniti come parte dell'argomento della riga di comando o di un file di impostazioni. È necessario fornire il segreto OAuth2 per un connettore usando OAuth2. Al termine dell'operazione, il comando stamperà l'ID del connettore personalizzato appena creato. Se usi un file settings.json per il comando di creazione, assicurati di aggiornarlo con il nuovo ID connettore prima di aggiornare il connettore appena creato.

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.

Aggiornare un connettore personalizzato esistente

Come l'operazione create, un connettore personalizzato esistente può essere aggiornato utilizzando l'operazione update. Aggiorna un connettore eseguendo:

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

oppure

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]

oppure

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

Se l'ID ambiente o l'ID connettore non viene specificato, il comando chiederà di fornire gli argomenti mancanti. Tuttavia, la definizione dell'API e il file delle proprietà dell'API devono essere forniti come parte dell'argomento della riga di comando o di un file di impostazioni. È necessario fornire il segreto OAuth2 per un connettore usando OAuth2. Al termine dell'operazione, il comando stamperà l'ID del connettore aggiornato. Se usi un file settings.json per il comando di aggiornamento, verifica che siano specificati gli ID ambiente e connettore corretti.

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.

Convalidare un JSON Swagger

L'operazione di convalida di un file swagger verifica se segue tutte le regole consigliate. Convalida un file swagger eseguendo:

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

oppure

paconn validate -s [Path to settings.json]

Il comando stamperà il messaggio di errore, avviso o completamento a seconda del risultato della convalida.

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.

Procedure consigliate

Scarica tutti i connettori personalizzati e utilizza git o qualsiasi altro sistema di controllo del codice sorgente per salvare i file. Nel caso di un aggiornamento non corretto, ridistribuisci il connettore eseguendo di nuovo il comando di aggiornamento con il set corretto di file dal sistema di controllo del codice sorgente.

Testa il connettore personalizzato e il file di impostazioni in un ambiente di test prima di eseguire la distribuzione nell'ambiente di produzione. Verifica sempre con attenzione che gli ID ambiente e connettore siano corretti.

Limitazioni

Il progetto si limita alla creazione, all'aggiornamento e al download di un connettore personalizzato negli ambienti di Power Automate e Power Apps. Se non viene specificato un ambiente, l'elenco di opzioni disponibili includerà solo gli ambienti di Power Automate. Per i connettori non personalizzati, il file Swagger non viene restituito.

Proprietà del proprietario stack e file apiProperties:

Attualmente, esiste una limitazione che ti impedisce di aggiornare gli artefatti del connettore nel tuo ambiente utilizzando Paconn quando la proprietà stackOwner è presente nel file apiProperties.json. Come soluzione alternativa, crea due versioni degli artefatti del connettore: la prima è la versione inviata alla certificazione e contiene la proprietà stackOwner. Il secondo ha la proprietà stackOwner omessa per consentire l'aggiornamento all'interno dell'ambiente. Stiamo lavorando per rimuovere la limitazione e aggiorneremo questa sezione una volta completata.

Segnalazione di problemi e commenti

Se si rilevano bug con lo strumento, invia un problema nella sezione Issues del repository GitHub.

Se ritieni di aver riscontrato una vulnerabilità di sicurezza conforme alla definizione di Microsoft di una vulnerabilità di sicurezza, invia la segnalazione a MSRC. Per altre informazioni, vedi le domande frequenti sulle segnalazioni a MSRC.

Inviare commenti

L'invio da parte degli utenti di feedback sui problemi riscontrati con la piattaforma di connettori o di idee su nuove funzionalità è molto apprezzato. Per fornire un feedback, vai a Inviare problemi o ottenere assistenza per i connettori e seleziona il tipo di commenti.