• Zuletzt bearbeitet am: 25 July 2022

Einführung von GraphQL

Einleitung

GraphQL ist eine offene Spezifikation für eine API-Abfragesprache (daher die "QL" -Referenz), mit der Sie Ihre Integrationen reaktionsschneller als je zuvor machen können, indem Sie die Möglichkeit haben, die benötigten Daten anzufordern und nicht mehr. GraphQL kann auch die Anzahl der Anrufe und der damit verbundenen Hin- und Rückfahrten reduzieren, indem alle benötigten Ressourcen in einem einzigen oder weniger Anrufen abgerufen werden. 

Kurz gesagt, GraphQL wirkt sich messbar auf Ihre Integrationen aus, indem es den Bandbreiten-Overhead aufgrund der Antwortnutzlastgrößen und der Anzahl der getätigten Anrufe reduziert.

Hinweis

API-Filter sind nach wie vor eine Schlüsselfunktion, die weiterhin verwendet werden sollte, um die Ressourcennutzung zu reduzieren, wenn REST-API-GET-Aufrufe durchgeführt WERDEN.

OIDC/OAuth2

Coupas GraphQL-Abfrageendpunkt wird über OIDC authentifiziert und die Autorisierung wird über OAuth2-Bereiche abgewickelt.  Wählen Sie „Konfiguration“ > „Integrationen“ > „Oauth2-/OpenID-Connect-Clients“ und klicken Sie auf die Schaltfläche „Erstellen“ (oder wählen Sie „/oauth2/clients/new“), um einen OIDC-Client mit den entsprechenden OAuth2-Lesebereichen für Ihre Abfragen zu erstellen (das Schreiben wird noch nicht unterstützt). Derzeit unterstützen wir nur Arten von Kundenanmeldeinformationen.

create-client.png

Verwenden Sie nach dem Erstellen eines OIDC-Clients die OIDC-Clientinformationen, um ein Zugriffstoken abzurufen. Wir werden nicht darauf eingehen, wie man ein Zugriffstoken erhält. Wenden Sie sich an Ihren Coupa-Administrator oder Coupa-Support, um zu erfahren, wie Sie ein Zugriffstoken mit Ihren OIDC-Clientinformationen abrufen können.

GraphQL-Clients

Nachdem Sie ein Zugriffstoken haben, stehen Ihnen viele Tools zur Verfügung, mit denen Sie GraphQL-Anfragen an Coupa stellen können. Zu diesen Tools gehören Curl, Postman und GraphiQL. 

In den folgenden Beispielen verwenden wir GraphQL. Einer der Hauptvorteile der Verwendung von GraphQL besteht darin, dass das Schema abgerufen wird und Sie das Schema benutzerfreundlich erkunden können.

Laden Sie GraphiQL von https://www.electronjs.org/apps/graphiql herunter oder verwenden Sie den folgenden Befehl, wenn Sie ein Mac-Benutzer sind, auf dem Homebrew installiert ist:

brew install --cask graphiql

Nach der Installation von GraphiQL starten Sie es und Sie sehen etwas Ähnliches wie das Bild unten:

graphiiQ.png

Hinweise im obigen Bild:

  • Geben Sie Ihre Instanz-URL an und fügen Sie sie mit/api/graphql  in der GraphQL-Endpunkt-Adressleiste hinzu.
  • Bearbeiten Sie die HTTP-Header, um Ihr Zugriffstoken zum Autorisierungs-Header hinzuzufügen (siehe Abbildung unten).
  • Klicken Sie auf Dokumente, um das Schema anzuzeigen.

Wenn Sie die Kopfzeile bearbeiten, fügen Sie eine Berechtigungskopfzeile hinzu, indem Sie auf die Schaltfläche Kopfzeile hinzufügen und die folgenden Informationen klicken:

Kopfzeilenname: Autorisierungs-Header-Wert
: Bearer {Ihr Zugriffstoken}

