Documentation sur Oracle Cloud Infrastructure

Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API

Découvrez comment déployer une API sur une passerelle d'API en créant un déploiement d'API avec le service de passerelle d'API.

Ayant créé une passerelle d'API, vous déployez une API sur la passerelle en créant un déploiement d'API. Lorsque vous créez un déploiement d'API, vous incluez une spécification de déploiement d'API qui définit l'API. Le service Passerelle d'API inspecte la spécification de déploiement d'API pour confirmer qu'elle est valide.

Vous pouvez utiliser une seule passerelle d'API comme élément frontal pour plusieurs services dorsaux comme suit :

  • En créant un seul déploiement d'API sur la passerelle d'API, avec une spécification de déploiement d'API qui définit plusieurs services dorsaux.
  • En créant plusieurs déploiements d'API sur la même passerelle d'API, chacun avec une spécification de déploiement d'API qui définit un ou plusieurs services dorsaux.

Utilisation de la console pour créer un déploiement d'API à partir de zéro

Pour utiliser la console afin de créer un déploiement d'API, en entrant la spécification de déploiement d'API dans les boîtes de dialogue de la console au fur et à mesure :

  1. Dans la page de liste Passerelles, sélectionnez la passerelle d'API sur laquelle déployer l'API. Si vous avez besoin d'aide pour trouver la page de liste ou la passerelle d'API, voir Liste des passerelles d'API.
  2. Dans la page Détails de la passerelle, sélectionnez Déploiements dans la liste Ressources, puis Créer un déploiement.

  3. Sélectionnez À partir de zéro et dans la section Informations de base, spécifiez les données suivantes :

    • Nom : Nom du nouveau déploiement d'API. Évitez d'entrer des informations confidentielles.

    • Préfixe du chemin : Chemin sur lequel déployer toutes les routes contenues dans la spécification de déploiement d'API. Par exemple :

      • /v1
      • /v2
      • /test/20191122

      Notez que le préfixe du chemin de déploiement que vous spécifiez :

      • Doit être précédé d'une barre verticale (/) et peut être simplement cette seule.
      • Peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes), mais ne doit pas se terminer par une barre oblique.
      • Peut inclure des caractères alphanumériques en majuscules et en minuscules.
      • peut inclure les caractères spéciaux $ - _ . + ! * ' ( ) , % ; : @ & =
      • Ne peut pas inclure des paramètres et des caractères génériques.

      Notez également que si un déploiement d'API comporte une barre oblique unique comme préfixe de chemin de déploiement, il s'agit du seul déploiement d'API autorisé sur une passerelle d'API donnée. Vous ne pouvez pas créer un déploiement d'API avec une barre oblique unique comme préfixe de chemin de déploiement s'il existe déjà un autre déploiement d'API sur la même passerelle d'API.

    • Compartiment : Compartiment dans lequel créer le nouveau déploiement d'API.

  4. (Facultatif) Dans la section Politiques de demande d'API, spécifiez les détails de la politique de demande pour fournir la prise en charge des éléments suivants :

  5. (Facultatif) Dans la section API Politiques de journalisation d'API, spécifiez éventuellement un niveau de journal d'exécution pour enregistrer les informations sur le traitement dans la passerelle d'API. Voir Ajout de la journalisation aux déploiements d'API.

  6. (Facultatif) Sélectionnez Afficher les options avancées et, facultativement, spécifiez :

    • Marqueurs : Si vous êtes autorisé à créer une ressource, vous disposez également des autorisations nécessaires pour appliquer des marqueurs à structure libre à cette ressource. Pour appliquer un marqueur défini, vous devez être autorisé à utiliser l'espace de noms de marqueur. Pour plus d'informations sur le marquage, voir Marqueurs de ressource. Si vous ne savez pas si vous devez appliquer des marqueurs, ignorez cette option ou demandez à un administrateur. Vous pouvez appliquer des marqueurs plus tard.
  7. Sélectionnez Suivant pour afficher la page Authentification et entrez les détails d'une politique de demande d'authentification :

    Pour plus d'informations, voir Ajout de l'authentification et de l'autorisation aux déploiements d'API.

  8. Sélectionnez Suivant pour entrer les détails des routes du déploiement d'API.

  9. Dans la section Route 1, spécifiez la première route du déploiement d'API qui mappe un chemin et une ou plusieurs méthodes à un service dorsal :

    • Chemin : Chemin des appels d'API utilisant les méthodes indiquées au service dorsal. Notez que le chemin de routage que vous spécifiez :

      • Est relatif au préfixe du chemin de déploiement.
      • Doit être précédé d'une barre oblique (/) et peut être simplement cette seule barre oblique.
      • Peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes) et peut se terminer par une barre oblique.
      • Peut inclure des caractères alphanumériques en majuscules et en minuscules.
      • peut inclure les caractères spéciaux $ - _ . + ! * ' ( ) , % ; : @ & =
      • Peut inclure des paramètres et des caractères génériques (voir Ajout de paramètres de chemin et de caractères génériques aux chemins de routage).
    • Méthodes : Une ou plusieurs méthodes acceptées par le service dorsal, séparées par des virgules. Par exemple, GET, PUT.

    • Ajouter un seul serveur dorsal ou Ajouter plusieurs serveurs dorsaux : Indique si toutes les demandes doivent être acheminées vers le même serveur dorsal ou si elles doivent être acheminées vers différents serveurs dorsaux en fonction de la variable de contexte et des règles que vous entrez.

      Ces instructions supposent que vous voulez utiliser un seul élément dorsal. Sélectionnez donc Ajouter un seul élément dorsal. Sinon, si vous voulez utiliser des éléments dorsaux différents, sélectionnez Ajouter plusieurs éléments dorsaux et suivez les instructions sous Utilisation de la console pour ajouter une sélection d'élément dorsal dynamique à une spécification de déploiement d'API.

    • Type dorsal : Type du service dorsal, parmi l'un des suivants :
  10. (Facultatif) Sélectionnez Autre route pour entrer les détails des routes supplémentaires.
  11. Sélectionnez Suivant pour vérifier les détails que vous avez entrés pour le nouveau déploiement d'API.

  12. Sélectionnez Créer pour créer le déploiement d'API.

    Notez que la création du déploiement d'API peut prendre quelques minutes. Lors de sa création, le déploiement d'API est affiché avec l'état Création dans la page Détails de la passerelle. Lorsqu'il a été créé avec succès, le nouveau déploiement d'API est affiché avec l'état Actif.

    Notez également que, plutôt que de créer immédiatement le nouveau déploiement d'API, vous pouvez le créer ultérieurement à l'aide du gestionnaire de ressources et de Terraform, en sélectionnant Enregistrer en tant que pile pour enregistrer la définition de ressource en tant que configuration Terraform. Pour plus d'informations sur l'enregistrement des piles à partir des définitions de ressource, voir Création d'une pile à partir d'une page de création de ressource.

  13. Si vous avez attendu pendant plus que quelques minutes pour que le déploiement d'API soit affiché avec l'état Actif (ou si l'opération de création du déploiement d'API a échoué) :

    1. Sélectionnez le nom du déploiement d'API, puis Demandes de travail pour voir un aperçu de l'opération de création du déploiement d'API.
    2. Sélectionnez l'opération Créer un déploiement pour voir plus d'informations sur l'opération (notamment les messages d'erreur, les messages de journal et le statut des ressources associées).
    3. Si l'opération de création du déploiement d'API a échoué et que vous ne pouvez pas diagnostiquer la cause du problème à partir des informations de la demande de travail, voir Dépannage de passerelle d'API.
  14. (Facultatif) Vérifiez que l'API a été déployée avec succès en l'appelant (voir Appel d'une API déployée sur une passerelle d'API).

