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.
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.
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 graphiqlNach der Installation von GraphiQL starten Sie es und Sie sehen etwas Ähnliches wie das Bild unten:
Hinweise im obigen Bild:
- Geben Sie Ihre Instanz-URL an und fügen Sie sie mit
/api/graphqlin 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.
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.
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).
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.
Vereinigungen
Mit GraphQL können Sie verschachtelte Daten abfragen:
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:
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:
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.
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:
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:
- Generieren Sie ein OIDC-Token in Coupa. Weitere Informationen finden Sie unter Erste Schritte mit OAuth.
- Sobald das Zugriffstoken generiert ist, verwenden Sie es, um die GraphQL-Anforderung mit der folgenden Postbotenkonfiguration zu initiieren:
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