Einführung in GraphQL

Einleitung

GraphQL ist eine offene Spezifikation für eine API-Abfragesprache (also die "QL"-Referenz), mit der Sie Ihre Integrationen reaktiver machen können als je zuvor, indem Sie die Möglichkeit haben, die benötigten Daten anzufordern und nichts weiter. GraphQL kann auch die Anzahl der Anrufe und der zugehörigen Hin- und Rückfahrten reduzieren, indem Sie alle benötigten Ressourcen in einem einzigen Anruf abrufen oder weniger. 

Kurz gesagt, GraphQL wird sich messbar auf Ihre Integrationen auswirken, indem es den Bandbreitenaufwand aufgrund der Antwortzahllasten und der Anzahl der getätigten Anrufe reduziert.

OIDC/OAuth2

Der GraphQL-Abfrageendpunkt von Coupa wird mit OIDC authentifiziert und die Autorisierung wird mit OAuth2-Geltungsbereichen durchgeführt.  Gehen Sie zu Konfiguration > Integrationen > Oauth2/OpenID Connect Clientsund klicken Sie auf die Schaltfläche Erstellen (oder gehen Sie zu /oauth2/clients/new), um einen OIDC-Client mit den entsprechenden OAuth2-Lesebereichen für Ihre Abfragen zu erstellen (Schreiben wird noch nicht unterstützt). Wir unterstützen derzeit nur Clientanmeldeinformationen für Gewährungstypen.

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

GraphQL-Clients

Nachdem Sie über ein Zugriffstoken verfügen, gibt es viele Tools, die verwendet werden können, um GraphQL-Anforderungen an Coupa zu stellen. Zu diesen Tools gehören curl, Postman und GraphiQL. 

In den folgenden Beispielen verwenden wir GraphQL. Einer der Hauptvorteile der Verwendung von GraphQL ist, dass es das Schema abruft und es Ihnen ermöglicht, das Schema auf eine benutzerfreundliche Weise zu erkunden.

Laden Sie GraphiQL von https://www.electronjs.org/apps/graphiqlherunter oder verwenden Sie, wenn Sie ein Mac-Benutzer mit Homebrew sind, den folgenden Befehl:

brew install --cask graphiql

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

Zu beachten im obigen Bild:

• Geben Sie Ihre Instanz-URL an und hängen Sie sie /api/graphqlin der Adressleiste des GraphQL-Endpunkts an.
• Bearbeiten Sie die HTTP-Kopfzeilen, um Ihr Zugriffstoken zum Autorisierungskopf hinzuzufügen (siehe Bild unten).
• Klicken Sie auf Docs, um das Schema zu erweitern.

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

Kopfzeilenname: Autorisierung
Kopfzeilenwert: Inhaber {Ihr Zugriffstoken}

Stellen Sie sicher, dass Sie dem Kopfzeilenwert das Präfix bearervoranstellen, oder Sie können nicht autorisieren.

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 verwendet werden können.

Abfragen

Mit GraphQL können Sie gezielt nach den benötigten Daten suchen. Sie können Daten für ein einzelnes Objekt oder eine Auflistung von Objekten abfragen.

Einzelne Objekte

Um nach einem einzelnen Objekt zu fragen, verwenden Sie die singuläre Form des Objektnamens in der unteren Kamelschrift und geben Sie die Objekt-ID an. Beispiel: user(id: 1), expenseReport(id: 1).

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

Sammlungen

Um eine Auflistung von Objekten abzufragen, verwenden Sie die Pluralform des Objektnamens in der unteren Kamelschrift. Beispiel: Benutzer, expenseReports.

Verbände

Mit GraphQL können Sie nach verschachtelten Daten suchen:

Das obige Bild zeigt eine Abfrage für einen einzelnen Ausgabenbericht (dies funktioniert auch für eine Auflistung von Objekten). Im Ausgabenbericht fragen wir nach dem Ersteller und zusätzlichen Informationen zu den Ausgabenpositionen des Berichts. Beachten Sie, dass wir selbst in Ausgabenpositionen nach geschachtelten Daten abfragen.