Utilisation de la console pour créer un déploiement d'API à partir d'un fichier JSON

Pour utiliser la console afin de créer un déploiement d'API, en chargeant la spécification de déploiement d'API à partir d'un fichier JSON :

  1. Dans la page de liste Passerelles, sélectionnez la passerelle d'API sur laquelle déployer l'API. Si vous avez besoin d'aide pour trouver la page de liste ou la passerelle d'API, voir Liste des passerelles d'API.
  2. Dans la page Détails de la passerelle, sélectionnez Déploiements dans la liste Ressources, puis Créer un déploiement.
  3. Sélectionnez Charger une API existante.

  4. Dans la section Charger les informations, spécifiez les données suivantes :

    • Nom : Nom du nouveau déploiement d'API. Évitez d'entrer des informations confidentielles.

    • Préfixe du chemin : Chemin sur lequel déployer toutes les routes contenues dans la spécification de déploiement d'API. Par exemple :

      • /v1
      • /v2
      • /test/20191122

      Notez que le préfixe du chemin de déploiement que vous spécifiez :

      • Doit être précédé d'une barre verticale (/) et peut être simplement cette seule.
      • Peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes), mais ne doit pas se terminer par une barre oblique.
      • Peut inclure des caractères alphanumériques en majuscules et en minuscules.
      • peut inclure les caractères spéciaux $ - _ . + ! * ' ( ) , % ; : @ & =
      • Ne peut pas inclure des paramètres et des caractères génériques.
    • Compartiment : Compartiment dans lequel créer le nouveau déploiement d'API.
    • Specification : Fichier JSON contenant la spécification de déploiement d'API, soit par glisser-déposer du fichier, soit en sélectionnant en sélectionner un. Voir Création d'une spécification de déploiement d'API.

    Notez également que si un déploiement d'API comporte une barre oblique unique comme préfixe de chemin de déploiement, il s'agit du seul déploiement d'API autorisé sur une passerelle d'API donnée. Vous ne pouvez pas créer un déploiement d'API avec une barre oblique unique comme préfixe de chemin de déploiement s'il existe déjà un autre déploiement d'API sur la même passerelle d'API.

  5. (Facultatif) Sélectionnez Afficher les options avancées et, facultativement, spécifiez :

    • Marqueurs : Si vous êtes autorisé à créer une ressource, vous disposez également des autorisations nécessaires pour appliquer des marqueurs à structure libre à cette ressource. Pour appliquer un marqueur défini, vous devez être autorisé à utiliser l'espace de noms de marqueur. Pour plus d'informations sur le marquage, voir Marqueurs de ressource. Si vous ne savez pas si vous devez appliquer des marqueurs, ignorez cette option ou demandez à un administrateur. Vous pouvez appliquer des marqueurs plus tard.
  6. Sélectionnez Suivant pour vérifier les détails que vous avez entrés pour le nouveau déploiement d'API.

  7. Sélectionnez Créer pour créer le déploiement d'API.

    Notez que la création du déploiement d'API peut prendre quelques minutes. Lors de sa création, le déploiement d'API est affiché avec l'état Création dans la page Détails de la passerelle. Lorsqu'il a été créé avec succès, le nouveau déploiement d'API est affiché avec l'état Actif.

    Notez également que, plutôt que de créer immédiatement le nouveau déploiement d'API, vous pouvez le créer ultérieurement à l'aide du gestionnaire de ressources et de Terraform, en sélectionnant Enregistrer en tant que pile pour enregistrer la définition de ressource en tant que configuration Terraform. Pour plus d'informations sur l'enregistrement des piles à partir des définitions de ressource, voir Création d'une pile à partir d'une page de création de ressource.

  8. Si vous avez attendu pendant plus que quelques minutes pour que le déploiement d'API soit affiché avec l'état Actif (ou si l'opération de création du déploiement d'API a échoué) :

    1. Sélectionnez le nom du déploiement d'API, puis Demandes de travail pour voir un aperçu de l'opération de création du déploiement d'API.
    2. Sélectionnez l'opération Créer un déploiement pour voir plus d'informations sur l'opération (notamment les messages d'erreur, les messages de journal et le statut des ressources associées).
    3. Si l'opération de création du déploiement d'API a échoué et que vous ne pouvez pas diagnostiquer la cause du problème à partir des informations de la demande de travail, voir Dépannage de passerelle d'API.
  9. (Facultatif) Vérifiez que l'API a été déployée avec succès en l'appelant (voir Appel d'une API déployée sur une passerelle d'API).

