Per usare l’API Chat negli account Support+Chat e Chat di fase 4 , devi generare un token di accesso OAuth per autenticare le richieste API. L’autenticazione di base non è supportata. Tuttavia, la prima generazione di un token può creare confusione, quindi questa esercitazione fornisce esempi dettagliati su come generare un token manualmente. Al termine, dovresti avere un token che puoi usare nelle richieste API di Chat per leggere e scrivere dati.
Se stai creando un’applicazione, dovresti incorporare la funzionalità di generazione dei token nell’app per automatizzare il processo.
Esistono due modi per creare un token di accesso per l’API Chat: un modo più rapido e comodo per testare gli ambienti (usando il flusso di concessione "implicito") e uno più lungo e più formale per gli ambienti di produzione (usando la concessione "Codice di autorizzazione" flusso). Questo tutorial tratta entrambi.
Condizioni
Questa esercitazione è destinata agli account Chat integrati a cui sono state applicate tutte le modifiche a cui si fa riferimento nell’articolo precedente. Attualmente è in fase di implementazione graduale, quindi alcuni account potrebbero richiederlo prima di altri. Se non sei sicuro che il tuo account abbia ricevuto tutte le modifiche, non esitare a contattare il nostro team di assistenza che può confermare per te.
Nota: Un effetto collaterale delle modifiche all'account è che i token OAuth dovranno essere ricreati. Se completi questo tutorial prima che le modifiche abbiano raggiunto il tuo account, dovrai ripetere i passaggi in seguito.
Procedura
Il flusso di concessione "implicita" di OAuth include i passaggi seguenti:
- Crea il client API OAuth
- Completa il flusso di concessione implicita OAuth per ottenere il token usando le informazioni del passaggio 1
Crea il client API OAuth
Prima di tutto, abbiamo bisogno di un client API. Seleziona Zendesk Chat > Account > API e SDK e fai clic sul pulsante Aggiungi client API . Inserisci il nome del cliente e dell’azienda di tua scelta e l’URL di reindirizzamentohttp://localhost:8080
. Dovrebbe assomigliare a questo:
Fai clic su Crea client API per completare la configurazione. Verrà mostrato un popup con l’ID e il segreto del client. Molto importante: Il segreto del client viene mostrato una sola volta, quindi prendine nota per un uso futuro. Sarà simile a questo:
Ora che il nostro client API è pronto per l’uso, prendi nota del tuo ID client e del segreto del client prima di fare clic su OK. Ora siamo pronti per completare il flusso di concessione OAuth.
Completa il flusso di concessione implicita OAuth per ottenere il token
Questo approccio usa il flusso di concessione "implicito" OAuth. Un approccio alternativo consiste nell'usare il flusso di concessione del "Codice di autorizzazione" OAuth (illustrato nella sezione successiva). Se viene eseguito manualmente, questo approccio richiede meno passaggi ed è più pratico del flusso di concessione del codice di autorizzazione mostrato in seguito.
1. Segui il passaggio “Creazione del client API OAuth” qui sopra
2. Raccogli queste informazioni dal client OAuth
- ID cliente: CLIENT_ID
- Il tuo sottodominio Zendesk
3. Formatta l’URL seguente con i tuoi CLIENT_ID e SUBDOMAIN, incollalo in una nuova scheda del browser e premi Invio.
https://www.zopim.com/oauth2/authorizations/new?response_type=token&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN
NOTE:
- Se il client Chat OAuth ha un solo valore di URL di reindirizzamento, l’invio di un valore di reindirizzamento_uri è facoltativo. Per impostazione predefinita, il sistema userà il valore di un URL di reindirizzamento del client OAuth.
- Se il client OAuth ha più di un valore di URL di reindirizzamento, è necessario un valore di reindirizzamento_uri. Se viene passato un valore di reindirizzamento_uri, deve essere codificato in URL. Nell’esempio qui sopra, il parametro di reindirizzamento facoltativo sarebbe: redirect_uri=http%3A%2F%2Flocalhost%3A8080
4. Verrà effettuata una chiamata, che potrebbe chiederti di accedere e di selezionare “Consenti” per generare il token.
Se la chiamata ha esito positivo, il campo dell’indirizzo del browser conterrà il nuovo token OAuth (restituito come valore access_token).
Nonostante il messaggio di errore che appare nella finestra principale del browser, se il campo URL del browser restituisce “token_accesso”, ha funzionato.
Ecco una demo del workflow:
Un modo alternativo e più lungo per generare il token
Questi passaggi creano un token proprio come la sezione precedente, ma illustra il flusso di concessione del "Codice di autorizzazione" OAuth. Prendi nota dei dettagli del tuo client OAuth, che saranno usati qui sotto.
Verranno usati dei segnaposto al posto dei dati reali; tieni presente che il segreto del tuo client OAuth deve essere trattato con la massima sicurezza in quanto è essenzialmente una password per il tuo account Chat.
- ID cliente:
CLIENT_ID
- Segreto client:
CLIENT_SECRET
- URI reindirizzamento:
http://localhost:8080
- Sottodominio: il tuo sottodominio Zendesk; es., se il tuo account è su
niall.zendesk.com
, questo valore èniall
- Codice di autorizzazione: non ancora disponibile
1. Prepara il primo URL
Qui creeremo un URL per richiedere un codice di autorizzazione. Dovrai accedere ahttps://www.zopim.com/oauth2/authorizations/new
e aggiungi alcuni parametri di query per trasmettere alcune delle informazioni indicate sopra. Questa volta abbiamo bisogno di:
-
response_type
: sarà sempre cosìcode
-
redirect_uri
: dove verremo reindirizzati dopo aver concesso l’accesso,http://localhost:8080
per il nostro tutorial -
client_id
: specifici per te, come annotato in precedenza -
scope
: sceglieremo quale accesso avrà questo tokenread
ewrite
- Includi anche l’ambito “chat” se usi il token in relazione all’API Chat Conversations.
- Includi anche l’ambito “chat” se usi il token in relazione all’API Chat Conversations.
-
subdomain
: il tuo sottodominio Zendesk
Mettendo insieme questi dati e la codifica URL, otterrai un URL finale simile al seguente:
https://www.zopim.com/oauth2/authorizations/new?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN
con CLIENT_ID
e SUBDOMAIN
essendo l’unica differenza per il tuo URL.
2. Prepara la chiamata cURL
Prima di visitare effettivamente quell’URL, creiamo la chiamata cURL che verrà eseguita dopo. Questa volta avremo bisogno di quanto segue:
-
grant_type
: sarà sempre cosìauthorization_code
-
code
: otterremo dopo aver permesso l’accesso dall’URL -
client_id
: l’ID client -
client_secret
: il segreto del client -
redirect_uri
: come l’ultimo passaggio - http://localhost:8080 -
scope
: come l’ultimo passaggio -read
ewrite
Mettendo insieme tutto questo, otteniamo un comando che dovrebbe assomigliare a:
curl https://www.zopim.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \ -X POST
Ricorda: avresti già dovuto farlo CLIENT_ID
e CLIENT_SECRET
ora, ma non l’abbiamo fatto AUTH_CODE
ancora.
3. Ottieni il codice di autorizzazione
Ora seleziona l’URL generato nel passaggio 1. Vedrai una pagina come questa:
Fai clic su Consenti per concedere l’accesso e verrai reindirizzato all’URL di reindirizzamento. Sembrerà una pagina interrotta, ma l’importante è controllare l’URL per vedere qual è il codice di autorizzazione, ovvero tutto ciò che è dopo ?code=
Copia quel codice e siamo pronti per il passaggio finale. Il codice di autorizzazione è valido solo per un breve periodo di tempo. Se attendi più di qualche minuto, potrebbe essere necessario ripetere il passaggio precedente per ottenere un nuovo valore di codice.
4. Effettua la chiamata cURL per ottenere il token
Facendo riferimento alla nostra chiamata cURL creata nel passaggio 2, che assomiglia a questo
curl https://www.zopim.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \ -X POST
sostituireAUTH_CODE
con il codice del passaggio 3 ed esegui il comando da un’applicazione terminale. Riceverai una risposta sotto forma di oggetto JSON come questa:
{ "access_token": "TOKEN", "token_type": "Bearer", "refresh_token": "REFRESH_TOKEN", "scope": "read write" }
5. Prova il nuovo token
È sempre una buona idea provare per confermare che ha funzionato come previsto, quindi possiamo farlo ora. La chiamata più facile da effettuare è semplice GET
a /api/v2/chats
per vedere le informazioni del tuo account:
curl https://www.zopim.com/api/v2/chats -H "Authorization: Bearer TOKEN"
sostituzione TOKEN
con quello recuperato al passaggio 4.
Ulteriori informazioni
Client_type riservato
Le sezioni precedenti illustrano il tipo di concessione "Implicito" e il tipo di concessione "Codice di autorizzazione". Esistono altri due tipi di concessione Zendesk Chat supportati: "password" e "client_credentials". Questi sono descritti più dettagliatamente nella documentazione di riferimento in Tipi di sovvenzioni riservate.
Per le chiamate API usate da amministratori e agenti per rapporti sulle metriche, potrebbe essere preferibile ottenere un token OAuth con uno di questi tipi di concessione. Dovrai impostare il client_type
come “riservato”. Per impostazione predefinita, questo valore è “public”. Questa operazione può essere eseguita solo tramite l’API e procede come segue:
1. Ottieni l’ID client
Per prima cosa, abbiamo bisogno dell’ID del tuo nuovo cliente. Puoi ottenerlo usando il tuo nuovo token, con la chiamata seguente:
curl https://www.zopim.com/api/v2/oauth/clients -H "Authorization: Bearer TOKEN"
che mostrerà tutti i tuoi clienti. Puoi averne solo uno, ma se ne hai molti, dovresti scegliere quello che desideri aggiornare e annotarne l’ID.
2. Aggiorna client_type
Ora che disponi dell’ID del client, puoi eseguire la seguente chiamata cURL per aggiornare il file client_type
proprietà:
curl https://www.zopim.com/api/v2/oauth/clients/ID -d '{"client_type": "confidential"}' \
-X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"
Una volta completata questa operazione, il token può essere usato per gli endpoint con limitazioni.
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.