Stellen Sie sicher, dass Sie dem Header-Wert den Bearer voranstellen, da Sie sonst nicht autorisieren können.

auth-header.png

Schema

Wenn Sie die Dokumente in GraphiQL erweitern, können Sie das Schema erkunden. Mit dem Schema können Sie herausfinden, was abfragbar ist und welche Rückgabetypen für die Abfragen vorhanden sind.

Warnung

Mutationen werden nicht unterstützt und sollten nicht verwendet werden.

Rückfragen

Mit GraphQL können Sie gezielt die Daten abfragen, die Sie benötigen. Sie können Daten für ein einzelnes Objekt oder eine Sammlung von Objekten abfragen.

Einzelobjekte

Um nach einem einzelnen Objekt abzufragen, verwenden Sie die Singularform des Objektnamens im unteren Kamelkästchen und geben Sie die Objekt-ID an. Zum Beispiel user(id: 1), expenseReport(id: 1).

single-object.png

Die Daten werden im JSON-Format mit den Daten für die abgefragten Felder zurückgegeben.

Kollektionen

Zum Abfragen einer Sammlung von Objekten verwenden Sie die Pluralform des Objektnamens im unteren Kamelkästchen. Zum Beispiel Benutzer, Spesenabrechnungen.

collections.png

Vereinigungen

Mit GraphQL können Sie verschachtelte Daten abfragen:

associations.png

Das Bild oben zeigt eine Abfrage für eine einzelne Spesenabrechnung (dies funktioniert auch für eine Sammlung von Objekten). In der Spesenabrechnung fragen wir nach, wer sie erstellt hat, und nach zusätzlichen Informationen zu den Spesenpositionen der Abrechnung. Beachten Sie, dass wir selbst innerhalb von Ausgabenzeilen nach verschachtelten Daten abfragen.

Benutzerdefinierte Felder

Objekte können benutzerdefinierte Felder haben, die über den Feldnamen customFields abgefragt werden können:

custom-fields.png

Bei benutzerdefinierten Feldern kann es sich um eine Reihe von Typen handeln (z. B. Text, Datum/Uhrzeit, Benutzer usw.). Das Feld customFields kann den Typ für dieses spezifische benutzerdefinierte Feld anzeigen, sodass Sie diese Typen speziell mithilfe von Fragmenten abfragen können.

Fragmente

Mit Fragmenten können Sie Gruppen von Feldern erstellen und diese dann in Abfragen einbeziehen. Für customFields können Sie Fragmente auf Typ-Ebene angeben:

fragments.png

Im obigen Beispiel geben wir zwei Fragmente an: … on User { … } und… on StringValue { … }. Die Fragmente weisen Coupa an, zu versuchen, die benutzerdefinierten Felder in die angegebenen Typen zu konvertieren (falls zutreffend). Wenn es in den angegebenen Typ konvertiert werden kann, werden die angefragten Felder zurückgegeben.

Erweiterte Filter- und Abfrageoptionen

Sammlungsabfragen verfügen über den zusätzlichen Optionsparameter Abfrage, der Antworten weiter herausfiltert. Das Format für die Abfrageoption ist in Form eines Abfragezeichenfolgenparameters, der auch zum Herausfiltern von Werten in unseren REST-APIs verwendet wird.

advanced-filtering-querying.png

Das obige Beispiel verwendet "id[lt_or_eq]=5" für den Abfrageparameter, der ID-Werte auf weniger als 5 herausfiltert. Dies kann auch direkt in unsere REST-APIs in Form von/api/invoices?id[lt_or_eq]=5 fallen gelassen werden.

Fehler

Wenn Sie Antworten überprüfen, sollten Sie immer überprüfen, ob die JSON-Antwort Fehler enthält. Bei Fehlern werden eine Meldung und Details zum Fehler angezeigt:

errors.png

Introspektion

