Che cos'è l'API Zendesk?
Un'API, o interfaccia di programmazione delle applicazioni, è uno strumento per le applicazioni software. Se pensi a un ristorante, il cameriere porta i piatti dalla cucina alla tua tavola. L'API funziona in modo simile: Porta i dati da un punto all'altro. Nell'API, la parabola è chiamata risorsae il server che te la porta è chiamato endpoint. Pensa a un piatto specifico che potresti richiedere al ristorante. Alcuni endpoint riportano una raccolta di elementi come un piatto di campionamento. Un esempio di ciò nell'API è l' endpoint Elenco utenti. Restituisce un elenco di tutti gli utenti nell'account Zendesk Support. Alcuni endpoint, comeMostra utente, sono più mirati e restituiscono solo un elemento.
Puoi anche usare l'API per modificare Zendesk. Immagina di dire a un cameriere come vorresti che fosse cotta la tua bistecca. Lo chef cambierà la bistecca in base alle tue esigenze. L'API è una risorsa potente che molti dei nostri clienti usano per importare risorse in blocco, creare app, trasferire dati in origini esterne e altro ancora.
La maggior parte della documentazione di riferimento per Zendesk API è disponibile nella sezione API di riferimentodel portale per sviluppatori Zendesk. La documentazione di riferimento descrive tutti gli endpoint disponibili. Puoi anche usare la guida per sviluppatori Zendesk per iniziare. Sebbene la documentazione sia completa, in questo articolo esamineremo come decodificarli e usarli.
Perché usare l'API?
Ora che sai cos'è l'API, ti starai chiedendo: "Perché dovrebbe interessarmi?" In poche parole, puoi usare l'API per aggiungere funzionalità che non sono disponibili nell'interfaccia utente (né a livello nativo, né a livello di piano) a un ritmo molto più rapido rispetto alle operazioni manuali.
Per gli account attualmente con piano Essential o Team, l'uso dell'API permette di avere un metodo diretto per l'esportazione dei dati senza dover passare al piano Professional (che consente l'esportazione automatica dei dati). Allo stesso modo, puoi usare l'API per ottenere i dati dei ticket a fini di reportistica. L'API può restituire tutte le informazioni relative a un ticket, quindi puoi usare l'output API per passare i dati a un'applicazione di generazione rapporti di terzi.
La possibilità di aggiornare rapidamente molti record è un altro vantaggio offerto dall'API. Ad esempio, mentre puoi creare una sola organizzazione alla volta nell'interfaccia agente, puoi creare fino a 100 organizzazioni alla volta con l'API. Allo stesso modo, le limitazioni sul numero di elementi che è possibile aggiornare alla volta sono maggiori con l'API. L'interfaccia permette di modificare 60 ticket contemporaneamente, mentre l'API ne permette un massimo di 100.
Altri compiti comuni includono:
- Creazione di ticket
- Migrazione dei dati dei ticket in Zendesk da un altro sistema
- Come modificare gli utenti in blocco
- Ricerca record
- E molti altri!
Ora che abbiamo indicato il motivo per cui usare l'API, vediamo come effettuare una richiesta API.
Formato
L'API Zendesk restituisce i dati in un formato leggero chiamato JSON. Consulta Lavorare con JSON nel Centro assistenza Zendesk. Puoi visualizzare i dati formattati in un browser web installando un'estensione per il visualizzatore JSON perChromeo Firefox.
JSON ha questo aspetto:
{
"posts": [
{
"id": 35467,
"title": "How do I open the safe"
},
{
"id": 35468,
"title": "How do I reset the combination?"
},
]
}
Un endpoint tipico ha il seguente aspetto:
subdomain.zendesk.com/api/v2/users/me.json
Gli endpoint possono eseguire le azioni seguenti:
- GET - Recupera elementi
- POST - Crea elementi che prima non esistevano
- PUT - Aggiorna elementi esistenti
- DELETE - Rimuovi elementi
In un browser è possibile effettuare solo richieste GET. Puoi eseguire le altre azioni usando strumenti come cURL o Postino.
cURL
La documentazione di riferimento usa cURL in tutti gli esempi di endpoint. cURL è uno strumento a riga di comando che ti permette di provare i comandi API senza un browser. Per maggiori informazioni, consulta la sezione relativa all'installazione e all'uso di cURL nel Centro assistenza Zendesk. Puoi usare cURL per uno qualsiasi dei 4 tipi di chiamate. È preinstallato su un Mac, ma sarà necessario installarlo in Windows. Per istruzioni, consulta l'articolo Installazione di cURL nel Centro assistenza Zendesk.
Stato delle tue richieste
Per ogni richiesta API effettuata, ricevi una risposta che ti informa se ha funzionato o meno. In caso contrario, la risposta fornirà indizi sul motivo per cui la richiesta non ha funzionato. Queste risposte sono chiamate codici di stato. Alcuni di quelli di base sono i seguenti:
- 200 - La richiesta è riuscita
- 400 - Richiesta non riuscita
- 409 - Errore di unione o vincolo. Riprova
- 422 - Entità non elaborabile
- 429 - Superato il limite massimo
- 500 - Avviso o stato temporaneo. Contatta l'assistenza se persiste
Consulta Formato delle risposte nella documentazione API per maggiori dettagli sui codici di stato.
pratica
Ora che abbiamo analizzato le basi di un'API, usiamola per cercare nei nostri ticket.
Supponiamo che io sia un utente del piano Team e che stia usando dei tag per monitorare l'escalation dei ticket a diversi livelli di assistenza. I tag che aggiungo sono escalation_one ed escalation_two.
Ora voglio generare un report per ogni ticket nel mio sistema che ha raggiunto entrambe le escalation. Ho provato a creare una vista per restituire questi ticket, ma non ha soddisfatto le mie esigenze perché i ticket archiviati non sono stati mostrati. Cosa faccio adesso?
Risposta: Usa l'API per ottenere i ticket!
A tal fine, ti consigliamo di visitare l' endpoint API di ricerca. Questo endpoint non filtra i ticket archiviati, quindi puoi usarlo per restituire un elenco di tutti i ticket che includono questi due tag. Allo stesso modo, l'API di ricerca è una semplice chiamata GET, quindi puoi usarla direttamente nel browser se hai effettuato l'accesso a Zendesk Support in un'altra scheda del browser. Il formato dell'endpoint di ricerca è il seguente:
subdomain.zendesk.com/api/v2/search.json?query={search_string}
Importante: Assicurati di sostituire "sottodominio" con il sottodominio del tuo account.
L'API di ricerca è molto flessibile e la query può usare qualsiasi cosa indicata nel riferimento Zendesk Search. Nel nostro esempio, poiché stiamo semplicemente cercando dei tag, l'unico parametro che useremo nella stringa di ricerca sarà "tag". Per cercare più tag, è sufficiente aggiungere una virgola tra i tag dopo il parametro "tag". La chiamata ora dovrebbe avere il seguente aspetto:
https://subdomain.zendesk.com/api/v2/search.json?query=tags:escalation_one,escalation_two
Per autenticare la richiesta, assicurati di essere un agente o un amministratore e di aver effettuato l'accesso a Zendesk Support in un'altra scheda del browser.
L'esecuzione di questa chiamata nel browser restituisce un elenco di ticket con entrambi questi tag. Puoi quindi salvare l'output JSON per un uso futuro.
complimenti! Sei arrivato alla fine! L'API è uno strumento potente dai molteplici usi. Da qui puoi iniziare ad approfondire la documentazione diriferimentoe la documentazione per sviluppatori Zendesk.
Avvertenza sulla traduzione: questo articolo è stato tradotto usando un software di traduzione automatizzata per fornire una comprensione di base del contenuto. È stato fatto tutto il possibile per fornire una traduzione accurata, tuttavia Zendesk non garantisce l'accuratezza della traduzione.
Per qualsiasi dubbio sull'accuratezza delle informazioni contenute nell'articolo tradotto, fai riferimento alla versione inglese dell'articolo come versione ufficiale.