Configura lo strumento Call API

Questa configurazione richiede conoscenze di API e codifica.

Lo strumento Call API ti consente di gestire le chiamate API pubbliche che stai effettuando attraverso i flussi di lavoro di automazione in Bridge. Ha due componenti principali: 

• Profiles: conserva le informazioni sulle API di sistema a cui desideri connettere i flussi di lavoro. 

• Modulo Make API Call: utilizza i dati del profilo e i dettagli specifici forniti per effettuare una chiamata API a un'API di sistema.

   

Suggerimento sul Bridge Builder

I profili semplificano anche la modifica dei flussi di lavoro utilizzando tale profilo in caso di modifiche delle informazioni chiave, come il token di autorizzazione o il Base URL. Un aggiornamento del profilo garantirà che tutti i moduli che chiamano il profilo ottengano i dati più recenti per effettuare la chiamata.

Campi di chiamata API

Prima di iniziare, esaminiamo alcuni dettagli terminologici sull’uso delle API.

Base URL

Questo campo è contenuto nel profilo ed è la parte dell’URL dell’API che rimane sempre la stessa. Per Smartsheet, devi utilizzare il Base URL: https://api.smartsheet.com/2.0/.

Endpoint

Questo campo è contenuto nel modulo Make API Call e specifica l’azione che si desidera eseguire (ad esempio ordinare il foglio). Quindi, puoi aggiungere tutti i riferimenti ai dati di cui hai bisogno dai trigger Bridge.

Ecco alcuni esempi su come configurare i dati statici o dinamici:

• Static ID value: il formato URL per questo tipo di dati è il seguente: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Devi specificare l’ID del foglio in questo URL, in modo che la chiamata API ordini sempre quel foglio specifico. 
• Dynamic Run Log data reference: il formato URL per questi dati è simile a quello del valore ID statico: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. Tuttavia, invece di aggiungere l’ID del foglio, dovresti aggiungere il riferimento ai dati del foglio dal log di esecuzione del flusso di lavoro Bridge. È utile se il flusso di lavoro Bridge si attiva in caso di modifiche o trasporta dati da più fogli. Quando usi questo tipo di URL, la chiamata API ordina il foglio specifico a cui si fa riferimento in questo URL.

Method

Il metodo definisce il tipo di operazioni che stai tentando di eseguire e lo imposterai per ogni chiamata API nel modulo Make API Call. La maggior parte delle API delinea il metodo necessario per un determinato endpoint API. Ad esempio, con Smartsheet, i metodi che utilizzerai sono i seguenti:

• GET: porta i dati nel flusso di lavoro Bridge "ottenendo" una riga da un foglio.
• POST: crea qualcosa. Ad esempio, aggiungi una riga a un foglio.
• PUT: aggiorna qualcosa. Ad esempio, aggiorna una riga su un foglio.
• DELETE: elimina qualcosa. Ad esempio, elimina una riga da un foglio.

Intestazioni

Le intestazioni sono i valori necessari per la richiesta e le coppie chiave-valore. Di solito vengono utilizzate per gestire le autorizzazioni (permessi). Ad esempio, nelle chiamate Smartsheet, avrai un’intestazione chiave denominata Authorization con il valore impostato su Bearer [Inserisci il tuo token API].

Le intestazioni necessarie per ogni chiamata a un sistema possono essere impostate nel profilo. È possibile impostare intestazioni aggiuntive per azioni specifiche nel modulo Make API Call nel flusso di lavoro. 
 

Form Parameters 

I parametri del modulo sono noti anche come Query Parameters o Arguments. Sono elementi aggiuntivi che puoi definire nella richiesta. È possibile impostarli nel modulo Make API Call.

Uno scenario di esempio potrebbe essere l’applicazione del paging con le chiamate Smartsheet, in modo che nella risposta sia incluso solo un certo numero di elementi. Ad esempio, desideri ottenere solo la prima pagina di un report con 20.000 righe.
 

Body

Il corpo contiene i dettagli pertinente alla richiesta che devi inviare. Di solito è in formato JSON.

L’invio dei parametri del modulo sovrascriverà qualsiasi dato del corpo.

In una chiamata API Sort Sheet, il corpo sarà simile al seguente: {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}. Il corpo nell’esempio sopra potrebbe utilizzare uno di questi tipi di valore:

• Un valore statico per una colonna specifica in un foglio, oppure
• Un riferimento ai dati dinamici del log di esecuzione in cui viene visualizzato l'ID colonna. 

A seconda del tipo di richiesta che stai facendo, un corpo potrebbe non essere necessario. Ad esempio, non avrai bisogno di un corpo per le chiamate GET.
 

Dati restituiti

