Fragen Sie Datensatzdaten mit dem GraphQL-API-Framework ab

  • Freigeben Version: Xanadu
  • Aktualisiert 1. August 2024
  • 3 Minuten Lesedauer

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

    Sie können beispielsweise eine Komponente erstellen, die die mit einem SLA verknüpften Fälle anzeigt. Sie können Next Experience UI Framework verwenden, um die benötigte Komponente zu entwickeln und auf Falldaten von der Plattform zuzugreifen, indem Sie ein GraphQL-Schema erstellen, das Daten in der Falltabelle definiert.

    Weitere Informationen zum Entwickeln von Komponenten finden Sie unter Komponenten für den Arbeitsbereichentwickeln.

    Vorteile von GraphQL

    GraphQL ist eine Web-Abfragesprache, die für die clientseitige Entwicklung optimiert ist. Mit GraphQL mit Skript können Sie:

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

    Was Sie wissen müssen, bevor Sie beginnen

    Bevor Sie mit der Erstellung benutzerdefinierter GraphQL-APIs beginnen, vergewissern Sie sich:

    • GraphQL-Wissen zum Erstellen eines Schemas.
    • JavaScript-Kenntnisse zum Definieren des API-Verhaltens.
    • Allgemeine Kenntnisse über Webkomponentenkonzepte.
    • Eine anwenderdefinierte Arbeitsbereich -Komponente zum Verwenden von Datensatzdaten.
    • Verständnis des ServiceNow -Datenmodells, das im Schema verfügbar gemacht werden soll.
    • GlideRecord-Wissen zum Zuordnen von Feldern zum Aufzeichnen von Daten in Ihren Resolver-Skripts.

    GraphQL-Übersicht

    Das Erstellen einer geskripteten GraphQL-API umfasst folgende Teile:

    GraphQL-Schemadefinitionssprache (SDL)
    Definieren Sie die Struktur und den Datentyp der Felder, die in einer GraphQL-Abfrage verfügbar sind. Sie können die SDL mithilfe des Skriptfelds Schema in der Tabelle der geskripteten GraphQL-Schemas [sys_graphql_schema] definieren. Die SDL unterstützt nur Abfrage- und Mutationsvorgä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 Geskriptete GraphQL-Resolver im Formular Geskriptete GraphQL-Schemas definieren.
    TypeResolver
    Lösen Sie Schnittstellen und Vereinigungen in konkrete GraphQL-Typen auf. Sie können beispielsweise eine Vereinigung zwischen einem Incident -Typ und einem Problemtyp definieren. Verwenden Sie das typeresolver-Skript, um zu definieren, wann welche zurückgegeben werden sollen. Sie können die Typeresolver in der zugehörigen Liste Geskriptete GraphQL-Typeresolver im Formular Geskriptete GraphQL-Schemas definieren.
    Resolver-Zuordnungen
    Ordnen Sie Resolver den Feldern im Schema zu. Sie können Resolver-Zuordnungen in der zugehörigen Liste Geskriptete GraphQL-Resolver-Zuordnungen im Formular Geskriptete GraphQL-Schemas definieren.

    Weitere Informationen zur GraphQL-Abfragesprache finden Sie auf der 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 dem GraphQL-Explorer.

    Einschränkungen

    Die folgenden GraphQL-Funktionen werden nicht unterstützt:

    • Abonnementvorgänge
    • Anwenderdefinierte Skalartypen

    Introspektion

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

    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 einzigen Anwendung haben.

    Wenn Sie Daten abfragen, müssen Sie beide Namespaces in Ihre Abfrage aufnehmen. Die folgende Abfrage sucht beispielsweise nach Daten mit den folgenden Namespaces:

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

    Richtlinien und globale Funktionen

    @source-Schemadirektive

    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 auflöst, anstelle des übergeordneten Objekts.

    Verwenden Sie die Direktive @source in Ihrem Schemaskript.

    @defer-Abfragedirektive
    Verschieben Sie die Verarbeitung eines GraphQL-Fragments auf einen späteren Zeitpunkt in der Abfrage. Verwenden Sie diese Abfragerichtlinie, um die Rückgabe von Daten für langsam reagierende Felder in einem Fragment zu verzögern. Streamen Sie die Feldergebnisse des zurückgestellten Fragments als mehrteilige Antwort.
    Hinweis:
    Um die Direktive @defer zu verwenden, muss Ihr GraphQL-Client mehrteilige/gemischte HTTP-Header akzeptieren. Legen Sie beispielsweise die HTTP-Header auf „Akzeptieren: mehrteilig/komisch;“fest. grenze="-" .

    Verwenden Sie die Direktive @defer, um die Interaktionszeit des Benutzers zu verkürzen. Vermeiden Sie es, diese Abfragerichtlinie 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 für das globale env- Objekt verfügbar.

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

    Verwenden Sie im Resolver-Skript.

    Typeresolver-Funktionen

    Diese Funktionen sind für das globale env- Objekt verfügbar.

    • 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.

    Verwenden Sie im typeresolver-Skript.

    Demo-Anwendung

    Um ein Demo-GraphQL-Schema für den bezahlten Kalender mit Mutationen und Abfragen anzuzeigen, aktivieren Sie das Plugin „GraphQL Framework Demo Application“ (com.glide.graphql.framework.demo).