Sie können GraphQL auch für das Schema selbst abfragen. Dies ist, was GraphQL tut, um das Schema für seine Clients zu generieren.  Hier ist ein Beispiel für eine typische Introspektionsabfrage:

query IntrospectionQuery {

		__Schema {

			queryType { name }

			mutationstyp { name }

			subscriptionType { name }

			typen {

				...FullType

			}

			direktiven {

				name

				beschreibung

				args {

					...Eingabewert

				}query IntrospectionQuery {

	__Schema {

		queryType {

			name

		}

		mutationType {

			name

		}

		subscriptionType {

			name

		}

		arten {

			...FullType

		}

		direktiven {

			name

			beschreibung

			args {

				...InputValue

			}

			onOperation

			onFragment

			onField

		}

	}

}



fragment FullType auf __Type {

	art

	name

	beschreibung

	felder(includeDeprecated: true) {

		name

		beschreibung

		args {

			...Eingabewert

		}

		type {

			...TypeRef

		}

		isDeprecated

		deprecationReason

	}

	inputFields {

		...Eingabewert

	}

	schnittstellen {

		...TypeRef

	}

	enumValues(includeDeprecated: true) {

		name

		beschreibung

		isDeprecated

		deprecationReason

	}

	possibleTypes {

		...TypeRef

	}

}



fragment InputValue auf __InputValue {

	name

	beschreibung

	type {

		...TypeRef

	}

	defaultValue

}



fragment TypeRef auf __Type {

	art

	name

	ofType {

		art

		name

		ofType {

			art

			name

			ofType {

				art

				name

			}

		}

	}

}



				onOperation

				onFragment

				onField

			}

		}

	}



	fragment FullType auf __Type {

		art

		name

		beschreibung

		felder(includeDeprecated: true) {

			name

			beschreibung

			args {

				...InputValue

			}

			typ {

				...TypeRef

			}

			isDeprecated

			deprecationReason

		}

		inputFields {

			...Eingabewert

		}

		schnittstellen {

			...TypeRef

		}

		enumValues(includeDeprecated: true) {

			name

			beschreibung

			isDeprecated

			deprecationReason

		}

		possibleTypes {

			...TypeRef

		}

	}



	fragment InputValue auf __InputValue {

		name

		beschreibung

		type { ...TypeRef }

		defaultValue

	}



	fragment TypeRef auf __Type {

		art

		name

		ofType {

			art

			name

			ofType {

				art

				name

				ofType {

					art

					name

				}

			}

		}

	}

GraphQL mit Postman

Alle oben genannten GraphQL-Beispiele können auch in Postman ausgeführt werden, indem Sie diese Schritte ausführen:

  1. Generieren Sie ein OIDC-Token in Coupa. Weitere Informationen finden Sie unter Erste Schritte mit OAuth.
  2. Sobald das Zugriffstoken generiert ist, verwenden Sie es, um die GraphQL-Anforderung mit der folgenden Postbotenkonfiguration zu initiieren:
    pm-gql-01.png

    pm-gql-02.png

Wichtige Hinweise

  • Alle Anfragen sind POST-Anfragen
  • Alle Antworten sind nur in json
  • Überprüfen Sie immer den Antworttext auf Fehler, auch wenn der Antwortcode von 200 zurückgegeben wurde

Vergleichbare Artikel


Optionen für die Abfrage

21 October 2016

Erfahren Sie, wie Sie Abfragen verwenden können, um die benötigten Daten schnell zu identifizieren und abzurufen.

Spezielle Aktionen und API-Notizen

21 October 2016

Weitere Informationen zur Verwendung der Coupa-API.

Unterschiede zwischen XML und json in Coupa

16 December 2016

Integrationsausführungen-API

24 April 2017

Verwenden Sie diese API, um einen Integrationslauf zu erstellen, abzufragen oder zu aktualisieren sowie den Status zu aktualisieren.

Hinweis: Einige Inhalte wurden maschinell übersetzt.