API GraphQL

Introduzione

In addition to Zammad's REST API, you can fetch, manipulate and create data via the powerful and open-source GraphQL API too.

This documentation isn't intended to cover everything about GraphQL. It should give you a basic understanding about how you can fetch and create/manipulate data to build upon. For a comprehensive guide, have a look at GraphQL's documentation.

GraphQL è usato da molti servizi web, anche grandi. È diventato una sorta di standard del settore.

Recuperare lo schema GraphQL di Zammad (chiamato introspezione) abilita l'autocompletamento e la convalida lato client.

Per iniziare

Seguendo i passaggi successivi sarai in grado di inviare con successo una semplice richiesta e ricevere dati.

Client

Per inviare richieste e ricevere risposte, hai bisogno di un client API. Se già lavori con le API, puoi saltare questa sezione. Se sei nuovo sull’argomento, cerca un client che si adatti alle tue esigenze. A seconda del tuo sistema operativo, potresti avere diverse opzioni. Alcuni esempi di client popolari con supporto GraphQL sono:

• Bruno
• Insomnia
• Postman

Autenticazione

Se non già presente, crea un token nel profilo Zammad che vuoi utilizzare come utente API. A seconda di ciò che vuoi ottenere tramite API, imposta le autorizzazioni di conseguenza.

Assicurati di copiarlo prima di chiudere la finestra di dialogo perché non potrai visualizzarlo di nuovo.

Prepare your client

Apri il tuo client API e configuralo.

• Aggiungi il tuo token da Zammad come bearer token.
• Crea una richiesta e aggiungi il tuo dominio Zammad con il suffisso /graphql, ad esempio https://fastlane.inc/graphql.
• Recupera lo schema GraphQL di Zammad dall'introspezione o caricalo da file.

WARNING

L’introspezione dello schema è abilitata per Zammad nell’ambiente di sviluppo. Per abilitarla nei sistemi di produzione, imposta la variabile d’ambiente ZAMMAD_GRAPHQL_INTROSPECTION su true. Farlo aumenta la potenziale superficie di attacco ed è sconsigliato.

Create a request

Tutte le richieste e risposte sono in formato JSON. Ciò significa che tutte le informazioni devono essere incapsulate.

Diamo un'occhiata a una richiesta per recuperare informazioni da Zammad. Tale richiesta inizia con.

Esempio di base per recuperare gli utenti con il loro nome e cognome:

query userName (
  $userId: ID!
  ) {
  user(userId: $userId) {
    firstname
    lastname

Il $userId dalla riga 2 definisce una variabile usata come ID. Nella sezione delle variabili.

{
  "userId": "gid://zammad/User/2"
}

Il valore sopra è nel formato ID globale dell’implementazione GraphQL di Zammad. A seconda del tipo di oggetto con cui vuoi lavorare, sostituisci User con un altro oggetto come Ticket, Organization, Group, ecc. Zammad si aspetta un valore numerico come ID.

A partire dalla riga 4 nel blocco di codice sopra c'è la richiesta vera e propria. Questo semplice esempio.

Per creare o modificare dati, sostituisci query con mutation nel corpo della richiesta.

Esempi

Gli esempi usano variabili per i diversi tipi di oggetto. Assicurati di impostarla quando usi.

query ticketDetails (
  $ticketId: ID!
  ) {
  ticket(ticketId: $ticketId) {
    title
    checklist {
      items {
        text
        checked
      }
    }
    tags
    state {
      name
    }
    escalationAt
  }
}

Appendice

Global ids

INFO

Sostituisci {ID} con un valore numerico.

• gid://zammad/Ticket/{ID}
• gid://zammad/User/{ID}
• gid://zammad/Organization/{ID}