Datensatzdaten mit dem GraphQL-API-Framework abfragen

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 3 Minuten Lesedauer

    • Erstellen Sie eine anwenderdefinierte GraphQL-API, um Datensatzdaten aus einer Komponente oder einem Drittparteisystem abzufragen.

    Sie können beispielsweise eine Komponente erstellen, die die Fälle anzeigt, die einem SLA zugeordnet sind. Sie können verwenden Next Experience UI FrameworkUm die benötigte Komponente zu entwickeln und auf Falldaten von der Plattform zuzugreifen, indem ein GraphQL-Schema erstellt wird, das Daten in der Falltabelle definiert.

    Weitere Informationen zur Entwicklung von Komponenten finden Sie unter Entwickeln von Komponenten für den Arbeitsbereich .

    Vorteile von GraphQL

    GraphQL ist eine Webabfragesprache, die für die clientseitige Entwicklung optimiert ist. Mit geskriptetem GraphQL können Sie:

    • Erkennen Sie Felder und Objekte, die für die Abfrage durch Introspektion verfügbar sind.
    • Fragen Sie die genauen Daten ab, die Sie von einer Komponente benötigen.
    • Verwalten Sie mehrere mögliche Abfragen über eine einzelne API im Gegensatz zu mehreren Endpunkten für eine REST-Anforderung.
    • Integrieren Sie in Drittparteisysteme, indem Sie das Schema öffentlich machen.
    • Generieren Sie die GraphQL-Abfrage aus Ihrer Komponente, und verarbeiten Sie die Antwort.

    Was Sie wissen sollten, bevor Sie beginnen

    Bevor Sie mit der Erstellung anwenderdefinierter GraphQL-APIs beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

    • GraphQL-Wissen zum Erstellen eines Schemas.
    • JavaScript-Wissen zum Definieren des API-Verhaltens.
    • Allgemeines Wissen über Webkomponentenkonzepte.
    • Ein anwenderdefinierter ArbeitsbereichKomponente zum Verbrauchen von Datensatzdaten.
    • Verständnis von ServiceNowDatenmodell, das Sie im Schema angeben möchten.
    • GlideRecord-Wissen, um Felder zuzuordnen, um Daten in Ihren Resolver-Skripts aufzuzeichnen.

    GraphQL-Übersicht

    Das Erstellen einer geskripteten GraphQL-API enthält diese Teile:

    GraphQL-Schemadefinitionssprache (SDL)
    Definieren Sie die Struktur und den Datentyp von Feldern, die in einer GraphQL-Abfrage verfügbar sind. Sie können SDL mit definieren Schema Skriptfeld in der Tabelle „GraphQL-Skriptschemata“ [sys_graphql_Schema]. SDL unterstützt nur Abfrage- und Mutation-Vorgänge.
    Resolver
    Definieren Sie die von jedem Feld zurückgegebenen Daten. Sie können die Resolver für jedes Feld in der zugehörigen Liste „GraphQL-Skriptlöser“ im Formular „GraphQL-Skriptschemata“ definieren.
    Typeresolver
    Lösen Sie Schnittstellen und Verbindungen in konkrete GraphQL-Typen auf. Sie können beispielsweise eine vereinigung zwischen definieren Incident Geben Sie und ein ein Problem Typ. Verwenden Sie das typeresolver-Skript, um zu definieren, wann welche zurückgegeben werden soll. Sie können die Typeresolver in der zugehörigen Liste GraphQL-Skripttyperesolver im Formular GraphQL-Skriptschemata definieren.
    Resolver-Zuordnungen
    Ordnen Sie Resolver Feldern im Schema zu. Sie können Resolver-Zuordnungen in der zugehörigen Liste GraphQL-Skriptlöserzuordnungen im Formular „GraphQL-Skriptschemata“ definieren.

    Weitere Informationen zur GraphQL-Abfragesprache finden Sie unter GraphQL-Website .

    Um Abfragen an Ihre GraphQL-APIs zu testen, können Sie den GraphQL-Explorer verwenden, ein integriertes GraphQL-Testtool. Weitere Informationen finden Sie unter Testen Sie GraphQL-APIs mit GraphQL Explorer.

    Einschränkungen

    Die folgenden GraphQL-Funktionen werden nicht unterstützt:

    • Abonnementvorgänge
    • Anwenderdefinierte Skalartypen

    Introspektion

    Standardmäßig sind introspektive Abfragen in Ihren anwenderdefinierten Schemas nicht aktiviert. Informationen zum Aktivieren der Introspektion finden Sie unter Aktivieren Sie introspektive Abfragen für GraphQL-Schemas.

    Namespaces

    GraphQL-APIs haben zwei verschiedene Namespaces:

    Anwendungsnamespace
    Der Namespace für die anwenderdefinierte Anwendung. Weitere Informationen zu Anwendungsnamespaces finden Sie unter Anwendungsbereich .
    Schemanamespace
    Der Namespace für das Schema, um sicherzustellen, dass alle Abfragen eindeutig sind. Sie können mehrere Schema-Namespaces in einer einzelnen Anwendung haben.

    Beim Abfragen von Daten müssen Sie beide Namespaces in Ihre Abfrage einschließen. Die folgende Abfrage sucht beispielsweise nach Daten mit den folgenden Namespaces:

    • Anwendungsnamespace: X_Graph_scope
    • Schema-Namespace: Planet 
    query {
  x_graph_scope {
    planet {
      findAll {
        name
        mass
        distance
      }
    }
  }
}

    Anweisungen und globale Funktionen

    @Quelle Schemaanweisung

    Ordnet ein GraphQL-Feld dem Wert einer Eigenschaft des übergeordneten Objekts zu. Wenn das Feld über ein separates Resolver-Skript verfügt, verwendet das System den Datensatz, in den es aufgelöst wird, anstelle des übergeordneten Objekts.

    Verwenden Sie @Quelle anweisung in Ihrem Schemaskript.

    @Zurückstellen Abfrageanweisung
    Verschieben Sie die Verarbeitung eines GraphQL-Fragments bis zu einem späteren Zeitpunkt in der Abfrage. Verwenden Sie diese Abfrageanweisung, um die Rückgabe von Daten für Felder mit langsamer Antwort in einem Fragment zu verzögern. Streamen Sie die Feldergebnisse des zurückgestellten Fragments als mehrteilige Antwort.
    Hinweis:
    Zur Verwendung von @Zurückstellen anweisung, muss Ihr GraphQL-Client mehrteilige/gemischte HTTP-Header akzeptieren. Legen Sie beispielsweise die HTTP-Header auf fest Akzeptieren: Mehrteilig/gemischt; Grenze=„-“ .

    Verwenden Sie @Zurückstellen richtlinie zur Verbesserung der Zeit bis zur Interaktion des Anwenders. Vermeiden Sie es, diese Abfrageanweisung wahllos anzuwenden, da dies auch zu Leistungsverschlechterungen führen kann. Führen Sie Leistungstests durch, um zu bestimmen, welche Felder für eine bessere Leistung zurückgestellt werden können.

    Resolver-Funktionen

    Diese Funktionen sind global verfügbar umgebung Objekt.

    • GetArguments() : Gibt die Argumente des vorherigen Felds zurück.
    • GetSource() : Gibt das übergeordnete Objekt zurück.

    In Ihrem Resolver-Skript verwenden.

    Typeresolver-Funktionen

    Diese Funktionen sind global verfügbar umgebung Objekt.

    • GetArguments() : Gibt die Argumente des vorherigen Felds zurück.
    • GetObject() : Gibt das übergeordnete Objekt zurück.
    • GetTypeName() : Gibt den Namen der Schnittstelle oder des vereinigungstyps zurück.

    In Ihrem Typeresolver-Skript verwenden.

    Demo-Anwendung

    Um ein Demo-GraphQL-PTO-Kalenderschema mit Mutationen und Abfragen anzuzeigen, aktivieren Sie das GraphQL-Framework-Demoanwendung-Plugin (com.glide.graphql.framework.demo).