• Dernière modification le: 25 July 2022

Présentation de GraphQL

Introduction

GraphQL est une spécification ouverte pour un langage de requête API (d'où la référence « QL ») qui vous permet de rendre vos intégrations plus réactives que jamais en vous offrant 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 que vous effectuez en récupérant toutes les ressources dont vous avez besoin en un seul appel ou moins. 

En bref, GraphQL aura un impact mesurable sur vos intégrations en réduisant la surcharge de bande passante en raison de la taille des charges utiles de réponse et du nombre d'appels effectués.

Remarque

Les filtres d'API continuent d'être une fonctionnalité clé qui devrait toujours être utilisée pour réduire l'utilisation des ressources lorsque l'API REST REÇOIT des appels.

OIDC/OAuth2

Le point de terminaison de requête GraphQL de Coupa est authentifié à l'aide d'OIDC et l'autorisation est gérée à l'aide des étendues OAuth2.  Accédez à Configuration des > intégrations > Oauth2/OpenID Connect Clients 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). Nous ne prenons actuellement en charge que les types de subvention d'informations d'identification client.

create-client.png

Après avoir créé un client OIDC, utilisez les informations du client OIDC pour récupérer un jeton d'accès. Nous n'entrerons pas dans la discussion sur la façon d'obtenir un jeton d'accès. Contactez votre administrateur Coupa ou le support Coupa pour savoir comment récupérer un jeton d'accès avec vos informations client OIDC.

Clients GraphQL

Une fois que vous avez un jeton d'accès, il existe de nombreux outils disponibles qui peuvent être utilisés pour faire des demandes GraphQL à Coupa. Ces outils comprennent 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 de l'explorer de manière conviviale.

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

installation de brassage --cask graphiql

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

graphiiQ.png

Choses à noter dans l'image ci-dessus :

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

Lors de la modification de l'en-tête, ajoutez un en-tête d'autorisation en cliquant sur le bouton Ajouter un en-tête et les informations suivantes :

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

Assurez-vous de préfixer la valeur d'en-tête par le porteur, sinon vous ne pourrez pas autoriser.

auth-header.png

Schéma

L'extension des documents dans GraphiQL vous permettra d'explorer le schéma. Avec le schéma, vous pouvez savoir ce qui est interrogeable et les types de retour pour les requêtes.

Avertissement

Les mutations ne sont pas prises en charge et ne doivent pas être utilisées.

Requêtes

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

Objets simples

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

single-object.png

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 casse de chameau inférieure. Par exemple, les utilisateurs, les notes de frais.

collections.png

Associations

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

associations.png

L'image ci-dessus montre une requête pour une seule note de frais (cela fonctionne également pour une collection d'objets). Dans le rapport de dépenses, nous demandons qui l'a créé et des informations supplémentaires sur les lignes de dépenses du rapport. Notez que même au sein des lignes de notes de frais, 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 :

custom-fields.png

Les champs personnalisés peuvent être de plusieurs types (par exemple : texte, date et heure, utilisateur, etc.). Le champ customFields peut révéler quel est le type pour ce champ personnalisé spécifique, ce qui vous permettra de rechercher 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 :

fragments.png

Dans l'exemple ci-dessus, nous spécifions deux fragments : … sur l'utilisateur { … } et… sur 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 à ce type donné, les champs demandés seront retournés.

Options avancées de filtrage et d'interrogation

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.

advanced-filtering-querying.png

L'exemple ci-dessus utilise « id[lt_or_eq]=5 » pour le paramètre de requête qui filtre les valeurs d'ID inférieures à 5. Cela peut également être déposé directement dans nos API REST sous la forme de/api/INVOICES ?id[lt_or_eq]=5.

Erreurs

Lorsque vous vérifiez les réponses, vous devez toujours vérifier si la réponse JSON contient des erreurs. S'il y a des erreurs, un message et les détails de l'erreur s'affichent :

errors.png

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 de requête d'introspection typique :

query IntrospectionQuery {

		__schema {

			queryType { name }

			mutationType { name }

			subscriptionType { name }

			types {

				...FullType

			}

			directives {

				nom

				description

				args {

					...InputValue

				}query IntrospectionQuery {

	__schema {

		queryType {

			nom

		}

		mutationType {

			nom

		}

		subscriptionType {

			nom

		}

		types {

			...FullType

		}

		directives {

			nom

			description

			args {

				...InputValue

			}

			onOperation

			onFragment

			onField

		}

	}

}



fragment FullType sur __Type {

	nature

	nom

	description

	champs(includeDeprecated : true) {

		nom

		description

		args {

			...InputValue

		}

		type {

			...TypeRef

		}

		isDeprecated

		deprecationReason

	}

	inputFields {

		...InputValue

	}

	interfaces {

		...TypeRef

	}

	enumValues(includeDeprecated : true) {

		nom

		description

		isDeprecated

		deprecationReason

	}

	possibleTypes {

		...TypeRef

	}

}



fragment InputValue sur __InputValue {

	nom

	description

	type {

		...TypeRef

	}

	defaultValue

}



fragment TypeRef sur __Type {

	nature

	nom

	ofType {

		nature

		nom

		ofType {

			nature

			nom

			ofType {

				nature

				nom

			}

		}

	}

}



				onOperation

				onFragment

				onField

			}

		}

	}



	fragment FullType sur __Type {

		nature

		nom

		description

		champs(includeDeprecated : true) {

			nom

			description

			args {

				...InputValue

			}

			type {

				...TypeRef

			}

			isDeprecated

			deprecationReason

		}

		inputFields {

			...InputValue

		}

		interfaces {

			...TypeRef

		}

		enumValues(includeDeprecated : true) {

			nom

			description

			isDeprecated

			deprecationReason

		}

		possibleTypes {

			...TypeRef

		}

	}



	fragment InputValue sur __InputValue {

		nom

		description

		type { ...TypeRef }

		defaultValue

	}



	fragment TypeRef sur __Type {

		nature

		nom

		ofType {

			nature

			nom

			ofType {

				nature

				nom

				ofType {

					nature

					nom

				}

			}

		}

	}

GraphQL à l'aide de Postman

Tous les exemples GraphQL mentionnés ci-dessus peuvent également être exécutés dans Postman en suivant ces étapes :

  1. Générez un jeton OIDC dans Coupa. Voir 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 requête GraphQL avec la configuration POSTMAN suivante :
    pm-gql-01.png

    pm-gql-02.png

Remarques importantes

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

Articles associés


Options de requête

21 October 2016

Découvrez comment utiliser les requêtes pour identifier et extraire rapidement les données dont vous avez besoin.

Actions spéciales et notes API

21 October 2016

Informations supplémentaires sur l'utilisation de l'API Coupa.

Différences entre XML et JSON dans Coupa

16 December 2016

API d'exécution d'intégration

24 April 2017

Utilisez cette API pour créer, interroger ou mettre à jour une exécution d'intégration, ainsi que pour mettre à jour le statut.

Une partie ou la totalité de cette page peut avoir été traduite par machine. Toutes nos excuses pour les inexactitudes.