Importer une API GraphQL

S’APPLIQUE À : tous les niveaux de Gestion des API

Dans Gestion des API, vous pouvez ajouter une API GraphQL selon l’un des deux modèles suivants : pass-through vers un point de terminaison GraphQL existant ou importation d’un schéma GraphQL et création d’une API GraphQL synthétique avec des résolveurs de champs personnalisés. Pour plus d’informations, consultez la Vue d’ensemble de GraphQL.

Dans cet article, vous allez :

• Ajouter une API GraphQL pass-through dans votre instance Gestion des API.
• Tester votre API GraphQL.

Si vous souhaitez importer un schéma GraphQL et configurer des programmes de résolution de champs qui utilisent des points de terminaison d’API REST ou SOAP, consultez Importer un schéma GraphQL et configurer des programmes de résolution de champs.

Prérequis

• Une instance du service Gestion des API Azure. Si vous ne l’avez pas déjà fait, créez-en un.

• Azure CLI, si vous souhaitez l’utiliser pour importer l’API.

  • Utilisez l’environnement Bash dans Azure Cloud Shell. Pour obtenir plus d’informations, consultez Démarrage d’Azure Cloud Shell.

    

  • Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.

    • Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour obtenir d’autres options de connexion, consultez S’authentifier auprès d’Azure à l’aide d’Azure CLI.

    • Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser et gérer des extensions avec Azure CLI.

    • Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

• Azure PowerShell, si vous souhaitez l’utiliser pour importer l’API.

  • Si vous choisissez d’utiliser Azure PowerShell localement :
    • Installez la dernière version du module Az PowerShell.
    • Connectez-vous à votre compte Azure à l’aide de la cmdlet Connect-AzAccount.
  • Si vous choisissez d’utiliser Azure Cloud Shell :
    • Pour plus d’informations, consultez Vue d’ensemble d’Azure Cloud Shell.

Ajouter une API GraphQL

Portail

1. Dans le portail Azure, accédez à votre instance Gestion des API.

2. Dans le volet gauche, sélectionnez API> API.

3. Sélectionnez Ajouter une API.

4. Sous Définir une nouvelle API, sélectionnez la vignette GraphQL .

   

5. Dans la boîte de dialogue résultante, sélectionnez Full, puis entrez des valeurs dans les champs obligatoires, comme décrit dans le tableau suivant.

   

   Valeur	Descriptif
   Nom complet	Nom sous lequel votre API GraphQL est affichée.
   Nom	Nom brut de l’API GraphQL. Se remplit automatiquement à mesure que vous tapez le nom complet.
   type de GraphQL	Sélectionnez Pass-through GraphQL pour importer depuis un point de terminaison d’API GraphQL existant.
   Point de terminaison de l’API GraphQL	URL de base avec le nom de point de terminaison de l’API GraphQL. Par exemple : https://example.com/your-GraphQL-name. Vous pouvez également utiliser un point de terminaison SWAPI GraphQL commun comme https://swapi-graphql.azure-api.net/graphql pour la démonstration.
   Charger un schéma	Sélectionnez éventuellement pour charger votre fichier de schéma pour remplacer le schéma récupéré à partir du point de terminaison GraphQL (si vous en avez un).
   Description	Ajoutez une description de votre API.
   Modèle d’URL	Sélectionnez un schéma en fonction de votre point de terminaison GraphQL. Sélectionnez l’une des options contenant un schéma WebSocket (WS ou WSS) si votre API GraphQL inclut le type d’abonnement. La sélection par défaut est HTTP(S).
   Suffixe de l’URL de l’API	Ajoutez un suffixe d’URL pour identifier l’API spécifique dans l’instance Gestion des API. Il doit être unique dans l’instance Gestion des API.
   URL de base	Champ non modifiable affichant votre URL de base d’API.
   Balises	Associez éventuellement votre API GraphQL à des balises nouvelles ou existantes.
   Produits	Associez votre API GraphQL à un produit pour la publier.
   Créer une version pour cette API ?	Cochez la case pour appliquer un schéma de contrôle de version à votre API GraphQL.

6. Sélectionnez Create (Créer).

7. Une fois l’API créée, passez en revue ou modifiez le schéma sous l’onglet Screenshot of the GraphQL schema in the portal.

Azure CLI

L’exemple suivant utilise la commande az apim api import pour importer un passthrough API GraphQL à partir de l’URL spécifiée dans une instance Gestion des API nommée apim-hello-world.