Utilisation de la console pour créer un déploiement d'API à partir d'une ressource d'API

Vous pouvez créer un déploiement d'API à partir d'une ressource d'API existante à l'aide de la description de l'API de cette ressource. Dans ce cas, la description de l'API est basée sur un fichier de description d'API que vous avez chargé pour la ressource d'API (voir Création d'une ressource d'API avec description de l'API). Le fichier de description d'API fournit quelques valeurs initiales pour la spécification de déploiement d'API, que vous pouvez modifier et étendre lors de la création du déploiement d'API. En particulier, une route par défaut est créée pour chaque chemin et méthode associée dans la description de l'API.

Pour utiliser la console afin de créer un déploiement d'API à partir d'une ressource d'API existante, à l'aide d'une spécification de déploiement d'API dérivée d'un fichier de description d'API :

  1. Dans la page de liste API, sélectionnez le nom de la ressource d'API à déployer. Si vous avez besoin d'aide pour trouver la page de liste, voir Liste des ressources d'API.
  2. (Facultatif) Dans la page Détails de l'API, sélectionnez Spécification de déploiement d'API dans la liste Ressources pour confirmer qu'une spécification de déploiement d'API valide a été créée pour la ressource d'API à partir d'un fichier de description d'API chargé. Si aucune spécification de déploiement d'API n'est disponible, voir Création d'une ressource d'API avec description de l'API
  3. Dans la page Détails de l'API, sélectionnez Déployer la passerelle d'API afin d'utiliser les boîtes de dialogue de la console pour créer un déploiement d'API.

    Certaines des valeurs initiales des propriétés de spécification de déploiement d'API affichées dans les boîtes de dialogues de la console sont dérivées du fichier de description d'API.

    La section Données d'API présente des détails sur la ressource d'API à partir de laquelle créer le déploiement d'API.

  4. Dans la section Passerelle, sélectionnez la passerelle d'API sur laquelle créer le déploiement d'API. Si une passerelle d'API appropriée n'existe pas déjà, sélectionnez Créer une passerelle pour en créer une (voir Création d'une passerelle d'API).

  5. Dans la section Informations de base, spécifiez les données suivantes :

    • Nom : Nom du nouveau déploiement d'API. Évitez d'entrer des informations confidentielles.

    • Préfixe du chemin : Chemin sur lequel déployer toutes les routes contenues dans la spécification de déploiement d'API.

      Par exemple :

      • /v1
      • /v2
      • /test/20191122

      Notez que le préfixe du chemin de déploiement que vous spécifiez :

      • Doit être précédé d'une barre verticale (/) et peut être simplement cette seule.
      • Peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes), mais ne doit pas se terminer par une barre oblique.
      • Peut inclure des caractères alphanumériques en majuscules et en minuscules.
      • peut inclure les caractères spéciaux $ - _ . + ! * ' ( ) , % ; : @ & =
      • Ne peut pas inclure des paramètres et des caractères génériques.

      Notez également que si un déploiement d'API comporte une barre oblique unique comme préfixe de chemin de déploiement, il s'agit du seul déploiement d'API autorisé sur une passerelle d'API donnée. Vous ne pouvez pas créer un déploiement d'API avec une barre oblique unique comme préfixe de chemin de déploiement s'il existe déjà un autre déploiement d'API sur la même passerelle d'API.

    • Compartiment : Compartiment dans lequel créer le nouveau déploiement d'API.

  6. (Facultatif) Dans la section Politiques de demande d'API, spécifiez les détails de la politique de demande pour fournir la prise en charge des éléments suivants :

  7. (Facultatif) Dans la section API Politiques de journalisation d'API, spécifiez éventuellement un niveau de journal d'exécution pour enregistrer les informations sur le traitement dans la passerelle d'API. Voir Ajout de la journalisation aux déploiements d'API.

  8. (Facultatif) Sélectionnez Afficher les options avancées et, facultativement, spécifiez :

    • Marqueurs : Si vous êtes autorisé à créer une ressource, vous disposez également des autorisations nécessaires pour appliquer des marqueurs à structure libre à cette ressource. Pour appliquer un marqueur défini, vous devez être autorisé à utiliser l'espace de noms de marqueur. Pour plus d'informations sur le marquage, voir Marqueurs de ressource. Si vous ne savez pas si vous devez appliquer des marqueurs, ignorez cette option ou demandez à un administrateur. Vous pouvez appliquer des marqueurs plus tard.

  9. Sélectionnez Suivant pour vérifier et entrer les détails des routes du déploiement d'API.

    Par défaut, une route est créée pour chaque chemin et méthode associée présents dans la description de l'API. Initialement, chacune de ces routes par défaut est créée avec un élément dorsal de réponse standard. Le code de statut HTTP, le contenu du corps de la réponse et l'en-tête sont obtenus à partir des détails de la description de l'API. Si la description de l'API n'inclut pas d'informations de réponse pour un chemin et une méthode associée spécifiques, un élément dorsal de réponse standard par défaut est créé pour cette route avec 501 comme code de statut HTTP.

  10. Vérifiez chaque route par défaut, modifiez leur configuration si nécessaire pour répondre à vos besoins et ajoutez des politiques de demande, de réponse et de journalisation :

  11. (Facultatif) Sélectionnez une autre route pour entrer les détails des routes supplémentaires, en plus de celles créées par défaut à partir de la description de l'API.
  12. Sélectionnez Suivant pour vérifier les détails que vous avez entrés pour le nouveau déploiement d'API.

  13. Sélectionnez Créer pour créer le déploiement d'API.

    Notez que la création du déploiement d'API peut prendre quelques minutes. Lors de sa création, le déploiement d'API est affiché avec l'état Création dans la page Détails de la passerelle. Lorsqu'il a été créé avec succès, le nouveau déploiement d'API est affiché avec l'état Actif.

  14. Si vous avez attendu pendant plus que quelques minutes pour que le déploiement d'API soit affiché avec l'état Actif (ou si l'opération de création du déploiement d'API a échoué) :

    1. Sélectionnez le nom du déploiement d'API, puis Demandes de travail pour voir un aperçu de l'opération de création du déploiement d'API.
    2. Sélectionnez l'opération Créer un déploiement pour voir plus d'informations sur l'opération (notamment les messages d'erreur, les messages de journal et le statut des ressources associées).
    3. Si l'opération de création du déploiement d'API a échoué et que vous ne pouvez pas diagnostiquer la cause du problème à partir des informations de la demande de travail, voir Dépannage de passerelle d'API.
  15. (Facultatif) Vérifiez que l'API a été déployée avec succès en l'appelant (voir Appel d'une API déployée sur une passerelle d'API).

