Présentation de GraphQL

Introduction

GraphQL est une spécification ouverte pour un langage de requête API (donc la référence « QL ») qui vous permet de rendre vos intégrations plus réactives que jamais en vous donnant la possibilité de demander les données dont vous avez besoin et rien de plus. GraphQL peut également réduire le nombre d'appels et d'allers-retours associés en récupérant toutes les ressources dont vous avez besoin en un seul appel ou en moins. 

En bref, GraphQL aura un impact mesurable sur vos intégrations en réduisant la surcharge de la bande passante due à la taille de la charge utile des réponses et au nombre d'appels effectués.

OIDC/OAuth2

Le point de terminaison de la requête GraphQL de Coupa est authentifié à l’aide d’OIDC et l’autorisation est gérée à l’aide de portées OAuth2.  Accédez à Configuration > Intégrations > ClientsOauth2/OpenID Connect et cliquez sur le bouton Créer (ou accédez à /oauth2/clients/new) pour créer un client OIDC avec les étendues de lecture OAuth2 appropriées pour vos requêtes (l'écriture n'est pas encore prise en charge). Actuellement, nous prenons uniquement en charge les types d'attribution des identifiants client.

Après avoir créé un client OIDC, utilisez les informations du client OIDC pour récupérer un jeton d'accès. Nous n'aborderons pas la question de savoir comment obtenir un jeton d'accès. Contactez votre administrateur Coupa ou l'assistance Coupa pour savoir comment récupérer un jeton d'accès avec vos informations client OIDC.

Clients GraphQL

Une fois que vous disposez d'un jeton d'accès, de nombreux outils sont disponibles et peuvent être utilisés pour envoyer des demandes GraphQL à Coupa. Ces outils incluent curl, Postman et GraphiQL. 

Dans les exemples suivants, nous utiliserons GraphQL. L'un des principaux avantages de l'utilisation de GraphQL est qu'il récupère le schéma et vous permet d'explorer le schéma de manière conviviale.

Téléchargez GraphiQL à partir de https://www.electronjs.org/apps/graphiqlou, si vous êtes un utilisateur Mac avec Homebrew installé, utilisez la commande suivante :

brew install --cask graphiql

Après avoir installé GraphiQL, lancez-le et vous verrez quelque chose de similaire à l'image ci-dessous :

À noter dans l'image ci-dessus :

• Indiquez l'URL de votre instance et ajoutez-la /api/graphqldans la barre d'adresses du point de terminaison GraphQL .
• Modifiez les en-têtes HTTP pour ajouter votre jeton d'accès à l'en-tête Autorisation (voir image ci-dessous).
• Cliquez sur Docspour développer et afficher le schéma.

Lorsque vous modifiez l'en-tête, ajoutez un en-tête d'autorisation en cliquant sur le bouton Ajouter un en-tête [Add Header ] et les informations suivantes :

Nom de l'en-tête : Autorisation
Valeur de l'en-tête : porteur {votre jeton d'accès}

Veillez à faire précéder la valeur de l'en-tête de bearerou vous ne pourrez pas l'autoriser.

Schéma

Développer les Docs dans GraphiQL vous permettra d'explorer le schéma. Avec le schéma, vous pouvez trouver ce qui peut être interrogé et les types de retour pour les requêtes.

Requêtes

Avec GraphQL, vous pouvez interroger spécifiquement les données dont vous avez besoin. Vous pouvez demander des données pour un seul objet ou une collection d'objets.

Objets uniques

Pour rechercher un seul objet, utilisez la forme singulière du nom de l'objet en minuscules et spécifiez l'ID de l'objet. Par exemple, user(id: 1), expenseReport(id: 1).

Les données sont renvoyées au format JSON avec les données des champs interrogés.

Collections

Pour rechercher une collection d'objets, utilisez la forme plurielle du nom de l'objet en minuscules. Par exemple, users, expenseReports.

Associations

GraphQL vous permet de demander des données imbriquées :

L'image ci-dessus montre une requête pour une note de frais unique (cela fonctionne également pour une collection d'objets). Dans la note de frais, nous recherchons qui l'a créée et des informations supplémentaires sur les lignes de notes de frais de la note de frais. Notez que même dans les lignes de dépenses, nous recherchons des données imbriquées.

Champs personnalisés

Les objets peuvent avoir des champs personnalisés qui peuvent être interrogés par le nom de champ customFields :

Les champs personnalisés peuvent être de n'importe quel type (ex : texte, datetime, utilisateur, etc...). Le champ CustomFields peut révéler le type de ce champ personnalisé spécifique, ce qui vous permettra d'interroger ces types en utilisant spécifiquement des fragments.

Fragments

Les fragments vous permettent de construire des ensembles de champs, puis de les inclure dans des requêtes. Pour customFields, vous pouvez spécifier des fragments au niveau du type :

Dans l'exemple ci-dessus, nous spécifions deux fragments : ... on User { ... } et ... on StringValue { ... }. Les fragments indiquent à Coupa de tenter de convertir les champs personnalisés aux types spécifiés (le cas échéant). S'il peut être converti dans ce type donné, les champs demandés seront retournés.

Options avancées de filtrage et de requête

Les requêtes de collection ont le paramètre d'option supplémentaire appelé requête qui filtre davantage les réponses. Le format de l' option de requête se présente sous la forme d'un paramètre de chaîne de requête qui est également utilisé pour filtrer les valeurs dans nos API REST.

The above example uses "id[lt_or_eq]=5" for the query parameter which filters out ID values to less than 5. This can also be dropped straight into our REST APIs in the form of /api/invoices ?id[lt_or_eq]=5.

Erreurs

Lors de la vérification des réponses, vous devez toujours vérifier si la réponse JSON comporte des erreurs. En cas d'erreurs, un message et les détails de l'erreur s'affichent :

Introspection

Vous pouvez également interroger GraphQL pour le schéma lui-même. C'est ce que fait GraphQL pour générer le schéma pour ses clients.  Voici un exemple typique de requête d'introspection :

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
				}
			}
		}
	}

GraphQL avec Postman

Tous les exemples GraphQL mentionnés ci-dessus peuvent également être exécutés dans Postmanen procédant comme suit :

1. Générer un jeton OIDC dans Coupa. Consultez la rubrique Prise en main d'OAuth pour plus de détails.
2. Une fois le jeton d'accès généré, utilisez-le pour lancer une demande GraphQL avec la configuration POSTMAN suivante :
   
   
   

Notes importantes

• Toutes les demandes sont des demandes POST
• Toutes les réponses sont au format JSON uniquement
• Vérifiez toujours si le corps de la réponse contient des erreurs, même si le code de réponse 200 a été renvoyé