Documentation Oracle Cloud Infrastructure

Création d'une ressource d'API avec une description d'API

Découvrez comment créer une ressource d'API avec le service API Gateway que vous pouvez utiliser pour déployer une API sur une passerelle d'API.

Lorsque vous utilisez le service API Gateway, vous avez la possibilité de créer une ressource d'API. Vous pouvez utiliser la ressource d'API pour déployer une API sur une passerelle d'API. La ressource d'API contient une description d'API qui décrit l'API.

Si vous utilisez une ressource d'API pour déployer une API sur une passerelle d'API, sa description préremplit certaines des propriétés de la spécification de déploiement d'API.

Vous pouvez éventuellement importer la description d'API à partir d'un fichier (parfois appelé "spécification d'API") écrit dans un langage pris en charge. Actuellement, les spécifications OpenAPI Specification version 2.0 (anciennement Swagger Specification 2.0) et version 3.0 sont prises en charge.

La création d'une ressource d'API dans le service API Gateway est facultative. Vous pouvez déployer une API sur une passerelle d'API sans créer de ressource d'API dans le service API Gateway. Vous pouvez également créer une ressource d'API sans description, puis ajouter une description d'API ultérieurement.

    1. Sur la page de liste API, sélectionnez Créer une API. Si vous avez besoin d'aide pour trouver la page de liste, reportez-vous à Liste des ressources d'API.

    2. Indiquez les valeurs suivantes pour la ressource d'API :

      • Nom : nom de la ressource d'API. Evitez de saisir des informations confidentielles.
      • Compartiment : compartiment dans lequel créer la ressource d'API.
      • Télécharger le fichier de description d'API vers le serveur : (facultatif) fichier contenant la description de l'API (dans un langage pris en charge) à télécharger vers le serveur et à partir duquel créer la description de l'API. Le fichier peut atteindre une taille maximale de 1 Mo. Le fichier est analysé pour vérifier que son langage est pris en charge et que son format est correct. Actuellement, les fichiers OpenAPI Specification version 2.0 (anciennement Swagger Specification 2.0) et version 3.0 sont pris en charge.
      • Afficher les options avancées : sélectionnez cette option pour appliquer des balises à la ressource. Si vous disposez des droits d'accès nécessaires pour créer une ressource, vous disposez également de droits d'accès permettant d'appliquer des balises à format libre à cette ressource. Pour appliquer une balise defined, vous devez disposer des droits d'accès permettant d'utiliser l'espace de noms de balise. Pour plus d'informations sur le balisage, reportez-vous à Balises de ressource. Si vous n'êtes pas certain d'appliquer des balises, ignorez cette option ou demandez à un administrateur. Vous pouvez appliquer des balises ultérieurement.

    3. Sélectionnez Créer une API pour créer la ressource d'API.

      Si vous avez téléchargé un fichier de description d'API vers le serveur, une description d'API est créée et validée. La validation de la description d'API peut prendre quelques minutes. Pendant sa validation, la description d'API est affichée avec l'état En cours de validation sur la page Validations. Lorsque la description d'API a été validée, les actions suivantes se produisent :

      • la page Validations affiche la validation terminée,
      • la page Description d'API affiche la description d'API créée à partir du fichier de description d'API,
      • la page Spécification du déploiement d'API affiche des informations supplémentaires sur la spécification de déploiement d'API par défaut créée à partir de la description d'API.

      Au lieu de créer la ressource d'API immédiatement, vous pouvez la créer ultérieurement à l'aide de Resource Manager et de Terraform. Sélectionnez Enregistrer en tant que pile pour enregistrer la définition de ressource en tant que configuration Terraform. Pour plus d'informations sur l'enregistrement de piles à partir de définitions de ressource, reportez-vous à Création d'une pile à partir d'une page de création de ressource.

    4. Si l'attente de l'affichage de la description d'API comme valide dépasse quelques minutes (ou si l'opération de validation de la description d'API a échoué), procédez comme suit :

      1. Sélectionnez Demandes de travail pour afficher un aperçu de l'opération de validation de la description d'API.
      2. Sélectionnez l'opération Valider l'API pour afficher des informations supplémentaires sur celle-ci (y compris les messages d'erreur, les messages de journalisation et le statut des ressources associées).
      3. Si l'opération de validation de la description d'API a échoué et que vous ne pouvez pas diagnostiquer la cause du problème à partir des informations de la demande de travail. Reportez-vous à Dépannage d'API Gateway.

    5. Si vous n'avez pas téléchargé de fichier de description d'API vers le serveur lors de la création de la ressource d'API ou si vous souhaitez télécharger ultérieurement un autre fichier de description d'API, procédez comme suit :

      1. Sur la page API, sélectionnez Modifier dans le menu Actions (trois points) de la ressource d'API.
      2. Indiquez les détails du fichier de description d'API à partir duquel créer la description d'API.

    Une fois que vous avez créé une ressource d'API avec une description d'API, vous pouvez la déployer sur une passerelle d'API. Reportez-vous à Utilisation de la console pour créer un déploiement d'API à partir d'une ressource d'API.

  • Pour créer une ressource d'API à l'aide de l'interface de ligne de commande, procédez comme suit :

    1. Configurez votre environnement client de façon à pouvoir utiliser l'interface de ligne de commande (Configuration de l'environnement client pour utiliser l'interface de ligne de commande pour le développement de passerelle d'API).
    2. Ouvrez une invite de commande et exécutez oci api-gateway api create pour créer la ressource d'API :
      oci api-gateway api create --display-name "<api-name>" --compartment-id <compartment-ocid> --content "<api-description>"

      où :

      • <api-name> est le nom de la nouvelle ressource d'API. Evitez de saisir des informations confidentielles.
      • <compartment-ocid> est l'OCID du compartiment auquel la nouvelle ressource d'API appartient.
      • <api-description> est une description d'API facultative (dans un langage pris en charge). La valeur que vous indiquez pour <api-description> peut être l'une des suivantes :
        • La description d'API complète, entre des guillemets. Dans la description, chaque guillemet doit être échappé à l'aide d'une barre oblique inverse (\). Par exemple (abrégé pour plus de lisibilité) : --content "swagger:\"2.0\",title:\"Sample API\",..."
        • Le nom et l'emplacement d'un fichier de description d'API, entre guillemets et au format "$(< <path>/<filename>.yaml)". Par exemple : --content "$(< /users/jdoe/api.yaml)"
        La description est analysée pour vérifier que son langage est pris en charge et que son format est correct. Actuellement, les fichiers OpenAPI Specification version 2.0 (anciennement Swagger Specification 2.0) et version 3.0 sont pris en charge.

      Par exemple :

      oci api-gateway api create --display-name "Hello World API Resource" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --content "swagger:\"2.0\",title:\"Sample API\",..."

      La réponse à la commande inclut les éléments suivants :

      • OCID de la ressource d'API.
      • Etat de cycle de vie (par exemple, SUCCEEDED, FAILED).
      • ID de la demande de travail utilisée pour créer la ressource d'API (les détails des demandes de travail sont disponibles pendant sept jours après leur fin, leur annulation ou leur échec).

      Pour que la commande attende que la ressource d'API soit créée (ou que la demande ait échoué) avant de renvoyer le contrôle, incluez l'un des paramètres suivants ou les deux :

      • --wait-for-state SUCCEEDED
      • --wait-for-state FAILED

      Par exemple :

      oci api-gateway api create --display-name "Hello World API Resource" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --content "swagger:\"2.0\",title:\"Sample API\",..." --wait-for-state SUCCEEDED

      Vous ne pouvez pas utiliser la ressource d'API tant que la demande de travail ne l'a pas créée.

    3. (Facultatif) Pour afficher le statut de la demande de travail qui crée la ressource d'API, saisissez ce qui suit :

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

    4. (Facultatif) Pour afficher les journaux de la demande de travail qui crée la ressource d'API, saisissez ce qui suit :

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

    5. (Facultatif) Si la demande de travail qui crée la ressource d'API échoue et que vous voulez consulter les journaux d'erreurs, saisissez ce qui suit :

      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, reportez-vous à Interface de ligne de commande (CLI). Afin d'obtenir la liste complète des indicateurs et des options disponibles pour les commandes de l'interface de ligne de commande, reportez-vous à Aide relative à l'interface de ligne de commande.

  • Exécutez l'opération CreateAPI pour créer une ressource d'API.