Documentation sur Oracle Cloud Infrastructure

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

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

Lorsque vous utilisez le service Passerelle d'API, 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 la description de l'API.

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

Vous pouvez éventuellement importer la description de l'API à partir d'un fichier ( parfois appelé ' spécification d'API') écrit dans un langue prise en charge. Actuellement, la spécification OpenAPI version 2.0 (anciennement spécification Swagger 2.0) et version 3.0 sont prises en charge.

Notez que la création d'une ressource d'API dans le service Passerelle d'API est facultative. Vous pouvez déployer une API sur une passerelle d'API sans créer de ressource d'API dans le service Passerelle d'API. Notez également que vous pouvez créer une ressource d'API sans description de l'API initialement, puis ajouter la description plus tard.

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

    2. Spécifiez les valeurs suivantes pour la ressource d'API :

      • Nom : Nom de la ressource d'API. Évitez d'entrer des informations confidentielles.
      • compartiment : compartiment dans lequel créer la ressource d'API.
      • Charger le fichier de description de l'API : (Facultatif) Fichier qui contient la description de l'API (dans un langage pris en charge) à charger et à partir duquel créer la description de l'API. Le fichier peut avoir une taille maximale de 1 Mo. Le fichier est analysé pour confirmer qu'il est dans un langage pris en charge et correctement formaté. Actuellement, les fichiers de spécification OpenAPI version 2.0 (anciennement spécification Swagger 2.0) et version 3.0 sont pris en charge.
      • Afficher les options avancées : Sélectionnez cette option pour appliquer des marqueurs à la ressource. Si vous avez l'autorisation de créer une ressource, vous avez également l'autorisation d'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.

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

      Si vous avez chargé un fichier de description d'API, la description de l'API est créée et validée. La validation de la description de l'API peut prendre quelques minutes. Pendant la validation, la description de l'API est affichée avec l'état Validation dans la page Validations. Lorsque la description de l'API est validée, les actions suivantes se produisent :

      • La page Validations indique que la validation a réussi.
      • La page Description de l'API affiche la description de l'API créée à partir du fichier de description d'API.
      • La page Spécification de déploiement d'API affiche toutes les informations supplémentaires sur la spécification de déploiement d'API par défaut créée à partir de la description de l'API.

      Notez que, plutôt que de créer la ressource d'API immédiatement, vous pourrez la créer ultérieurement à l'aide du gestionnaire de ressources 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 des piles à partir des définitions de ressource, voir Création d'une pile à partir d'une page de création de ressource.

    4. Si vous avez attendu plus de quelques minutes pour que la description de l'API soit valide (ou si l'opération de validation de la description de l'API a échoué), procédez comme suit :

      1. Sélectionnez Demandes de travail pour voir un aperçu de l'opération de validation de la description de l'API.
      2. Sélectionnez l'opération Valider l'API 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 validation de la description de l'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 du service de passerelle d'API.

    5. Si vous n'avez pas chargé de fichier de description d'API lorsque vous avez créé la ressource d'API pour la première fois ou si vous souhaitez ultérieurement charger un fichier de description d'API différent, procédez comme suit :

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

    Après avoir créé une ressource d'API avec la description de l'API, vous pouvez la déployer sur une passerelle d'API. Voir 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 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 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. Évitez d'entrer des informations confidentielles.
      • <compartment-ocid> est l'OCID du compartiment contenant la nouvelle ressource d'API.
      • <api-description> est la description facultative de l'API (dans un langage pris en charge). La valeur que vous spécifiez pour <api-description> peut être :
        • La description complète de l'API, entre guillemets doubles. Dans la description, chaque guillemet double doit être précédé d'une barre oblique (\). Par exemple (et abrégé pour une meilleure lisibilité), --content "swagger:\"2.0\",title:\"Sample API\",..."
        • Le nom et l'emplacement d'un fichier de description d'API, entre guillemets doubles et au format "$(< <path>/<filename>.yaml)". Par exemple, --content "$(< /users/jdoe/api.yaml)"
        La description est analysée pour confirmer qu'elle est dans un langage pris en charge et correctement formatée. Actuellement, les fichiers de spécification OpenAPI version 2.0 (anciennement spécification Swagger 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 comprend les données suivantes :

      • L'OCID de la ressource d'API.
      • L'état du cycle de vie (par exemple, SUCCEEDED, FAILED).
      • L'ID demande de travail permettant de créer la ressource 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 que la ressource d'API soit créée avant de retourner un contrôle (ou si la demande a échoué), 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

      Notez que vous ne pouvez pas utiliser la ressource d'API tant que la demande de travail n'a pas été créée.

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

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

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

      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 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.

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