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.
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.
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 graphiqlAprès avoir installé GraphiQL, lancez-le et vous verrez quelque chose de similaire à l'image ci-dessous :
Choses à noter dans l'image ci-dessus :
- Fournissez l'URL de votre instance et ajoutez-la avec
/api/graphqldans 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.
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.
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).
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.
Associations
GraphQL vous permet de rechercher des données imbriquées :
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 :
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 :
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.
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 :
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 :
- Générez un jeton OIDC dans Coupa. Voir Prise en main d'OAuth pour plus de détails.
- Une fois le jeton d'accès généré, utilisez-le pour lancer une requête GraphQL avec la configuration POSTMAN suivante :
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é