Se l’API di risposta restituisce un oggetto JSON, verrà salvato nel log di esecuzione. Ciò consente di fare riferimento ai dati restituiti nelle parti successive del flusso di lavoro.

Ora conosci i campi che incontrerai quando configuri i moduli Profiles e Make API Call dello strumento Call API. Continua a leggere per saperne di più su come impostare e utilizzare questa utility.

Di cosa hai bisogno per iniziare

• Un foglio 
  • Sheet ID
  • Una colonna che, una volta modificata nelle righe, desideri che attivi il flusso di lavoro Bridge
• Bridge
  • Integrazione di Smartsheet
  • Trigger del flusso di lavoro Bridge: Smartsheet - When Column Values are Changed
  • Moduli di flusso di lavoro Bridge: Make API Call
• Una chiave API Smartsheet. Scopri come generare una chiave API per Smartsheet. 

Per iniziare

Per creare questo flusso di lavoro in Bridge, autentica l’integrazione Smartsheet per il tuo workspace Bridge. Leggi i passaggi su come impostare l'integrazione Smartsheet per Bridge. 

Durante la creazione del flusso di lavoro, mantieni il foglio, la documentazione API di Smartsheet e il flusso di lavoro Bridge aperti in tre schede separate. Ciò renderà più facile la navigazione nel processo di generazione!

Passaggio 1: Costruisci il modello di flusso di lavoro di base

Prima di ogni altra cosa, estrai tutti i moduli necessari per il flusso di lavoro. 

1. Crea un nuovo flusso di lavoro in Bridge. 
2. Nel generatore di flussi di lavoro, usa il pannello per aggiungere il modulo Make API Call.
3. Salva il flusso di lavoro.

Questo è ciò che dovresti vedere nel tuo flusso di lavoro quando avrai finito: 

Brandfolder Image

Imposta il trigger del flusso di lavoro

Dopo aver creato il modello di flusso di lavoro di base, inizia a configurare il trigger del flusso di lavoro.

1. Seleziona il modulo Trigger.
2. Per aprire il pannello Integration in una nuova scheda, nella sezione Integrations seleziona Integrations Page.

3. Individua Smartsheet dall'elenco delle integrazioni.
    

   Puoi utilizzare l’opzione Connected sotto il logo Bridge per ottenere un elenco delle sole integrazioni autenticate per tale workspace.

4. Espandi la riga Triggers.
5. Per creare un nuovo trigger, seleziona l'icona più.
6. Compila i seguenti campi:
   • Trigger Name: crea un'etichetta personalizzata per il trigger.
   • Sheet ID: incolla l'ID del foglio (il foglio che desideri ordinare).
   • Event Type: seleziona When Column Values are Changed. 
   • Column Name or ID: digita il nome della colonna Smartsheet a cui desideri rispondere. Ad esempio, se desideri ordinare le righe sul foglio ogni volta che la priorità cambia, digita il nome della colonna delle priorità.
   • Select Workflow: seleziona il nuovo flusso di lavoro appena creato dall'elenco a discesa.
7. Seleziona Save.
8. Nell'info Trigger, copia l'ID della colonna.
   • L'ID della colonna sarà disponibile nelle informazioni Trigger dopo aver salvato il trigger del flusso di lavoro.
9. Incollalo in un blocco note o in qualsiasi elaboratore di testi. Avrai bisogno dell'ID colonna in un passaggio successivo. 

10. Torna al flusso di lavoro.
     

    Se desideri tornare alla scheda originale, aggiorna la pagina per visualizzare il trigger.

Ottieni i dettagli della chiamata API

Le modifiche dei valori nella colonna delle priorità del foglio si attivano in questo flusso di lavoro. Una volta che questo flusso di lavoro rileva i trigger, esegue le azioni necessarie sullo stesso foglio. Quindi, per compilare i moduli Smartsheet, useremo i riferimenti ai dati di runtime (Run Log) dal trigger.

Per questo flusso di lavoro, dovrai effettuare una chiamata API all’endpoint Smartsheet Sort Sheet. Usa la documentazione dell’API Smartsheet per modificare l’esempio in cURL.

Passaggio 2: Configura il tuo primo profilo

I profili sono un modo per salvare le informazioni chiave per le API di sistema a cui desideri connettere i flussi di lavoro. Quando selezioni un profilo nel modulo Make API Call, alcune delle informazioni necessarie per effettuare la chiamata API saranno già configurate per te. 

1. Accedi al tuo account Bridge
2. Vai alla scheda Integrations.
3. Seleziona l'utility Call API.

4. Seleziona Add to Profiles.

   Brandfolder Image

   
