Utilità bridge: API di chiamata

L'utilità Call API consente di gestire le chiamate API pubbliche effettuate nei flussi di lavoro di automazione in Bridge. Ha due componenti principali: 

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

• Il modulo Make API Call utilizza i dati del profilo e i dettagli specifici forniti dall'utente per effettuare una chiamata API a un'API di sistema.

  Questa configurazione richiede conoscenze di API e codifica.

Consiglio per Bridge Builder

I profili semplificano le modifiche al flusso di lavoro in caso di modifiche alle informazioni chiave, come il token di autorizzazione o l'URL di base. Un aggiornamento del profilo garantisce che tutti i moduli che chiamano il profilo ottengano i dati più recenti per effettuare la chiamata.

Crea modulo Chiamata API 

Questo è l'unico modulo dell'utilità e contiene i seguenti campi:

Endpoint

Questo campo specifica l'azione da intraprendere (ad esempio, ordinare il foglio). In questo valore, puoi aggiungere qualsiasi riferimento ai dati dai trigger di Bridge. Ecco alcuni esempi di come configurare dati statici o dinamici:

• Valore ID statico: il formato URL per questo tipo di dati è il seguente: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Specifica l'ID del foglio in questo URL, in modo che la chiamata API ordini sempre quel foglio specifico. 
• Riferimento ai dati Dynamic Run Log: il formato URL per questi dati è il seguente: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. Tuttavia, invece di aggiungere l'ID del foglio, è necessario aggiungere il riferimento ai dati del foglio dal registro di esecuzione. È utile se il flusso di lavoro Bridge si attiva in caso di modifiche o trasporta dati da più fogli. Quando si utilizza questo tipo di URL, la chiamata API ordina il foglio specifico a cui si fa riferimento in questo URL.

Metodo

Il metodo definisce il tipo di operazioni che si desidera eseguire. Definisci un metodo 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, questi sono i metodi che puoi utilizzare:

• OTTIENI: porta i dati nel flusso di lavoro di 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.
• ELIMINA: 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 utilizzati per gestire le autorizzazioni (permessi). Ad esempio, nelle chiamate Smartsheet, avresti un'intestazione chiave denominata Authorization con il valore impostato su Bearer [Inserisci il tuo token API].

Il profilo può impostare le intestazioni necessarie per ogni chiamata a un sistema. Nel tuo flusso di lavoro, il modulo Make API Call ti consente di configurare intestazioni aggiuntive per azioni specifiche. 

Parametri del modulo 

I parametri del modulo sono noti anche come parametri di interrogazione o argomenti. I parametri del modulo sono elementi aggiuntivi che puoi definire nella richiesta. Li imposti nel modulo Make API Call.

Uno scenario di esempio potrebbe essere quello di applicare il paging con chiamate Smartsheet per includere alcuni elementi nella risposta. Ad esempio, desideri ottenere solo la prima pagina di un report con 20.000 righe.

Corpo della richiesta HTTP

Un ente dispone dei dettagli della richiesta pertinenti che devi inviare. Di solito è in formato JSON.

L'invio dei parametri del modulo sovrascrive qualsiasi dato del corpo.

In una chiamata all'API Sort Sheet, un corpo avrebbe il seguente aspetto: {"sortCriteria»: [{"columnId»: {smartsheetColumnId}, «direction»: «DESCENDING"}]}. Il corpo in questo esempio 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. 

Un corpo potrebbe non essere necessario a seconda del tipo di richiesta che stai facendo. Ad esempio, non è necessario un corpo per le chiamate GET.

Output

Se l'API che risponde restituisce un oggetto JSON, questo viene salvato nel registro di esecuzione. Ciò consente di fare riferimento ai dati restituiti più avanti nel flusso di lavoro.

Di cosa hai bisogno per iniziare

• Un foglio 
  • L'ID del foglio
  • Una colonna che, se modificata nelle righe, attiva il flusso di lavoro di Bridge
• Bridge
  • Integrazione di Smartsheet
  • Trigger del flusso di lavoro Bridge: Smartsheet - When Column Values are Changed
  • Modulo bridge: Utilità > Chiama API > Effettua chiamata API
• Una chiave API Smartsheet.

Per creare questo flusso di lavoro in Bridge, autentica l'integrazione Smartsheet per il tuo spazio di lavoro 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

Recupera 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 hai finito: 

Brandfolder Image

Imposta il trigger del flusso di lavoro

1. Seleziona il modulo Trigger.
2. Nella sezione Integrazioni, seleziona la pagina delle integrazioni.

3. Individua Smartsheet dall’elenco delle integrazioni.

   Puoi utilizzare l'opzione Connesso sotto il logo Bridge per ottenere un elenco delle sole integrazioni autenticate per quell'area di lavoro.

4. Espandi la riga Trigger.
5. Per creare un nuovo trigger, seleziona Aggiungi ai trigger.
6. Compila i seguenti campi:
   • Nome del trigger: crea un'etichetta personalizzata per il trigger.
   • ID foglio: incolla l'ID del foglio (il foglio che desideri ordinare).
   • Tipo di evento: seleziona quando i valori delle colonne vengono modificati. 
   • Nome o ID colonna: digita il nome della colonna Smartsheet a cui vuoi rispondere. Ad esempio, se hai intenzione di ordinare le righe del foglio ogni volta che la priorità cambia, digita il nome della colonna di priorità.
   • Seleziona flusso di lavoro: seleziona il nuovo flusso di lavoro appena creato dall'elenco a discesa.
