Uso di criteri per la conversione dei dati
È possibile usare modelli di criteri per convertire i dati da una struttura a un'altra. Questo processo viene in genere eseguito per semplificare l'attività dei creatori di usare un connettore personalizzato per fornire dati alle azioni o per lavorare con i dati di risposta dai risultati dell'azione. L'API può ad esempio fornire un elenco delimitato da virgole di utenti che hanno accesso al record. La conversione di tale elenco in una matrice semplifica l'uso dell'elenco in un'app o in un flusso. La conversione di strutture di dati è attualmente supportata da modelli di criteri che eseguono le seguenti azioni:
Conversione di una matrice in un oggetto
Conversione di un oggetto in una matrice
Conversione di una stringa delimitata in una matrice di oggetti
Ogni criterio può essere eseguito sulla richiesta (dati di input) o sulla risposta (dati di output) di una o più azioni. Quando si esegue un criterio sulla richiesta, si modifica la forma dei dati forniti dal creatore per determinare come l'API vuole vederli. Il connettore Microsoft Planner, ad esempio, usa la conversione di una matrice per un oggetto sull'azione Aggiorna dettagli dell'attività. Questa azione consente all'utente di fornire una matrice di collegamenti di riferimento esterni e quindi eseguire l'associazione con l'attività. Poiché il creatore può specificare i collegamenti come una matrice, gli utenti visualizzano un'interfaccia intuitiva che consente loro di aggiungere più collegamenti selezionando Aggiungi nuovo elemento.
Se si usa la funzionalità di visualizzazione in anteprima nel passaggio di azione, è possibile vedere come sono strutturati i dati e come verranno presentati all'API in assenza di trasformazioni eseguite dai modelli di criteri sul connettore.
Se si analizza la documentazione dell'API di Microsoft Planner per questa operazione si può notare che i dati devono essere strutturati come nell'esempio seguente.
Per convertire gli elementi forniti dall'azione del flusso in ciò che è previsto dall'API, il connettore è configurato per la trasformazione dei dati tramite più modelli di criteri. I modelli di criteri vengono usati come illustrato di seguito:
Imposta proprietà - Per impostare il campo previewPriority su "!"
Imposta proprietà - Per impostare l'espressione @odata.type
Converti matrice in oggetto - Per rimodellare la matrice e includere tipo e alias come proprietà
Il criterio Converti matrice in oggetto sarà simile all'esempio seguente.
I modelli di criteri eseguiti sulla risposta consentono di rimodellare l'output dell'API. La risposta di Contoso Invoicing per l'azione Ottieni fattura include ad esempio un elenco di tag delimitati da punto e virgola come parte dell'oggetto fattura. I dati restituiti dall'API sono simili allo screenshot seguente.
Una stringa con più valori è più difficile da usare per le app e i flussi rispetto a una matrice. Per migliorare l'usabilità, è possibile usare il modello di criteri Converti stringa delimitata. L'esempio seguente mostra il modello di criteri da configurare.
Il risultato dell'azione è l'aggiunta di una nuova matrice denominata taglist alla risposta, come illustrato nell'immagine seguente.
Ora che sono stati esaminati alcuni esempi di modelli di criteri in uso, è possibile rivedere alcuni dettagli chiave di configurazione. Il parametro Esegui criterio su stabilisce se il criterio si applica alla richiesta o alla risposta. Se sono necessarie entrambe le opzioni, sarà necessario configurare due modelli di criteri.
Ogni modello di criteri di conversione ha un parametro relativo alla raccolta o all'oggetto di destinazione. Questo fattore fornisce il punto di partenza da cui la logica dei criteri ottiene i dati da trasformare. Il punto di partenza più comune si ottiene usando l'espressione @body(), che punta al corpo della richiesta o della risposta. Nell'esempio seguente l'espressione @body() è un oggetto e ha una proprietà denominata tags.
In alternativa, se la risposta fosse un oggetto con una proprietà denominata invoices costituito da una matrice di oggetti fattura ognuno con una proprietà tags, la configurazione sarebbe simile all'immagine seguente.
Durante la configurazione dei criteri, assicurarsi di applicarli solo alle azioni con dati di richiesta/risposta che corrispondono a queste configurazioni. L'azione Ottieni fattura, che restituisce un singolo oggetto fattura, richiederebbe ad esempio l'applicazione di modelli di criteri diversi rispetto all'azione Elenco fatture, che restituisce una matrice di oggetti fattura. Se si stanno aggiungendo modelli di criteri a un connettore esistente con tutte le azioni abilitate, assicurarsi di testare tutte le azioni e i trigger per verificare che funzionino con il nuovo criterio.
Dopo aver configurato i modelli di criteri di risposta, assicurarsi di reimportare i dati di esempio nella risposta dell'azione. Questo passaggio è necessario affinché app e flussi possano avere visibilità sui dati trasformati.
Se la configurazione di un modello di criteri crea un errore, in genere è possibile vederlo nel tester come uno stato HTTP 500 o capirlo dal fatto che non viene eseguita alcuna elaborazione. Sebbene non sia possibile disabilitare un criterio, è possibile rimuovere un'azione dall'elenco delle operazioni per consentire l'isolamento nei test se il criterio sta causando problemi. L'immagine seguente mostra solo due operazioni selezionate.
I modelli di criteri di conversione offrono un approccio incentrato sulla configurazione per trasformare i dati da e verso l'API sottostante. Possono essere usati per semplificare l'uso delle azioni del connettore.