5. Assegna un nome al profilo. Ogni nome del profilo deve essere univoco.
6. Aggiungi il Base URL per l’API di sistema a cui desideri connetterti.
   • In questo esempio, l’URL di base per Smartsheet è https://api.smartsheet.com/2.0/.
7. In Secret Headers, aggiungi tutte le intestazioni che contengono token o informazioni segrete (ad esempio token API).
   • Ad esempio, nelle chiamate Smartsheet, avrai un’intestazione chiave denominata Authorization con il valore impostato su Bearer [Inserisci il tuo token API].
8. In Headers, aggiungi tutte le intestazioni che devono essere incluse in tutte le chiamate API effettuate con questo profilo.
   • In questo esempio, abbiamo usato Content-Type come intestazione con un valore impostato su application/json.
9. Salva il profilo.

10. Torna al flusso di lavoro.

     

Suggerimento sul Bridge Builder

L’URL di base è la parte dell’URL dell’API di sistema che rimarrà invariata, indipendentemente da ciò che si sta tentando di fare in quel sistema. L’endpoint nel modulo Make API Call serve a includere i dettagli specifici e le azioni che è necessario intraprendere con tale chiamata API.

Esempio: stiamo usando l’API Smartsheet per ordinare un foglio. Il Base URL per il nostro profilo API Smartsheet è https://api.smartsheet.com/2.0 e l’azione specifica che stiamo intraprendendo con il modulo è quella di ordinare un foglio specifico, quindi inseriremo sheets/sheet_id_or_data_reference_here/sort nel campo Endpoint del modulo.

Passaggio 3: Configura il modulo Make API Call nel flusso di lavoro

1. Nel modulo Make API Call, seleziona il profilo desiderato dal menu a discesa.
2. Nel campo Endpoint, includi la parte del campo URL che non è stata aggiunta al campo Base URL nel profilo.
   • In questo esempio abbiamo usato sheets/sheet_id_or_data_reference_here/sort.
3. Compila i campi seguenti. tieni presente che non è possibile utilizzarli tutti:
   • Imposta il metodo su POST.
   • Nel campo HTTP Request Body, un corpo sarà simile al seguente: {"sortCriteria": [{"columnId": column_id_here, "direction": "ASCENDING"}]}
   • Parametri del modulo (se in uso; non in uso per questo flusso di lavoro)

4. Salva le modifiche.

   Brandfolder Image

   

   
    

Passaggio 4: Testa il flusso di lavoro

1. Apri il foglio. 
2. Modifica un valore nella colonna delle priorità. 
3. Salva il foglio. 

Se la colonna delle priorità è un elenco a discesa, le righe ordinate visualizzeranno in ordine crescente o decrescente (a seconda di quale opzione hai definito nel corpo della chiamata API) i valori mostrati nelle impostazioni della colonna. 

Impostazioni aggiuntive per il modulo

• Il modulo Make API Call restituisce tutte le chiamate API come oggetto JSON. Se hai bisogno che la risposta restituisca una stringa, puoi selezionare la casella di spunta Return raw response in Additional settings nel modulo.
• Se è necessario includere intestazioni aggiuntive per una chiamata specifica, copiale nella sezione HTTP Request Headers.

Opzioni alternative per questo flusso di lavoro

Ecco alcune idee su come personalizzare questo flusso di lavoro:

• Attiva da un foglio o da una colonna diversi da quelli che desideri ordinare. Ciò richiederà di modificare i dettagli di API Call in modo che si adattino al foglio e alla colonna che desideri ordinare. 
• Aggiungi una condizione al tuo ordinamento. Dopo che il flusso di lavoro è stato attivato, utilizza un modulo di giunzione per valutare il valore della colonna ed eseguire azioni diverse in base alla modifica apportata nella colonna delle priorità (ad esempio, se la priorità è 0, sposta la riga fuori dal foglio; se la priorità è 1, ordina il foglio).
• Usa un trigger di programmazione. Quando utilizzi questo trigger, non dovrai rispondere affatto alle modifiche, in quanto ordinerà il foglio una volta al giorno, a settimana o al mese.

Usa gli strumenti dell'API Call per tutte le tue soluzioni

• I profili si applicano al workspace, quindi tutti i flussi di lavoro nel workspace possono utilizzare lo stesso profilo in tutti i moduli Make API Call utilizzati. Quando i dettagli del profilo devono cambiare perché sono cambiate le autorizzazioni di un utente o l’API di sistema apporta modifiche, c’è un unico posto per apportare tali modifiche e applicarle ai flussi di lavoro nel workspace che utilizzano quel profilo.
• Per ogni API di sistema aggiuntiva a cui devi connetterti, puoi impostare un nuovo profilo univoco seguendo la prima parte della guida.