Utilisation de l'interface de ligne de commande

Pour créer un déploiement d'API à l'aide de l'interface de ligne de commande :

  1. Configurez l'environnement client pour utiliser l'interface de ligne de commande (Configuration de l'environnement client afin d'utiliser l'interface de ligne de commande pour le développement de passerelles d'API).

  2. Ouvrez une invite de commande et exécutez oci api-gateway deployment create pour créer le déploiement :

    oci api-gateway deployment create --compartment-id <compartment-ocid> --display-name <api-name> --gateway-id <gateway-ocid> --path-prefix "/<deployment-path-prefix>" --specification file:///<filename>

    où :

    • <compartment-ocid> est l'OCID du compartiment dans lequel créer le déploiement d'API.
    • <api-name> est le nom du nouveau déploiement d'API. Évitez d'entrer des informations confidentielles.
    • <gateway-ocid> est l'OCID de la passerelle existante sur laquelle déployer l'API. Pour connaître l'OCID de la passerelle d'API, voir Liste des passerelles d'API.

    • /<deployment-path-prefix> est un chemin sur lequel déployer toutes les routes contenues dans la spécification de déploiement d'API.

      Notez que le préfixe du chemin de déploiement que vous spécifiez :

      • Doit être précédé d'une barre oblique (/) dans le fichier JSON et ne peut être que cette seule.
      • Peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes), mais ne doit pas se terminer par une barre oblique.
      • Peut inclure des caractères alphanumériques en majuscules et en minuscules.
      • peut inclure les caractères spéciaux $ - _ . + ! * ' ( ) , % ; : @ & =
      • Ne peut pas inclure des paramètres et des caractères génériques.

      Notez également que si un déploiement d'API comporte une barre oblique unique comme préfixe de chemin de déploiement, il s'agit du seul déploiement d'API autorisé sur une passerelle d'API donnée. Vous ne pouvez pas créer un déploiement d'API avec une barre oblique unique comme préfixe de chemin de déploiement s'il existe déjà un autre déploiement d'API sur la même passerelle d'API.

    • <filename> est la spécification de déploiement d'API, notamment un chemin, une ou plusieurs méthodes et une définition d'élément dorsal. Voir Création d'une spécification de déploiement d'API.

    Par exemple :

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json

    La réponse à la commande comprend les données suivantes :

    • L'OCID du déploiement d'API.

    • Le nom d'hôte dans lequel le déploiement d'API a été créé, en tant que nom de domaine au format <gateway-identifier>.apigateway.<region-identifier>.oci.customer-oci.com, où :

      • <gateway-identifier> est la chaîne de caractères qui identifie la passerelle d'API. Par exemple, lak...sjd (abrégé pour une meilleure lisibilité).
      • <region-identifier> est l'identificateur de la région dans laquelle le déploiement d'API a été créé. Voir Disponibilité par région.

      Par exemple, lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com.

      Le nom d'hôte sera le nom du domaine à utiliser lors de l'appel d'une API déployée sur la passerelle d'API.

    • L'état du cycle de vie (par exemple, ACTIVE, FAILED).
    • L'ID demande de travail permettant de créer le déploiement d'API (les détails des demandes de travail sont disponibles pendant sept jours après l'achèvement, l'annulation ou l'échec).

    Si vous souhaitez que la commande attende avant de retourner un contrôle tant que le déploiement d'API n'est pas actif (ou que la demande a échoué), incluez l'un des paramètres suivants ou les deux :

    • --wait-for-state ACTIVE
    • --wait-for-state FAILED

    Par exemple :

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json --wait-for-state ACTIVE

    Notez que vous ne pouvez pas utiliser le déploiement d'API tant que la demande de travail ne l'a pas créé et que le déploiement d'API n'est pas actif.

  3. (Facultatif) Pour voir le statut du déploiement d'API, entrez :

    oci api-gateway deployment get --deployment-id <deployment-ocid>

  4. (Facultatif) Pour voir le statut de la demande de travail qui crée le déploiement d'API, entrez :

    oci api-gateway work-request get --work-request-id <work-request-ocid>

  5. (Facultatif) Pour voir les journaux de la demande de travail qui crée le déploiement d'API, entrez :

    oci api-gateway work-request-log list --work-request-id <work-request-ocid>

  6. (Facultatif) Si la demande de travail qui crée le déploiement d'API échoue et que vous voulez vérifier les journaux d'erreurs, entrez :

    oci api-gateway work-request-error --work-request-id <work-request-ocid>

Pour plus d'informations sur l'utilisation de l'interface de ligne de commande, voir Interface de ligne de commande. Pour la liste complète des indicateurs et des options disponibles pour les commandes d'interface de ligne de commande, voir Aide sur l'interface de ligne de commande.