Utilisation de l' éditeur de schémaGraphQL

L' éditeur de schémaGraphQL permet de configurer une plage de paramètres utilisés pour calculer la complexité d'une demande GraphQL et un coût associé qui compte pour la limite de débit.

Introduction

Lorsque l' éditeur de schémaGraphQL s'ouvre, tous les types définis dans le schéma GraphQL sont répertoriés. Vous pouvez développer un type pour afficher toutes les zones qui sont définies pour ce type.

Pour chaque type, vous pouvez spécifier le paramètre suivant :

Poids du type

Facteur de pondération que vous souhaitez appliquer au type pour calculer le coût d'une demande à l'API GraphQL. En règle générale, le facteur de pondération d'un type reflétera les conséquences de l'extraction des valeurs de ce type sur les ressources. Par exemple :

Un objet complexe peut avoir une pondération plus importante qu'une chaîne.
Les valeurs d'un type peuvent être extraites à partir d'une base de données de back end différente vers des valeurs d'un autre type. Sachant que l'accès à une base de données requiert davantage de ressources d'unité centrale, les types associés à cette base de données ont une pondération plus importante.

Pour chaque zone, vous pouvez spécifier les paramètres suivants :

Poids de la zone: Facteur de pondération que vous souhaitez appliquer à la zone pour calculer le coût d'une demande à l'API GraphQL.
Taille supposée: Taille limite imposée par le serveur de back end au nombre de valeurs renvoyées sous forme de liste, pour chaque récupération distincte de la zone dans une demande d'API. Si une taille supposée a été définie pour cette zone dans le schéma GraphQL importé, sa valeur s'affiche. Vous pouvez entrer une valeur ou modifier la valeur en cours et la définition de schéma stockée dans API Connect est mise à jour en conséquence. Vous devez vous assurer que la valeur spécifiée correspond à l'implémentation ou à la configuration sur le serveur dorsal afin que API Connect puisse appliquer correctement la limitation de débit. La taille supposée est destinée à être configurée pour les zones qui renvoient des listes de valeurs, afin d'indiquer à l'analyse des coûts le nombre de valeurs attendues.
Arguments de tranche: Liste séparée par des virgules des arguments utilisés par le serveur de back end pour limiter le nombre de valeurs de cette zone qui sont renvoyées sous forme de liste, pour chaque récupération distincte de la zone dans une demande d'API. Ces valeurs doivent correspondre à l'implémentation ou la configuration sur le serveur de back end. Par exemple, il peut y avoir des arguments de tranche first et last utilisés pour spécifier une gamme d'objets devant être renvoyés par une demande d'API.
Zones dimensionnées: Il peut arriver qu'une zone comportant un paramètre Taille supposée ou Arguments de tranche configuré renvoie un objet, dont une zone renvoie les valeurs devant être dimensionnées. Cela est fréquent dans le modèle de pagination des connexions, où les champs avec les arguments de découpage first ou last renvoient un objet connections , qui contient la liste dimensionnée dans un champ edges . L'option Zones dimensionnées permet à l'analyse de coût de tenir compte de ces relations indirectes entre les tailles supposées ou les arguments de tranche et la liste de valeurs dimensionnées. Fournissez une liste séparée par des virgules des noms de zones.

Vous pouvez accéder à l' éditeur de schémaGraphQL de l'une des manières suivantes:

En cliquant sur Editer l'API puis sur Schéma GraphQL tout de suite après avoir créé une API de proxy GraphQL. Pour plus de détails sur la création de l'API proxy GraphQL, voir Création d'une API proxy GraphQL.
En modifiant la configuration d'une API existante. Pour ce faire, procédez comme suit :
1. Dans le volet de navigation, cliquez sur Develop, puis sélectionnez l'onglet APIs.
2. À côté de la définition de l'API GraphQL avec laquelle vous souhaitez travailler, cliquez sur l'icône des options , puis sur Modifier l'API.
3. Cliquez sur l'onglet SchémaGraphQL .

Modifier un paramètre pour un type ou une zone unique

Dans le cas d'un paramètre numérique, cliquez sur ce paramètre en regard du type ou de la zone, puis entrez la valeur requise ou utilisez le bouton déroulant. Dans le cas d'un paramètre textuel, entrez directement la valeur. Vous pouvez d'abord filtrer l'affichage pour n'afficher qu'un sous-ensemble pertinent de types et de zones ; voir Filtrage de l'affichage.

Modifier les paramètres de plusieurs types et zones

Si vous souhaitez modifier les paramètres de plusieurs types et zones au cours d'une même opération, procédez comme suit :

Cochez les cases en regard des types et des zones dont vous souhaitez modifier les paramètres.
Cliquez sur Appliquer la configuration d'analyse.
Dans l'onglet Type, spécifiez les paramètres à appliquer aux types sélectionnés.
Dans l'onglet Zone, spécifiez les paramètres à appliquer aux zones sélectionnées.
Cliquez sur Appliquer pour appliquer les paramètres aux types et zones sélectionnés.
Une fois que vous avez modifié les types et zones sélectionnés, cliquez sur Terminé. Toutes les cases à cocher sont désélectionnées.