# Details specific to API Management instance.
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details.
APIId="my-graphql-api"
APIPath="myapi"
DisplayName="MyGraphQLAPI"
SpecificationFormat="GraphQL"
SpecificationURL="<GraphQL backend endpoint>"

# Import API.
az apim api import \
    --path $APIPath \
    --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --display-name $DisplayName --specification-format $SpecificationFormat \
    --specification-url $SpecificationURL

Après avoir importé l’API, vous pouvez mettre à jour les paramètres à l’aide de la commande az api api update , si nécessaire.

PowerShell

L’exemple suivant utilise l’applet de commande Azure PowerShell Import-AzApiManagementApi pour importer un passthrough API GraphQL à partir de l’URL spécifiée dans une instance Gestion des API nommée apim-hello-world.

# Details specific to API Management instance.
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details.
$apiId = "my-graphql-api"
$apiPath = "myapi"
$specificationFormat = "GraphQL"
$specificationUrl = "<GraphQL backend endpoint>"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API.
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

Après avoir importé l’API, vous pouvez mettre à jour les paramètres à l’aide de l’applet de commande Set-AzApiManagementApi , si nécessaire.

Tester votre API GraphQL

1. Accédez à votre instance Gestion des API.

2. Dans le volet gauche, dans la section API , sélectionnez API.

3. Sous Toutes les API, sélectionnez votre API GraphQL.

4. Sélectionnez l’onglet Test pour accéder à la console de test.

5. Sous En-têtes :

   1. Sélectionnez l’en-tête dans le menu Nom .
   2. Entrez la valeur dans la zone Valeur .
   3. Ajoutez d’autres en-têtes en sélectionnant Ajouter un en-tête.
   4. Supprimez les en-têtes à l’aide du bouton corbeille.

6. Si vous avez ajouté un produit à votre API GraphQL, ajoutez une étendue de produit sous Appliquer l’étendue du produit.

7. Dans l’éditeur de requête, effectuez l’une des opérations suivantes :

   1. Sélectionnez au moins un champ ou un sous-champ dans la liste dans le menu à gauche de l’éditeur. Les champs et les sous-champs que vous sélectionnez s’affichent dans l’éditeur de requête.

   2. Commencer à taper dans l’éditeur de requête pour composer une requête.

      

8. Sous Variables de requête, ajoutez des variables pour réutiliser la même requête ou mutation et passer des valeurs différentes.

9. Sélectionnez Envoyer.

10. Consultez la Réponse.

    

11. Répétez les étapes précédentes pour tester différentes charges utiles.

12. Lorsque vous avez terminé le test, quittez la console de test.

Testez un abonnement

Si votre API GraphQL prend en charge un abonnement, vous pouvez tester ce dernier dans la console de test.

1. Vérifiez que votre API autorise un schéma d’URL WebSocket (WS ou WSS) approprié pour votre API. Vous pouvez activer ce paramètre dans l’onglet Paramètres .

2. Configurez une requête d’abonnement dans l’éditeur de requête, puis sélectionnez Connecter pour établir une connexion WebSocket au service back-end.

   

3. Passez en revue les détails de la connexion dans le volet Abonnement.

   

4. Les événements abonnés s’affichent dans le volet Abonnement. La connexion WebSocket est conservée jusqu’à ce que vous la déconnectez ou connectez-vous à un nouvel abonnement WebSocket.

   

Sécuriser votre API GraphQL

Sécurisez l’API GraphQL en appliquant à la fois des stratégies d’authentification et d’autorisation existantes et une stratégie de validation GraphQL pour la protection contre les attaques ciblant GraphQL.

Contenu connexe

• Limitations de l’importation d’API
• Importer une spécification OpenAPI
• Importer une API SOAP
• Importer une API SOAP et la convertir en REST
• Importer une API App Service
• Importer une API d’application conteneur
• Importer une API WebSocket
• Importer une API GraphQL
• Importer un schéma GraphQL et configurer des résolveurs de champs
• Importer une API d’application de fonction
• Importer une API d’application logique
• Importer un service Service Fabric
• Importer une API Azure AI Foundry
• Importer une API Azure OpenAI
• Importer une API LLM
• Importer une API OData
• Exporter une API REST en tant que serveur MCP
• Exposer un serveur MCP existant
• Importer une API d’agent A2A
• Importer des métadonnées OData de SAP
• Importer une API gRPC
• Modifier une API