Aggiornamenti e controllo delle versioni
I connettori personalizzati usati dalle app possono essere ancora aggiornati. Il processo di aggiornamento è quasi identico al rilascio della versione iniziale. La differenza principale è che è necessario considerare l'impatto sugli utenti esistenti del connettore durante la pianificazione degli aggiornamenti. Interrompere le modifiche alla definizione del connettore, anche se secondarie, può influire sugli 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, alcune modifiche potrebbero interrompere il contratto descritto nella definizione del connettore personalizzato perché usano la 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, è necessario 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. La progettazione dello strumento consente di usare il connettore per mostrare o nascondere operazioni obsolete, scadute o che potrebbero avere versioni più recenti disponibili. In questo modo, 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
Usando la configurazione OpenAPI, è possibile annotare le azioni sul connettore in modo che trasmetta l'uso previsto quando viene presentato nell'area di progettazione. Ad esempio, aggiungendo 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
Prima o poi ci si potrebbe accorgere che un'azione necessita 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. Lo screenshot seguente mostra l'approccio descritto.
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 flussi. Il primo passaggio è contrassegnare la vecchia azione come avanzata. Se ci sono azioni contrassegnate come importanti, valutare se contrassegnare anche la nuova azione V2 come importante. Queste modifiche di visibilità incoraggeranno 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 la seguente logica alla configurazione dell'operazione:
deprecated: true
Una volta pubblicata l'azione, questo approccio impedisce agli utenti di selezionarla nei nuovi flussi nascondendola.
Esistono molte ragioni per aderire al controllo delle versioni delle azioni. In primo luogo, assicura che client come App per la logica di Microsoft Azure 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
In alcune situazioni è possibile evitare il controllo delle versioni, ma è necessario esercitare cautela ed eseguire numerosi test per assicurarsi di non aver trascurato i casi limite in cui le app e i flussi degli utenti potrebbero risultare interrotti in modo imprevisto.
Un breve elenco di questi casi, da usare con estrema prudenza, include:
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.
Prestare molta attenzione e creare una revisione quando si apportano modifiche non banali alla definizione del connettore o all'API sottostante.