Pour réinitialiser les paramètres de type ou de zone sur leur valeur par défaut après avoir appliqué une configuration d'analyse, cochez les cases en regard des types et zones concernés, puis cliquez sur Retirer la configuration d'analyse.

Vous pouvez d'abord filtrer l'affichage pour n'afficher qu'un sous-ensemble pertinent de types et de zones ; voir Filtrage de l'affichage.

Filtrer l'affichage

Pour afficher uniquement les types et zones qui comportent une chaîne spécifique, entrez la chaîne de filtrage requise dans la zone Rechercher un schéma et appuyez sur la touche Entrée.

Si un type correspond au filtre, le type et toutes ses zones sont affichés. Si une zone correspond au filtre, mais pas à son type parent, le type parent est affiché avec toutes les zones correspondantes. Vous pouvez entrer plusieurs chaînes de filtrage ; les éléments affichés sont ceux qui contiennent toutes les chaînes.

Vous pouvez désormais utiliser les opérations décrites dans Modification d'un paramètre pour un type ou une zone unique et dans Modification des paramètres pour plusieurs types et zones pour mettre à jour les paramètres des types et zones affichés.

Pour supprimer une chaîne de filtrage spécifique de la recherche, cliquez sur l'icône Fermer Icône d'effacement d'un filtre de recherche GraphQL pour cette chaîne de filtrage. Pour rétablir l'affichage complet du type et du champ en supprimant toutes les chaînes de filtrage, cliquez sur l'icône Clear (Effacer) Icône d'effacement de tous les filtres de recherche GraphQL à la fin du champ de recherche.

Avertissements liés aux schémas GraphQL

Le cas échéant, API Connect recommande des mises à jour de la configuration d'analyse pour protéger le serveur dorsal contre une utilisation excessive des ressources et pour garantir une estimation correcte des coûts des demandes. Ces recommandations s'affichent sous forme d'avertissements dans l' éditeur de schémaGraphQL.

Si un type contient un ou plusieurs champs avec des avertissements, cela est indiqué par une icône de nombre d'avertissements

à côté du type. Vous pouvez cliquer sur l'icône du nombre d'avertissements pour afficher les avertissements de ce type ; la fenêtre Avertissements s'ouvre au niveau des avertissements appropriés, par exemple:

Pour voir les champs comportant des avertissements, développez le type; une icône d'avertissement Icône d'avertissement GraphQL s'affiche à côté des champs comportant des avertissements. Pour voir les détails d'un avertissement pour un champ, cliquez sur l'icône d'avertissement à côté du champ

Si vous cliquez sur Accepter sous un avertissement dans la fenêtre Avertissements, la mise à jour recommandée est appliquée automatiquement au schéma.

Pour appliquer les suggestions de mises à jour pour tous les avertissements en une seule opération, cliquez sur Appliquer tout dans la fenêtre Avertissements et cliquez une deuxième fois sur Appliquer pour confirmer votre choix.

Vous pouvez filtrer l'affichage pour n'inclure que les éléments comportant des avertissements; cliquez sur l'icône de menu Icône de menu GraphQL , puis sélectionnez Afficher uniquement les avertissements.

Application de directives @remove à des types et des zones dans le schéma GraphQL

La directive de schéma GraphQL @remove spécifie les conditions permettant de supprimer des éléments de la validation ou de l'introspection pour chaque transaction en fonction de valeurs dans le contexte d'API. Par exemple, vous pouvez empêcher des plans spécifiques d'utiliser certains types ou zones.

Pour plus de détails sur la directive @remove , y compris des exemples, voir rapic_graphql_extensions.html#reference_wrt_bk1_5mb__at_remove.

Pour appliquer une directive @remove à un élément dans votre schéma GraphQL, procédez comme suit :

Cliquez sur l'icône des paramètres dans la colonne Afficher/Masquer à côté de l'élément requis. La fenêtre Afficher/masquer les paramètres s'ouvre.
Pour supprimer l'élément en fonction d'une condition booléenne, entrez l'expression booléenne dans la zone Expression personnalisée ; la directive suivante sera ajoutée à l'élément dans le schéma :
```
@remove(if: [expression])
```
Pour supprimer l'élément sans condition, placez le curseur de la règle Afficher dans le schéma sur Masquer dans le schéma ; la directive suivante sera ajoutée à l'élément dans le schéma :
```
@remove(if: ["true"])
```
Cliquez sur Suivant. Une fenêtre récapitulative s'ouvre. Si la suppression est autorisée, tous les éléments connexes auxquels la directive @remove sera appliquée sont répertoriés ; par exemple, si vous appliquez une directive @remove à un type et que ce type est référencé en tant que type de données d'une zone sur un autre type, la directive @remove est également appliquée à cette zone. Si la suppression n'est pas autorisée, une explication s'affiche.
Si le retrait est autorisé, cliquez sur Terminé pour appliquer la directive @remove. Si le retrait n'est pas autorisé, cliquez sur Annuler pour fermer la fenêtre ou sur Précédent et modifiez vos paramètres.
Pour afficher les mises à jour appliquées au schéma GraphQL JSON, cliquez sur Afficher la source.

