Uso dell'interfaccia della riga di comando dei connettori di Microsoft Power Platform
Non tutte le attività in un ciclo di vita del connettore personalizzato possono essere eseguite utilizzando un'interfaccia utente del connettore personalizzato nel portale di creazione. Lo strumento da riga di comando paconn deve essere usato come parte del ciclo di vita del connettore personalizzato per le seguenti attività:
Download di un connettore personalizzato per la modifica e il controllo del codice sorgente dopo averlo creato o modificato usando Maker Portal. Ad esempio, per aggiungere proprietà di connessione personalizzate, è necessario scaricare e modificare i file.
Creazione di un nuovo connettore personalizzato in un ambiente dai singoli file di definizione scaricati. Il connettore creato non è contenuto in una soluzione. Ad esempio, si potrebbe usare questo connettore per creare lo stesso connettore con un ID univoco diverso nello stesso ambiente se si desidera una copia mantenendo intatto l'originale.
Aggiornamento di un connettore esistente. Questo passaggio può essere utilizzato per aggiornare un connettore personalizzato autonomo o contenuto in una soluzione. Ad esempio, è possibile aggiornare un connettore dopo aver modificato le proprietà di connessione.
Convalida del connettore. Questo passaggio è necessario per la certificazione, ma molti degli errori rilevati possono migliorare la qualità di qualsiasi connettore personalizzato.
Assicurarsi che nessuno stia modificando il connettore personalizzato usando contemporaneamente il portale e i file scaricati per evitare di perdere le modifiche. Quando si effettua il caricamento usando lo strumento da riga di comando, non viene verificata la presenza di conflitti e la definizione esistente viene solo sostituita, senza alcun merge.
Installazione dello strumento da riga di comando
Lo strumento da riga di comando paconn richiede Python 3.5 o versione successiva. Python dovrà essere installato per primo, seguito dal comando pip install paconn per installare lo strumento. Sono disponibili istruzioni dettagliate per l'installazione.
Parametri o file delle impostazioni
È possibile configurare le opzioni dello strumento usando i parametri della riga di comando quando si esegue un comando oppure mediante un file settings.json. Specificare un file di impostazioni usando il parametro -settings o -s. Quando si usa il file delle impostazioni, gli altri parametri della riga di comando vengono ignorati.
L'uso del file delle impostazioni può semplificare l'esecuzione ripetuta dei comandi. Quando scarichi un connettore personalizzato, viene creato un file settings.json come parte del download. Lo screenshot seguente mostra un esempio di un file settings.json.
È possibile rivedere l'elenco dettagliato delle impostazioni per maggiori specifiche sui valori di ogni impostazione.
Autenticazione
Per usare un qualsiasi comando paconn, è necessario prima autenticarsi mediante il comando paconn login. Questo comando fornirà un codice e reindirizzerà a https://microsoft.com/devicelogin, dove eseguire l'accesso con il proprio account e specificare tale codice.
Il completamento dell'accesso interattivo stabilirà una sessione che altri comandi paconn useranno. La sessione scadrà dopo un po' di tempo e sarà necessario ristabilirla per continuare a usare lo strumento. È possibile forzare la fine della sessione in qualsiasi momento usando il comando paconn logout.
Poiché per l'autenticazione è necessario un accesso utente interattivo, lo strumento da riga di comando può essere usato con script di automazione con intervento dell'utente, ma non funzionerà in scenari senza intervento dell'utente quali una pipeline di compilazione.
Download
Usare il comando paconn download per scaricare un connettore esistente. Se non si specificano parametri, verrà richiesto di scegliere da un elenco di ambienti e quindi da un elenco di connettori nell'ambiente selezionato.
Usare -e parameter per preselezionare un ambiente specifico e ignorare l'elenco degli ambienti. Il modo più semplice per ottenere un identificatore di ambiente è dall'URL del portale di creazione.
Usando questa opzione, verrà presentata una scelta dei soli connettori in quell'ambiente.
Anziché selezionare un connettore in modo interattivo, è possibile specificare un connettore particolare passando un identificatore del connettore in -c parameter. Il modo più semplice per ottenere l'identificatore del connettore è scaricare il connettore una volta e quindi copiare il valore dal file delle impostazioni.
Di conseguenza, il comando sarebbe simile al seguente esempio:
paconn download -e d80faec4-eb14-4076-9681-9b46b97adbfd -c shared_cr83e-5fcontoso-20invoicing-5f20493607d490e1e0
Questo comando scaricherà i file del connettore senza richieste.
L'altro vantaggio dell'utilizzo degli identificatori è che, a differenza dei numeri d'ordine negli elenchi di selezione, gli identificatori non cambiano quando vengono creati o eliminati ambienti e connettori.
I file scaricati vengono inseriti in una cartella denominata using the connector ID. Se la directory esiste già, il comando avrà esito negativo e sarà necessario rimuovere manualmente la cartella. I file scaricati sono costituiti dai seguenti quattro file:
apiDefinition.swagger.json: questo file di definizione dell'API descrive l'API per il connettore personalizzato usando la specifica OpenAPI.
apiProperties.json: il file delle proprietà dell'API contiene le proprietà per il connettore personalizzato e i modelli di criteri.
Icon.png: il file dell'icona è una piccola immagine che rappresenta l'icona del connettore personalizzato.
settings.json: è possibile usare questo file di impostazioni preconfigurato anziché specificare i parametri per ciascun comando.
Creazione
Il comando paconn create permette di creare un connettore personalizzato nell'ambiente di destinazione usando i file di definizione specificati. La definizione dell'API, le proprietà dell'API e l'icona devono essere specificate dai parametri o da un file di impostazioni. Il comando "create" richiederà tutti gli altri parametri, come l'ID ambiente, se non vengono specificati. L'esempio seguente mostra il comando "create":
paconn create ^
-e [Microsoft 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]
Se il connettore usa OAuth2, è possibile usare il parametro -secret per specificare il valore del segreto client.
Aggiornamento
Il comando paconn update permette di aggiornare un connettore personalizzato esistente nell'ambiente di destinazione usando i file di definizione specificati. La definizione dell'API, le proprietà dell'API e l'icona devono essere specificate dai parametri o da un file di impostazioni. Il comando "update" richiederà tutti gli altri parametri, come l'ID ambiente, se non vengono specificati. L'esempio seguente mostra il comando "update":
paconn update ^
-e [Microsoft 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]
Importante
L'aggiornamento sostituirà la definizione nell'ambiente di destinazione, anche se questa è stata modificata dal momento del download della copia. È importante coordinarsi con chiunque altro stia effettuando aggiornamenti al connettore.
L'interfaccia della riga di comando dei connettori di Microsoft Power Platform è uno strumento essenziale quando si creano connettori personalizzati. Usarla come parte del ciclo di vita per apportare modifiche ai connettori e scaricare copie dei file di definizione del connettore per il controllo del codice sorgente.