Effettua richieste all'API Discourse con Zapier

[Discourse]

Le richieste all’API di Discourse possono essere automatizzate creando uno Zap che utilizza un Webhook di Zapier come passaggio di azione. Questo argomento descrive come eseguire richieste per le seguenti azioni:

• aggiungere un utente a un gruppo
• assegnare un badge personalizzato

Per capire come eseguire altri tipi di richieste API con Zapier, leggi questo argomento e poi cerca nella documentazione dell’API di Discourse l’azione che desideri eseguire. Puoi anche scoprire come creare una richiesta API per un’azione specifica leggendo Reverse engineer the Discourse API.

Configurare il passaggio di attivazione (trigger)

Ogni Zap deve avere un passaggio di attivazione (trigger) e un passaggio di azione. Il trigger viene utilizzato per trasferire dati da un’applicazione al passaggio di azione dello Zap. In alcuni casi, il trigger può anche essere utilizzato per impedire allo Zap di completare il passaggio di azione a meno che i dati non soddisfino determinate condizioni.

Per configurare il passaggio di azione, vai alla tua Dashboard di Zapier e clicca sul pulsante “Crea uno Zap”. Si aprirà un modulo di ricerca che ti chiederà di scegliere un’app di attivazione.

Per gli esempi in questo argomento, sto utilizzando l’evento “Nuovo utente” di WordPress come passaggio di attivazione. Questo perché è facile da configurare per testare le chiamate API.

Il nodo “Testa questo passaggio” del tuo passaggio di attivazione ti consente di selezionare un campione di dati dalla tua applicazione di attivazione che verrà trasferito al passaggio di azione dello Zap. Questi dati saranno utili per configurare il passaggio di azione.

Aggiungere un passaggio opzionale per recuperare i dettagli da Discourse

A seconda dei dati trasferiti dalla tua app di attivazione, potresti aver bisogno di recuperare alcuni dati da Discourse prima di effettuare la richiesta API finale. Ad esempio, il trigger “Nuovo utente” di WordPress trasferisce il nome utente WordPress e l’indirizzo email dell’utente. So che l’indirizzo email corrisponderà all’email dell’utente su Discourse, ma per le richieste API in questo esempio, ho bisogno di conoscere il nome utente Discourse dell’utente.

Per ottenere i dettagli di un utente su Discourse dal suo indirizzo email, aggiungi un passaggio di azione al tuo Zap. Seleziona “GET” dal menu delle azioni del webhook.

Nel passaggio di modifica del modello del webhook, inserisci l’URL di base del tuo sito Discourse, seguito da /admin/users/list/all.json nella sezione URL. Ad esempio, l’URL di base del mio sito è https://demo.scossar.com, quindi inserisco https://demo.scossar.com/admin/users/list/all.json nel campo URL.

Nella sezione Parametri della stringa di query, inserisci “email” come Chiave e quindi clicca sull’icona “Inserisci un campo” per aprire il menu a discesa. Seleziona il valore trasferito dal tuo passaggio di attivazione che contiene l’indirizzo email dell’utente.

Autenticare la richiesta

Scorri verso il basso nel modulo fino alla sezione Intestazioni (Headers). Questa sezione viene utilizzata per autenticare la richiesta. Richiede tre coppie chiave/valore:

• Api-Username: il nome utente di un amministratore sul tuo sito. Nella maggior parte dei casi, l’utente ‘system’ sarà una buona scelta.
• Api-Key: la chiave API associata al nome utente utilizzato nella prima coppia chiave/valore
• Content-Type: multipart/form-data

La sezione Intestazioni completata dovrebbe assomigliare a questa, ma con la tua chiave API:

Clicca sul pulsante Continua per visualizzare i dati recuperati da Discourse per questa richiesta.

Aggiungere il passaggio di azione finale

Una volta configurati il trigger e il passaggio opzionale per recuperare i dati da Discourse, clicca sul link “Aggiungi un passaggio” e seleziona “Webhooks by Zapier” dal menu delle azioni. Ti verrà quindi chiesto di scegliere quale metodo di richiesta utilizzare nella tua richiesta API a Discourse.

Ecco i tipi di richiesta necessari per gli esempi utilizzati in questo argomento:

