Erstellen Sie ein GraphQL-Schema

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

    • Erstellen Sie ein GraphQL-Schema, um Daten für GraphQL-Abfragen verfügbar zu machen.

    Vorbereitungen

    Erforderliche Rolle: graphql_schema_admin oder admin

    Prozedur

    1. Navigieren zu Alle > System-Webservices > GraphQL > GraphQL-APIs.
    2. Wählen Sie Neu.
    3. Füllen Sie diese Felder aus.
      Feld Beschreibung
      Name Name des Schemas.
      Schemanamespace Muss innerhalb des Namens der Anwendung eindeutig sein.
      Anwendung Schreibgeschützte Anwendung, zu der das Schema gehört.
      Anwendungsnamespace Schreibgeschützt. Arbeitet mit dem Schema-Namespace, um Konflikte mit Schemas mit demselben Namen zu vermeiden.
      Aktiv Option zum Aktivieren oder Deaktivieren des GraphQL-Schemas.
      Schema Schemadefinition, die dem GraphQL-SDL-Format entspricht. Muss eine gültige GraphQL-Syntax sein. Andernfalls werden beim Speichern Fehlermeldungen angezeigt, die auf das Syntaxproblem hinweisen.
      Hinweis:
      Die folgenden GraphQL-Funktionen werden nicht unterstützt:
      • Abonnementvorgänge
      • Anwenderdefinierte Skalartypen

      Sie können diese Direktive in Ihrem Schema verwenden:

      @source: 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.

      Dieses Beispiel definiert einen Incident-Objekttyp im -Schema und verwendet ein Resolver-Skript, um den Typ einem GlideRecord aus der Incident-Tabelle zuzuordnen. Mit der Direktive @source werden die Felder innerhalb des Incident-Typs dem Wert oder display_value im Incident-GlideRecord zugeordnet.

      type Incident {
    id: String @source(value: "sys_id.value")
    active: Boolean @source(value: "active.display_value")
    state: String @source(value: "state.display_value")    
    priority: String @source(value: "priority.display_value")
    severity: String
    description: DisplayableString
    resolvedBy: User @source(value: "resolved_by.value")
    openedBy: User @source(value: "opened_by.value")
    child_incidents: String
    opened_at: String
    resolved_at: String
    closed_at: String
    work_notes: String    
    comments: String @source(value: "comments.display_value")
    parent_incident: String
}
    4. Füllen Sie im Abschnitt „Sicherheit“ die Felder aus.
      Feld Beschreibung
      Erfordert Authentifizierung Wählen Sie diese Option aus, um eine Authentifizierung für den Zugriff auf das Schema anzufordern. Durch Deaktivieren dieser Option wird das Schema öffentlich verfügbar gemacht.
      Erfordert ACL-Autorisierung Wählen Sie diese Option aus, um die ACL-Autorisierung für die gesamte API anzufordern. Wählen Sie im Feld ACLs ACLs mit dem GraphQL-Typ aus.

      Um die ACL-Autorisierung nur für bestimmte Pfade zu verwenden, lassen Sie diese Option deaktiviert, und geben Sie die Ebene an, für die ACLs ausgewertet werden sollen, im Feld Pfad-ACL-Tiefe.
      Erfordert SNC-intern Wählen Sie diese Option aus, wenn das Schema die interne SNC-Rolle erfordert. Diese Option wird nur angezeigt, wenn das Plugin Explicit Roles (com.glide.explicit_roles) aktiviert ist.
      Pfad-ACL-Tiefe Geben Sie die Ebene der GraphQL-API an, auf die ACLs angewendet werden sollen. Wenn Sie die Pfadtiefe auf 3 oder niedriger festlegen, werden weniger Ressourcen verbraucht und die Ausgabe von Abfrageantworten erleichtert.

      Um die für den Pfad zu verwendenden ACLs anzugeben, müssen Sie eine ACL vom Typ „GraphQL“ erstellen und den genauen API-Pfad beginnend mit dem Schema-Namespace im Feld Name hinzufügen. Beispiel: /<planet> /<findAll> /<name> . Platzhalter werden nicht unterstützt. Weitere Informationen finden Sie unter Configure an ACL rule.

      Hinweis:
      Das Feld ACLs gilt für die gesamte API und ist unabhängig von den ACLs, die auf bestimmte Pfade angewendet werden.
      ACLs Wählen Sie ACLs mit dem GraphQL-Typ aus, mit denen eingehende Abfragen überprüft werden sollen. Die von Ihnen ausgewählten ACLs gelten für die gesamte API. Diese Option wird nur angezeigt, wenn Erfordert ACL-Autorisierung ausgewählt ist.
      Hinweis:
      Die API gibt eindeutige Fehlermeldungen an Anwender zurück, die keinen Zugriff auf ein Schema haben oder nicht authentifiziert sind, wenn die API für den Zugriff eine Authentifizierung erfordert.
    5. Speichern Sie das Formular.
    6. Wahlweise: Erstellen Sie ein Resolver-Skript, um zu definieren, welchen Wert das Schema zurückgibt, wenn eine Komponente ein Feld abfragt.
      Wenn Sie keinen Resolver für ein Feld definieren, gibt die Abfrage einen beliebigen übereinstimmenden Feldwert aus dem übergeordneten Objekttyp zurück. Angenommen, Sie haben einen Objekttyp „Incident“ in Ihrem Schema mit einem Arbeitsnotizfeld. Der Objekttyp „Incident“ verfügt über einen Resolver, der einem GlideRecord aus der Incident-Tabelle zugeordnet ist. Wenn Sie keine Resolver-Zuordnung für das Arbeitsnotizfeld erstellen, durchsucht das System die Datenquelle des übergeordneten Objekts (GlideRecord aus der Incident-Tabelle) nach einem Arbeitsnotizfeld und weist den zugehörigen Wert zu.
      1. Wählen Sie die Registerkarte Geskriptete GraphQL-Resolver und anschließend Neu.
      2. Füllen Sie das Formular aus.
        Feld Beschreibung
        Name Name des Resolvers
        Schema Schreibgeschützter Schema-Namespace.
        Anwendung Schreibgeschützte Anwendung, zu der das Schema gehört.
        Skript Definieren Sie den Wert, der zurückgegeben wird, wenn das Feld abgefragt wird. Für das globale env- Objekt verfügbare Funktionen:
        • getArguments(): Gibt die Argumente des vorherigen Felds zurück.
        • getSource(): Gibt das übergeordnete Objekt zurück.

        Dieses Skript hat Zugriff auf GlideRecord.

        In diesem Beispiel wird ein Datensatz aus der Tabelle „Benutzer “ zurückgegeben, wenn das zugehörige Feld abgefragt wird:

        (function process(/*ResolverEnvironment*/ env) {

    var userid = env.getArguments().id != null ? env.getArguments().id : env.getSource();
    var now_GR = new GlideRecord('sys_user');
    gr.addQuery('sys_id', userid);
    gr.queryO;
    return gr;

})(env);
      3. Wählen Sie Absenden.
    7. Wahlweise: Definieren Sie die Typ-Resolver für Ihr Schema, um Schnittstellen und Vereinigungen in konkrete Typen aufzulösen.
      1. Wählen Sie die Registerkarte Resolver für geskriptete GraphQL-Typen und anschließend Neu.
      2. Füllen Sie das Formular aus.
        Feld Beschreibung
        Schema Schreibgeschützter Schema-Namespace.
        Typ Die im Schema definierte Schnittstelle oder der Verbindungstyp.
        Anwendung Schreibgeschützte Anwendung, zu der das Schema gehört.
        Skript Definieren Sie den für Vereinigungs- und Schnittstellentypen zurückgegebenen Wert. Für das globale env- Objekt verfügbare Funktionen:
        • 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.

        Dieses Skript hat Zugriff auf GlideRecord.
      3. Wählen Sie Absenden.
    8. Wahlweise: Ordnen Sie die Resolver- und Typ-Resolver-Datensätze Feldern im Schema zu.
      Diese Zuordnung teilt dem System mit, welcher Wert zurückgegeben werden soll, wenn eine Komponente ein Feld abfragt.
      1. Wählen Sie die Registerkarte Zuordnungen des geskripteten GraphQL-Resolvers und anschließend Neu.
      2. Füllen Sie das Formular aus.
        Feld Beschreibung
        Pfad Pfad zu dem Feld im Schema, das Sie zuordnen möchten.
        Resolver Zum Definieren der vom Feld zurückgegebenen Daten zu verwendender Resolver.
        Anwendung Schreibgeschützte Anwendung, zu der das Schema gehört.
        Schema Schreibgeschützter Schema-Namespace.
      3. Wählen Sie Absenden.