Aggiornamenti e controllo delle versioni
È sempre possibile aggiornare i connettori personalizzati pubblicati tramite certificazione o creati come open source. Il processo di aggiornamento è quasi identico alla pubblicazione iniziale. La differenza principale risiede nel fatto che è necessario considerare gli utenti esistenti quando si pianificano gli aggiornamenti. L'inserimento nella definizione del connettore di modifiche che causano interruzioni, per quanto di entità irrilevante, può interessare gli utenti esistenti.
I trigger e le azioni di un connettore possono aumentare e cambiare nel tempo, man mano che vengono aggiunte o espanse le funzionalità nell'API sottostante. Alcune modifiche sono una semplice aggiunta e non interrompono necessariamente il contratto esistente tra le app e i flussi che usano il connettore. In questa categoria potrebbe rientrare l'aggiunta di nuovi parametri, la restituzione di più dati o l'uso di input più flessibili. Tuttavia, molte modifiche possono causare la risoluzione del contratto descritto nella specifica OpenAPI.
Esempi di modifiche che causano un'interruzione includono:
Rimozione di parametri
Sospensione del supporto di alcuni input
Modifica del significato e del comportamento di un input, di un output o di un'operazione
L'API descritta dal connettore personalizzato deve evitare anche queste modifiche che causano un'interruzione. Nei casi in cui gruppi diversi mantengono la definizione del connettore e l'API, è necessario coordinarle per garantirne la sincronizzazione.
Per sviluppare un connettore personalizzato e un'API in modo sicuro, accertarsi di seguire un modello che può essere esplorato dagli utenti del connettore. È responsabilità del connettore, e di conseguenza dell'API, garantire la compatibilità con le versioni precedenti, comunicare l'intenzione e delineare gli attributi per il controllo delle versioni. Spetta invece al progettista degli strumenti decidere se consentire di usare il connettore per mostrare o nascondere operazioni obsolete, scadute o che potrebbero avere versioni più recenti disponibili. Di conseguenza, le operazioni possono aumentare e svilupparsi nel tempo senza causare un'inutile fragilità alle applicazioni che si basano su di esse.
Annotazione delle azioni del connettore
Con la configurazione OpenAPI è possibile annotare le azioni sul connettore in modo che, quando viene presentato nell'area di progettazione, trasmetta l'uso previsto. Ad esempio, se si aggiunge l'estensione OpenAPI x-ms-api-annotation all'azione GetInvoice, si specifica lo stato di anteprima.
Di conseguenza, quando questa azione viene presentata nella finestra di progettazione flusso cloud di Power Automate, specifica (anteprima) dopo il nome dell'azione.
Nuove versioni di un'azione
Durante il suo ciclo di vita, un'azione potrebbe aver bisogno di un cambiamento radicale. L'approccio migliore è creare una nuova versione dell'azione. Gli utenti dell'azione originale non saranno interessati dalla modifica, ma i nuovi utenti potranno trarre vantaggio dalla nuova versione. Di solito, si indica la versione all'interno del riepilogo.
Ritiro di un'azione
Dopo aver introdotto la nuova azione, è possibile che a un certo punto si decida di deprecare quella precedente in modo che non venga più usata nelle nuove app e nei nuovi flussi. Il primo passaggio è contrassegnare la vecchia azione come avanzata nella sezione Visibilità. Se ci sono azioni contrassegnate come importanti, valutare se contrassegnare anche la nuova azione V2 come importante. Queste modifiche di visibilità incoraggiano l'uso della nuova azione posizionandola più in alto nell'elenco delle azioni.
Nelle aree di riepilogo o descrizione è anche possibile inserire una nota sull'imminente ritiro. È possibile ad esempio sostituire Ottieni fattura con Ottieni fattura (deprecato). Questa modifica annuncia gradualmente il ritiro senza nascondere l'azione agli utenti. L'obiettivo è aiutare gli utenti del connettore ad adattarsi alle modifiche apportate.
Per nascondere l'azione ai nuovi utenti, senza però nasconderla agli utenti esistenti, è possibile contrassegnarla come deprecata nella configurazione OpenAPI. Per apportare questa modifica si può intervenire direttamente sulla definizione OpenAPI tramite l'editor Swagger. Per indicare che un'azione è deprecata, aggiungere il seguente comando alla configurazione dell'operazione:
deprecated: true
Dopo aver pubblicato il connettore, questo comando impedisce agli utenti di selezionarla nei nuovi flussi nascondendola.
Esistono molte ragioni per aderire al controllo delle versioni delle azioni. In primo luogo, si assicura che client come App per la logica e Power Automate continuino a funzionare correttamente quando gli utenti integrano le azioni del connettore nei propri flussi. Il controllo delle versioni delle azioni con i metodi descritti in precedenza è necessario ogni volta che si verifica una delle seguenti condizioni:
Viene aggiunta una nuova revisione di un'azione
Un'azione esistente aggiunge o rimuove parametri
Un'operazione esistente modifica in modo significativo l'input o l'output
Potrebbero verificarsi alcune situazioni in cui è possibile evitare il controllo delle versioni, ma in questi casi occorre prestare la massima attenzione. Eseguire più test per assicurarsi di non aver trascurato i casi limite in cui le app e i flussi degli utenti potrebbero venire interrotti in modo imprevisto.
È possibile (con cautela) evitare il controllo delle versioni nelle circostanze seguenti:
L'aggiunta di una nuova azione.
L'aggiunta di un nuovo parametro facoltativo a un'azione esistente.
Una modifica impercettibile nel comportamento di un'azione esistente.
Prendere le debite precauzioni e creare una revisione quando si apportano modifiche non banali alla definizione del connettore o all'API sottostante.