• aggiungere un utente a un gruppo: PUT
• assegnare un badge personalizzato: POST

Per configurare richieste API diverse dagli esempi di questo argomento, consulta la documentazione dell’API di Discourse per vedere se esiste un esempio della richiesta che desideri effettuare. Se non trovi un esempio lì, leggi Come fare reverse engineering dell’API di Discourse per imparare a trovare l’URL e il metodo di richiesta per l’azione che desideri eseguire. Una volta trovato il metodo di richiesta, selezionalo dal menu delle azioni.

Nota: se la tua richiesta utilizza il metodo DELETE, seleziona “Richiesta personalizzata” dal menu delle azioni.

Configurare il passaggio di azione finale

La sezione Intestazioni dell’azione può essere configurata nello stesso modo per tutte le richieste API. Consulta la sezione ‘Autenticare la richiesta’ di questo argomento per i dettagli. Se hai aggiunto il passaggio opzionale per recuperare i dettagli da Discourse, puoi configurare la sezione Intestazioni dell’azione finale esattamente nello stesso modo in cui hai fatto per quel passaggio.

Una volta aggiunte le coppie chiave/valore delle intestazioni, dovrai compilare i campi URL e Dati del modulo per la tua richiesta API.

Aggiungere un utente a un gruppo

Per aggiungere un utente a un gruppo, viene effettuata una richiesta PUT a /groups/<group_id>/members.json. Il modo più semplice per trovare l’ID di un gruppo è visitare la pagina del gruppo tramite l’interfaccia utente di Discourse e quindi inserire .json nell’URL nella barra degli indirizzi del browser. Ad esempio, il mio sito ha un gruppo “supporto” all’indirizzo https://demo.scossar.com/g/support. Andando su https://demo.scossar.com/g/support.json posso vedere che l’ID del gruppo è 41. L’URL di base del mio forum è https://demo.scossar.com. L’URL nel mio passaggio di azione finale per aggiungere utenti a un gruppo viene impostato su https://demo.scossar.com/groups/41/members.json.

La richiesta per aggiungere utenti a un gruppo richiede un parametro: un elenco di nomi utente separati da virgole. Nella sezione Dati del modulo, inserisci “usernames” come chiave. Quindi clicca sull’icona “Inserisci un campo” per cercare la proprietà del nome utente che è stata trasferita dal trigger o dal passaggio di azione GET opzionale.

Nel mio caso, voglio il nome utente recuperato dal passaggio GET, quindi espando il menu “GET” e seleziono Username dal menu a discesa.

Tutte le altre sezioni del modulo possono essere lasciate con i valori predefiniti.

Clicca sul pulsante Continua e poi testa il tuo passaggio. Se l’utente che hai trasferito attraverso i passaggi precedenti esiste sul tuo sito Discourse e non è già membro del gruppo selezionato, dovrebbe essere aggiunto al gruppo quando testi il passaggio.

Se tutto funziona come previsto, attiva il tuo Zap.

Assegnare un badge personalizzato

Per assegnare un badge personalizzato a un utente, viene effettuata una richiesta POST all’URL di base del tuo forum + /user_badges. Per il mio sito, l’URL per l’assegnazione dei badge è https://demo.scossar.com/user_badges. Il campo URL completato su Zapier appare così:

La sezione Dati del modulo richiede due coppie chiave/valore. Aggiungi una chiave “username” e impostala sul campo che restituisce il nome utente dell’utente. Aggiungi una chiave “badge_id” e impostala sull’ID del badge che desideri assegnare. Puoi trovare l’ID del badge andando alla pagina Amministratore / Badge e selezionando il badge dal menu a sinistra. Vedrai l’ID del badge come ultimo valore dell’URL nella barra degli indirizzi del browser.

Il badge che sto assegnando ha un ID di 105, quindi la mia sezione Dati completata appare così:

Assicurati di aver configurato la sezione Intestazioni del modulo, quindi clicca su Continua. Quindi clicca sul pulsante Invia test per testare il tuo Zap. L’utente che hai trasferito attraverso i passaggi precedenti dovrebbe ricevere il badge.

Se tutto funziona correttamente, attiva lo Zap.

[aj_silvers]

È possibile utilizzare questo flusso di lavoro per creare automaticamente un account per un nuovo utente e aggiungerlo a un gruppo Discourse specifico?

