GraphQL API

Einführung

Neben der REST API von Zammad können Sie Daten auch über die leistungsstarke und quelloffene GraphQL API abrufen, bearbeiten und erstellen.

Diese Dokumentation ist nicht dazu gedacht, alles über GraphQL abzudecken. Sie soll Ihnen ein grundlegendes Verständnis dafür vermitteln, wie Sie Daten abrufen und erstellen/ändern können, um darauf aufzubauen. Eine umfassende Anleitung finden Sie in der [GraphQL-Dokumentation] (https://graphql.org/learn/).

GraphQL wird von vielen, auch großen, Webdiensten verwendet. Aufgrund seiner Effizienz und seiner Funktionen wurde es zu einer Art Industriestandard. Sie können genau die Daten anfordern, die Sie benötigen, wodurch unnötige Datenübertragungen und die Suche nach der Nadel im Heuhaufen minimiert werden.

Das Abrufen des GraphQL-Schemas von Zammad (Introspection genannt) ermöglicht eine Autovervollständigung und Logikprüfung in Ihrem Client, während Sie eine Anfrage erstellen.

Erste Schritte

Wenn Sie die folgenden Schritte befolgen, können Sie erfolgreich eine einfache Anfrage senden und Daten von Zammad empfangen.

Clients

Um Anfragen zu senden und Antworten zu erhalten, benötigen Sie einen API Client. Wenn Sie bereits mit APIs zu tun haben, können Sie diesen Abschnitt überspringen. Wenn Sie neu auf dem Gebiet sind, suchen Sie nach einem Client, der Ihren Anforderungen entspricht. Je nach Betriebssystem haben Sie unterschiedliche Möglichkeiten. Einige Beispiele für beliebte Clients mit GraphQL-Unterstützung sind:

• Bruno
• Insomnia
• Postman

Authentifizierung

Falls noch nicht vorhanden, erstellen Sie ein Token im Zammad-Profil, das Sie als API-Benutzer verwenden möchten. Je nachdem, worauf Sie per API zugreifen wollen, legen Sie die Berechtigungen entsprechend fest.

Achten Sie darauf, dass Sie es vor dem Schließen des Dialogs kopieren, da Sie es nicht noch einmal sehen können. Falls Sie es versäumt haben, erstellen Sie einfach ein neues Token.

Client vorbereiten

Öffnen Sie Ihren API Client und richten Sie ihn ein.

• Fügen Sie Ihr Token von Zammad als Bearer-Token hinzu.
• Erstellen Sie einen Request und fügen Sie Ihre Zammad-Domain mit dem Suffix /graphql hinzu, z.B. https://fastlane.inc/graphql.
• Rufen Sie das GraphQL-Schema von Zammad aus der Introspection ab oder laden Sie es aus einer Datei.

Klicken Sie auf Details, um einen Screencast zu sehen, der die grundlegenden Schritte mit dem Client Bruno zeigt.

Details

Einen Request erstellen

Alle Requests und Responses sind im JSON-Format. Das bedeutet, dass alle Informationen in Klammern gekapselt sein und eine hierarchische Struktur haben müssen.

Werfen wir einen Blick auf einen Request zum Abrufen von Informationen aus Zammad. Eine solche Anfrage beginnt mit der Zeichenkette query, gefolgt von dem Objekt, zu dem Sie Informationen abrufen möchten.

Einfaches Beispiel zum Abrufen von Benutzern mit ihrem Vor- und Nachnamen:

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

Die $userId aus Zeile 2 definiert eine Variable, die als ID verwendet wird. Geben Sie im Variablenabschnitt Ihres Clients den Wert für diese Variable an. In diesem Beispiel sieht der Variablen-Abschnitt wie folgt aus:

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

Der obige Wert ist im Global ID-Format der GraphQL-Implementierung von Zammad. Je nachdem, mit welchem Objekttyp Sie arbeiten möchten, ersetzen Sie User durch ein anderes Objekt wie Ticket, Organization, Group, etc. Zammad erwartet einen numerischen Wert als ID.

Die eigentliche Anfrage beginnt mit Zeile 4 im obigen Codeblock. In diesem einfachen Beispiel werden lediglich die Attribute firstname und lastname von dem Benutzer mit der ID 2 abgerufen.

Klicken Sie auf Details, um einen Screencast zu sehen, der einen einfachen Request unter Verwendung einer Variable in Bruno zeigt.

Details

Um Daten zu erstellen oder zu ändern, ersetzen Sie query durch mutation im Request.

Beispiele

Die Beispiele verwenden Variablen für die verschiedenen Objekttypen. Stellen Sie sicher, dass Sie diese bei der Verwendung der Beispiele setzen.

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

Anhang

Global IDs

INFO

Ersetzen Sie {ID} durch einen numerischen Wert.

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