Benutzerdefinierte Felder

Objekte können benutzerdefinierte Felder haben, die durch den Feldnamen benutzerdefinierte Felder abgefragt werden können:

Benutzerdefinierte Felder können von einer Vielzahl von Typen sein (z. B. Text, Datum, Uhrzeit, Benutzer usw.). Das benutzerdefinierte Feld kann den Typ für dieses spezifische benutzerdefinierte Feld aufdecken, wodurch Sie mithilfe von Fragmenten gezielt nach diesen Typen abfragen können.

Fragmente

Mit Fragmenten können Sie Feldgruppen erstellen und sie dann in Abfragen einschließen. Für customFieldskönnen Sie Fragmente auf Typebene angeben:

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

Erweiterte Filter- und Abfrageoptionen

Auflistungsabfragen haben den zusätzlichen Optionsparameter query, der Antworten weiter herausfiltert. Das Format für die Abfrage -Option ist in Form eines Abfrage-String-Parameters, der auch zum Herausfiltern von Werten in unseren REST-APIs verwendet wird.

Im obigen Beispiel wird "id[lt_or_eq]=5" für den Abfrageparameter verwendet, 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 prüfen, ob die JSON-Antwort Fehler aufweist. Bei Fehlern werden eine Meldung und Details des Fehlers angezeigt:

Selbstbeobachtung

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 }
			mutationType { name }
			subscriptionType { name }
			types {
				...FullType
			}
			directives {
				name
				description
				args {
					...InputValue
				}query IntrospectionQuery {
	__schema {
		queryType {
			name
		}
		mutationType {
			name
		}
		subscriptionType {
			name
		}
		types {
			...FullType
		}
		directives {
			name
			description
			args {
				...InputValue
			}
			onOperation
			onFragment
			onField
		}
	}
}

fragment FullType on __Type {
	kind
	name
	description
	fields(includeDeprecated: true) {
		name
		description
		args {
			...InputValue
		}
		type {
			...TypeRef
		}
		isDeprecated
		deprecationReason
	}
	inputFields {
		...InputValue
	}
	interfaces {
		...TypeRef
	}
	enumValues(includeDeprecated: true) {
		name
		description
		isDeprecated
		deprecationReason
	}
	possibleTypes {
		...TypeRef
	}
}

fragment InputValue on __InputValue {
	name
	description
	type {
		...TypeRef
	}
	defaultValue
}

fragment TypeRef on __Type {
	kind
	name
	ofType {
		kind
		name
		ofType {
			kind
			name
			ofType {
				kind
				name
			}
		}
	}
}

				onOperation
				onFragment
				onField
			}
		}
	}

	fragment FullType on __Type {
		kind
		name
		description
		fields(includeDeprecated: true) {
			name
			description
			args {
				...InputValue
			}
			type {
				...TypeRef
			}
			isDeprecated
			deprecationReason
		}
		inputFields {
			...InputValue
		}
		interfaces {
			...TypeRef
		}
		enumValues(includeDeprecated: true) {
			name
			description
			isDeprecated
			deprecationReason
		}
		possibleTypes {
			...TypeRef
		}
	}

	fragment InputValue on __InputValue {
		name
		description
		type { ...TypeRef }
		defaultValue
	}

	fragment TypeRef on __Type {
		kind
		name
		ofType {
			kind
			name
			ofType {
				kind
				name
				ofType {
					kind
					name
				}
			}
		}
	}

GrafikQL mit Postman

Alle oben genannten GraphQL-Beispiele können auch in Postmanausgeführt werden, indem Sie die folgenden 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 wurde, verwenden Sie es, um die GraphQL-Anforderung mit der folgenden POSTMAN-Konfiguration zu initiieren:
   
   
   

Wichtige Hinweise

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