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.
API-Filter sind weiterhin eine wichtige Funktion, die weiterhin verwendet werden sollte, um die Ressourcennutzung zu reduzieren, wenn REST-API GET-Aufrufe getätigt werden.
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/graphql
in 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 bearer
voranstellen, 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.
Mutationen werden nicht unterstützt und sollten nicht verwendet werden.
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 customFields
kö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:
- Generieren Sie ein OIDC-Token in Coupa. Weitere Informationen finden Sie unter Erste Schritte mit OAuth .
- 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
Parts or all of this page might have been machine-translated. We apologize for any inaccuracies.