Vous pouvez utiliser l'icône des paramètres Icône des paramètres GraphQL pour modifier ou supprimer les directives @remove précédemment appliquées. Pour retirer une directive @remove conditionnelle, supprimez l'expression de la zone Expression personnalisée. Pour supprimer une directive @remove sans condition, placez le curseur de la règle Masquer dans le schéma sur Afficher dans le schéma.

Afficher le schéma GraphQL

Pour afficher le schéma GraphQL JSON précédemment téléchargé, cliquez sur Afficher la source. Notez que le schéma inclut des instructions directive et des valeurs d'attribut, ajoutées par API Connect, qui reflètent les paramètres de configuration.

Remplacer le schéma GraphQL

Pour remplacer le schéma GraphQL, procédez comme suit :

Cliquez sur Remplacer.
Indiquez le schéma de remplacement :
- Pour remplacer le schéma par l'introspection d'une URL, procédez comme suit :
  1. Sélectionnez Introspect sur URL.
  2. Entrez l'adresse URL dans le champ URL du serveur GraphQL, puis cliquez sur Introspect.
  Remarque : si vous remplacez le schéma d'un URL différent de celui spécifié comme serveur d'arrière-plan (backend) GraphQL, dans le champ URL du serveur GraphQL, lorsque l'API proxy d' GraphQL a été créée, le schéma lui-même est remplacé mais l' URL d'arrière-plan reste inchangé. Vous devez modifier en conséquence le paramètre URL sur la stratégie invoke dans l'assemblage d'API de votre API de proxy GraphQL.
- Pour remplacer le schéma en téléchargeant un fichier, procédez comme suit :
  1. Sélectionnez Télécharger le fichier de langue de définition de schéma (SDL).
  2. Vous pouvez soit faire glisser et déposer le fichier, soit cliquer sur le lien pour sélectionner le fichier sur votre système de fichiers local.
  Remarque :
  - Le schéma doit être écrit en langage de définition de schéma (SDL) GraphQL. Pour plus d'informations, voir Type language dans la documentation GraphQL à l'adresse suivante https://graphql.org/.
  - Si vous téléchargez un schéma à partir d'un fichier local ayant déjà téléchargé un schéma à partir d'une URL, le paramètre d'URL du schéma qui est stocké dans la source OpenAPI pour l'API, puis affiché dans l'interface utilisateur, conserve la valeur d'URL spécifiée précédemment au lieu d'indiquer un emplacement de fichier.
Toutes les modifications entre le schéma de remplacement et le schéma en cours sont répertoriées.
Mettez à jour le schéma selon les besoins :
- Pour que tous les nouveaux types et zones soient affichés par défaut, sélectionnez Nouveau schéma pour le paramètre Mettre à jour les valeurs par défaut du schéma en donnant la préférence à. Vous pouvez ensuite choisir de masquer des éléments spécifiques en sélectionnant Masquer dans la colonne Action en regard d'un élément. Le masquage d'un élément entraîne l'ajout d'une directive @remove à l'élément dans la source de schéma, comme indiqué dans la rubrique Application des directives @remove aux types et aux zones du schéma GraphQL.
- Pour que tous les nouveaux types et zones soient masqués par défaut, sélectionnez Ancien schéma pour le paramètre Mettre à jour les valeurs par défaut du schéma en donnant la préférence à. Vous pouvez ensuite choisir d'afficher des éléments spécifiques en sélectionnant Afficher dans la colonne Action en regard d'un élément.
Remarque: Si le schéma en cours contient des éléments qui ne figurent pas dans le schéma de remplacement, ces éléments sont supprimés. Ces suppressions figurent dans la liste des modifications avec le paramètre Accept affiché dans la colonne Action ; vous ne pouvez pas modifier ce paramètre.
Cliquez sur Suivant. Un récapitulatif des modifications s'affiche. Si aucun retrait n'est autorisé, une explication s'affiche et vous ne pouvez pas procéder au remplacement de schéma ; cliquez sur Annuler pour fermer la fenêtre ou sur Précédent et modifiez vos paramètres.
Cliquez sur Soumettre une fois le remplacement de schéma effectué.

Télécharger le schéma GraphQL

Pour télécharger le schéma vers un fichier local, cliquez sur Télécharger. Notez que le schéma téléchargé inclut tous les paramètres supplémentaires qui reflètent les mises à jour de votre configuration.