7. Seleziona Salva.
8. Copia l'ID della colonna nelle informazioni sul trigger. Una volta salvato il trigger del flusso di lavoro, l'ID della colonna diventa disponibile nelle informazioni sul trigger.
9. Incollalo nel Blocco note o in qualsiasi elaboratore di testi. È necessario l'ID della colonna per un passaggio successivo. 
10. Torna al flusso di lavoro.

Ottieni i dettagli della chiamata API

Questo flusso di lavoro modifica il valore nella colonna della priorità del trigger del foglio. Una volta che questo flusso di lavoro rileva i trigger, esegue le azioni necessarie sullo stesso foglio. Utilizziamo i riferimenti ai dati di runtime (Run Log) del trigger per compilare i moduli Smartsheet.

Per questo flusso di lavoro, devi 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 sono già impostate per te. 

1. Vai alla scheda Integrazioni.
2. Seleziona l'utilità Call API.
3. Espandi la sezione Profili, nella scheda Profili.

4. Seleziona Aggiungi ai profili.

   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.  L'URL di base per Smartsheet è https://api.smartsheet.com/2.0/
7. In Intestazioni segrete, aggiungi tutte le intestazioni che contengono token o informazioni segrete, come i token API.
   • Ad esempio, nelle chiamate Smartsheet, in genere hai un'intestazione chiave denominata Autorizzazione con il valore impostato su Bearer [Inserisci il tuo token API].
8. In Headers, aggiungi le intestazioni da includere in tutte le chiamate API effettuate con questo profilo.
   • In questo esempio, abbiamo utilizzato Content-Type come intestazione con un valore impostato su application/json.
9. Seleziona Salva.
10. Torna al flusso di lavoro.

Bridge Builder tip

L'URL di base è la parte dell'URL dell'API di sistema che rimane sempre la stessa, indipendentemente da ciò che stai cercando di fare in quel sistema. L'endpoint nel modulo Make API Call ti consente di includere i dettagli e le azioni specifici che intraprendi con quella chiamata API.

Esempio: stiamo usando l’API Smartsheet per ordinare un foglio. L'URL di base per il nostro profilo API Smartsheet è https://api.smartsheet.com/2.0 e l'azione specifica che stiamo intraprendendo con il modulo è ordinare un foglio specifico, quindi dobbiamo inserire 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 API desiderato da utilizzare dal menu a discesa.
2. Nel campo Endpoint, includi la parte del campo URL che non è stata aggiunta al campo URL di base 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 Corpo della richiesta HTTP, un corpo avrebbe il seguente aspetto: {"sortCriteria»: [{"columnId»: column_id_here, «direction»: «ASCENDING"}]}
   • Parametri del modulo (se utilizzati, non utilizzati per questo flusso di lavoro)

4. Salva le modifiche.

   Brandfolder Image

   

Fase 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 di priorità è un menu a discesa, le righe ordinate sono in ordine crescente o decrescente (a seconda di ciò che hai definito nel corpo della chiamata API) dei valori visualizzati 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 venga restituita come stringa, puoi selezionare la casella di controllo Restituisci risposta non elaborata in Impostazioni aggiuntive nel modulo.
• Se devi includere intestazioni aggiuntive per una chiamata specifica, copiale nella sezione Intestazioni di richiesta HTTP.

Opzioni alternative per questo flusso di lavoro

• Attiva da un foglio o colonna diverso da quello che desideri ordinare. Ciò richiede di modificare i dettagli della chiamata API per adattarli al foglio e alla colonna che si desidera ordinare. 
• Aggiungi una condizione al tuo ordinamento. Dopo l'attivazione del flusso di lavoro, utilizza un modulo di giunzione per valutare il valore della colonna ed eseguire diverse azioni in base alla modifica apportata nella colonna Priorità (ad esempio: se Priorità è 0, sposta la riga dal foglio e se Priorità è 1, ordina il foglio).
• Usa un trigger di pianificazione. Quando utilizzi questo trigger, non devi rispondere alle modifiche poiché ordina il foglio una volta al giorno, alla settimana o al mese.

Usa gli strumenti Call API in 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é le autorizzazioni di un utente sono cambiate o l'API di sistema apporta modifiche, c'è un unico posto per apportare tali modifiche e applicarle ai flussi di lavoro nell'area di lavoro che utilizzano quel profilo.
• Per ogni API di sistema aggiuntiva a cui devi connetterti, puoi impostare un nuovo profilo univoco.
• Il modulo Make API Call ha esito positivo se riceve una risposta dall'API di destinazione, incluso se riceve un errore. Ciò è utile nelle fasi successive per determinare i percorsi nel flusso di lavoro per le risposte impreviste dall'API (ad esempio, se la chiamata API restituisce un errore, puoi inviare un aggiornamento a una riga indicando che c'è stato un problema). Se preferisci che il flusso di lavoro si interrompa se l'API restituisce un errore, puoi selezionare la casella nella sezione Impostazioni aggiuntive del modulo.