Il caso d’uso qui è il seguente: qualcuno acquista un prodotto formativo e io voglio aggiungerlo automaticamente al sottoboard Discourse pertinente per quel prodotto.

Posso ottenere i dati del nuovo cliente in Zapier, ma il flusso di lavoro Discourse standard non ha la funzionalità di creazione account. Mi chiedevo solo se sia possibile farlo tramite l’API e il collegamento webhook come descritto in questo esempio.

Grazie!

[simon]

@aj_silvers

Il caso d’uso qui è che qualcuno acquista un prodotto di formazione; voglio aggiungerlo automaticamente al sottoforum Discourse pertinente per quel prodotto.

L’approccio più semplice sarebbe inviare un’email di invito alla persona dopo l’acquisto. Puoi configurare l’invito in modo che l’utente venga aggiunto automaticamente a un gruppo Discourse quando accetta l’invito. Per i dettagli, consulta Automate sending Discourse invite emails with Zapier.

Se l’invio di inviti non è un’opzione per te, è possibile utilizzare un webhook di Zapier per creare un utente Discourse. La pagina Discourse API Docs fornisce i dettagli sulla richiesta per creare un utente.

[aj_silvers]

Grazie @simon, proverò l’invito via email. Senza dubbio alcune persone non lo riceveranno/non lo troveranno/non lo apriranno, ma è sicuramente l’opzione più semplice.

Apprezzo anche la risposta veloce!

[pfaffman (Jay Pfaffman)]

Spesso è più facile che chi vende il prodotto effettui direttamente le chiamate all’API di Discourse.

[Nacho_Caballero]

C’è un motivo per cui questo funziona per me su Zapier, ma ottengo una risposta vuota quando provo a fare la mia richiesta fetch?

Sto usando ObservableHQ, ma il concetto è lo stesso. Non dovrebbe funzionare?

fetch("https://mycommunity.com/g.json", {
  headers: {
    "Content-Type": "multipart/form-data",
    "Api-Username": Secret("DISCOURSE_USERNAME"),
    "Api-Key": Secret("DISCOURSE_KEY")
  },
  method: "GET",
  mode: "no-cors"
})

[simon]

Riesci a far funzionare richieste API a Discourse con chiamate in quel formato da ObservableHQ? Sembra che ci debba essere qualcosa di sbagliato nel formato della richiesta.

Puoi anche verificare le richieste effettuando chiamate curl dal tuo terminale o utilizzando Postman.

[Nacho_Caballero]

Ok, ho capito cosa dovevo fare:

1. Installare cors-anywhere localmente e avviare il server
2. Modificare la richiesta per includere il proxy inverso prima dell’endpoint dell’API e chiamare il metodo json sull’oggetto Risposta Fetch:

await (fetch("http://localhost:8080/mycommunity.com/g.json", {
  headers: {
    "Api-Username": Secret("DISCOURSE_USERNAME"),
    "Api-Key": Secret("DISCOURSE_KEY")
  },
})).json()

[markersocial]

Lo lascio qui, potrebbe valere la pena dare un’occhiata:

n8n.io - AI workflow automation platform

GitHub - n8n-io/n8n: Fair-code workflow automation platform with native...

[Bernstein (Carey Bernstein)]

@simon

Per assegnare un distintivo personalizzato a un utente, viene inviata una richiesta POST all’URL base del tuo forum + /user_badges.

Ciao @simon, grazie per questa guida. Sto configurando tutto su Zapier, ma il mio forum non ha questo URL per l’assegnazione dei distintivi.

Mi chiedevo: non è un URL standard per tutte le installazioni di Discourse, o l’URL potrebbe essere cambiato in un aggiornamento recente?

[simon]

@Bernstein

Il mio forum non ha questo URL per l’assegnazione dei badge.

Dovrebbe averlo. Tuttavia, non si tratta di un URL visitabile tramite l’interfaccia utente di Discourse. Ho appena verificato la rotta sul mio sito seguendo i passaggi illustrati qui: Come fare reverse engineering dell’API di Discourse. Sulla base di ciò, sembra che i dettagli forniti nell’argomento siano ancora aggiornati.

[Bernstein (Carey Bernstein)]

Non è una sorpresa, è stato un mio errore.