Creare un connettore personalizzato con l'interfaccia della riga di comando

Lo strumento della riga di comando paconn è progettato per facilitare la creazione di connettori personalizzati per Copilot Studio e Power Platform.

Nota

Questa funzionalità potrebbe non essere ancora stata rilasciata.
Per informazioni sul rilascio, 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.

Installa

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.
Esegui il programma di installazione e assicurati di selezionare la casella Aggiungi Python X.X a PATH.
Assicurati che il percorso di installazione sia incluso nella variabile PATH eseguendo:

python --version
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 a quattro file:

una definizione Open API/swagger
un file delle proprietà dell'API
Un'icona facoltativa per il connettore
file di script csharp facoltativo

I file si trovano in una directory con un nome uguale all'ID connettore.

In alcuni casi, la directory del connettore personalizzato include 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, conosciuta anche come file swagger. Per ulteriori informazioni su come il file delle definizioni API consente di creare un 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 che non fanno parte della definizione dell'API. Il file delle proprietà 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 ulteriori informazioni su ciascuna delle 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: descrizione delle funzionalità del connettore. Ad esempio, gateway solo cloud e locale.
policyTemplateInstances: un elenco facoltativo di istanze e valori di modelli di criteri usati nel connettore personalizzato.

File icona

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

File script

Lo script è un file script Visual C# (CSX) che distribuisce il connettore personalizzato e viene 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"
}

Aspettati questi elementi nel file delle impostazioni. Se un'opzione obbligatoria è mancante, la console richiederà di specificarla.

connectorId: la stringa dell'ID del connettore personalizzato. Il parametro ID connettore è richiesto per le operazioni di download e aggiornamento mentre non è richiesto per le operazioni di creazione e convalida. Il comando Crea crea un nuovo connettore personalizzato con un nuovo ID. Se è necessario aggiornare un connettore personalizzato esistente usando lo stesso file di impostazioni, verifica di aver aggiornato il file di impostazioni 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 delle proprietà dell'API. Le operazioni di creazione e aggiornamento richiedono il file delle proprietà dell'API. Se questa opzione è presente durante il download, il file viene scaricato nella posizione specificata, in caso contrario viene salvato come apiProperties.json.
apiDefinition: il percorso del file Swagger. Per le operazioni di creazione, aggiornamento e convalida il file delle definizioni API è necessario. Se questa opzione è presente durante l'operazione di download, il file viene scaricato 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 di download, il file viene scaricato 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 di download, il file viene scaricato 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

Accedi a Power Platform eseguendo:

paconn login

Il comando richiede di accedere usando il processo di accesso con codice dispositivo. Segui le istruzioni per l'accesso. L'autenticazione dell'entità servizio non è supportata a questo punto.

Disconnessione

Esci eseguendo:

paconn logout

Scaricare i file del connettore personalizzato

Scarica sempre i file del connettore in una sottodirectory con il nome uguale all'ID connettore. Se specifichi una directory di destinazione, verrà creata la directory secondaria 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

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

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

Puoi 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]

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]

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. Fornisci il segreto OAuth2 per un connettore usando OAuth2. Al termine dell'operazione, il comando stamperà l'ID del connettore personalizzato appena creato. Se stai utilizzando 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]

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]

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

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 Copilot Studio, Power Automate e Power Apps. Se non viene specificato un ambiente, puoi solo selezionare un ambiente Power Automate. Per i connettori non personalizzati, il file Swagger non viene restituito.

Nota

Proprietà stackOwner e file delle proprietà API

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 delle proprietà API. Per ovviare a questo problema, creare due versioni degli artefatti del connettore:

Crea una versione che contenga la proprietà stackOwner e inviala per la certificazione.
Crea una seconda versione che ometta stackOwner per consentire di effettuare aggiornamenti nel tuo 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.

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

Last updated on 2025-06-25

Condividi tramite