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.
Les filtres API restent une fonctionnalité clé qui doit encore être utilisée pour réduire l'utilisation des ressources lors des appels REST API GET.
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/graphql
dans 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 bearer
ou 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.
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 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 :
- Générer un jeton OIDC dans Coupa. Consultez la rubrique 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 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é
Une partie ou la totalité de cette page peut avoir été traduite par machine. Toutes nos excuses pour les inexactitudes.