Ajout de réponses standard comme élément dorsal du service de passerelle d'API

Découvrez comment définir un chemin vers un élément dorsal de réponse standard au moyen de la passerelle d'API.

Vous aurez souvent besoin de vérifier qu'une API a été déployée sur une passerelle d'API sans avoir à configurer un service dorsal réel. Une approche consiste à définir une route dans la spécification de déploiement d'API, qui comporte un chemin vers un élément dorsal 'factice'. Lors de la réception d'une demande à ce chemin, la passerelle d'API elle-même agit comme élément dorsal et retourne une réponse standard que vous avez spécifiée.

De même, dans certains déploiements de production, vous aurez besoin que le chemin particulier d'une route retourne systématiquement la même réponse standard sans envoyer de demande à l'élément dorsal. Par exemple, lorsque vous voulez qu'un appel à un chemin retourne toujours un code de statut HTTP spécifique dans la réponse.

À l'aide du service Passerelle d'API, vous pouvez définir un chemin vers un élément dorsal de réponse standard qui retourne toujours le même élément suivant :

  • Code de statut HTTP
  • Champs d'en-tête HTTP (paires nom-valeur)
  • Contenu du corps de la réponse

Notez les restrictions suivantes lors de la définition des réponses standard et des éléments dorsaux de réponse standard :

  • Chaque nom d'en-tête ne doit pas dépasser une longueur de 1 Ko.
  • Chaque valeur d'en-tête ne doit pas dépasser une longueur de 4 Ko.
  • Chaque réponse de corps ne doit pas dépasser une longueur de 5 Ko (y compris tout encodage).
  • Une définition d'élément dorsal de réponse standard ne doit pas comporter plus de 50 champs d'en-tête.

Vous pouvez ajouter des éléments dorsaux de réponse standard à une spécification de déploiement d'API comme suit :

  • En utilisant la console.
  • En modifiant un fichier JSON.

Utilisation de la console pour ajouter des réponses standard à une spécification de déploiement d'API

Pour ajouter des réponses standard à une spécification de déploiement d'API à l'aide de la console :

  1. Créez ou mettez à jour un déploiement d'API à l'aide de la console, sélectionnez l'option À partir de zéro et entrez les détails dans la page Informations de base.

    Pour plus d'informations, voir Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API et Mise à jour d'une passerelle d'API.

  2. Dans la page Authentification, spécifiez les options d'authentification.

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

  3. Dans la page Routes, créez une route et spécifiez les données suivantes :

    • 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 :

    • Méthodes : Une ou plusieurs méthodes acceptées par le service dorsal. 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, par exemple Stock Response.
    • Code de statut : Tout code de réponse HTTP valide. Par exemple 200
    • Corps : Spécifie facultativement le contenu du corps de la réponse dans un format approprié. Par exemple :

      • Si vous spécifiez le nom d'en-tête et la valeur d'en-tête comme Content-Type et text/plain respectivement, le corps de la réponse peut être "Hello world".
      • Si vous spécifiez le nom d'en-tête et la valeur d'en-tête comme Content-Type et application/json respectivement, le corps de la réponse peut être {"username": "john.doe"}.

      Notez que le corps de la réponse ne doit pas dépasser une longueur de 5 Ko (y compris tout encodage).

    • Nom d'en-tête et Valeur d'en-tête : Facultativement, vous pouvez spécifier le nom d'un en-tête de réponse HTTP et sa valeur. Par exemple, le nom Content-Type et la valeur application/json. Vous pouvez spécifier plusieurs paires nom d'en-tête et valeur (50 au maximum). Notez que dans chaque cas :

      • Le nom d'en-tête ne doit pas dépasser une longueur de 1 Ko.
      • La valeur d'en-tête ne doit pas dépasser une longueur de 4 Ko.

    Dans cet exemple, une demande au chemin /test retourne le code de statut 200 et des données utiles JSON dans le corps de la réponse.

    Champ : Entrez :
    Chemin : /test
    Méthodes : GET
    Type de service dorsal : Stock Response
    Code de statut : 200
    Corps : {"username": "john.doe"}
    Nom d'en-tête : Content-Type
    Valeur d'en-tête : application/json

    Dans cet exemple, une demande au chemin /test-redirect retourne le code de statut 302 et une URL temporaire dans l'en-tête de la réponse Location.

    Champ : Entrez :
    Chemin : /test-redirect
    Méthodes : GET
    Type de service dorsal : Stock Response
    Code de statut : 302
    Corps : s.o.
    Nom d'en-tête : Location
    Valeur d'en-tête : http://www.example.com
  4. (Facultatif) Sélectionnez Autre route pour entrer les détails des routes supplémentaires.
  5. Sélectionnez Suivant pour vérifier les détails que vous avez entrés pour le déploiement d'API.
  6. Sélectionnez Créer ou enregistrer les modifications pour créer ou mettre à jour le déploiement d'API.
  7. (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).

Modification d'un fichier JSON pour ajouter des réponses standard à une spécification de déploiement d'API

Pour ajouter des réponses standard à une spécification de déploiement d'API dans un fichier JSON :

  1. Dans votre éditeur JSON préféré, modifiez la spécification de déploiement d'API existante à laquelle vous souhaitez ajouter une réponse standard ou créez une spécification de déploiement d'API (voir Création d'une spécification de déploiement d'API).

    Par exemple, la spécification de déploiement d'API de base suivante définit une simple fonction sans serveur Hello World du service des fonctions pour OCI en tant qu'élément dorsal unique :

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }
  2. Dans la section routes, incluez une nouvelle section path pour un élément dorsal de réponse standard :

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        },
        {
          "path": "<api-route-path>",
          "methods": ["<method-list>"],
          "backend": {
            "type": "STOCK_RESPONSE_BACKEND",
            "status": <http-response-code>,
            "headers": [{
              "name": "<header-name>",
              "value": "<header-value>"
            }],
            "body": "<body-content>"
          }
        }
      ]
    }

    où :

    • <api-route-path> indique le chemin des appels d'API utilisant les méthodes indiquées à l'élément dorsal de réponse standard. Notez que le chemin de routage que vous spécifiez :

    • <method-list> indique une ou plusieurs méthodes acceptées par l'élément dorsal de réponse standard, séparées par des virgules. Par exemple, "GET, PUT".
    • "type": "STOCK_RESPONSE_BACKEND" indique que la passerelle d'API elle-même agit comme élément dorsal et retourne la réponse standard que vous définissez (code de statut, champs d'en-tête et contenu du corps).
    • <http-response-code> représente tout code de réponse HTTP valide. Par exemple 200
    • "name": "<header-name>", "value": "<header-value>" spécifie facultativement le nom d'un en-tête de réponse HTTP et sa valeur. Par exemple, "name": "Content-Type", "value":"application/json". Vous pouvez spécifier plusieurs paires "name": "<header-name>", "value": "<header-value>" dans la section headers: (jusqu'à un maximum de 50). Notez que dans chaque cas :
      • <header-name> ne doit pas dépasser une longueur de 1 Ko.
      • <header-value> ne doit pas dépasser une longueur de 4 Ko.
    • "body": "<body-content>" spécifie facultativement le contenu du corps de réponse dans un format approprié. Par exemple :
      • Si l'en-tête Content-Type est text/plain, le corps de la réponse peut être "body": "Hello world".
      • Si l'en-tête Content-Type est application/json, le corps de la réponse peut être "body": "{\"username\": \"john.doe\"}". Dans le cas d'une réponse JSON, notez que les guillemets de la réponse doivent faire l'objet d'un échappement avec une barre oblique inverse (\).

      Notez que <body-content> ne doit pas dépasser une longueur de 5 Ko (y compris tout encodage).

    Dans cet exemple, une demande au chemin /test retourne le code de statut 200 et des données utiles JSON dans le corps de la réponse.

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        },
        {
          "path": "/test",
          "methods": ["GET"],
          "backend": {
            "type": "STOCK_RESPONSE_BACKEND",
            "status": 200,
            "headers": [{
              "name": "Content-Type",
              "value": "application/json"
            }],
            "body" : "{\"username\": \"john.doe\"}"
          }
        }
      ]
    }

    Dans cet exemple, une demande au chemin /test-redirect retourne le code de statut 302 et une URL temporaire dans l'en-tête de la réponse Location. Cet exemple montre également que vous pouvez créer une spécification de déploiement d'API avec une seule route vers un élément dorsal de type STOCK_RESPONSE_BACKEND.

    {
      "routes": [
        {
          "path": "/test-redirect",
          "methods": ["GET"],
          "backend": {
            "type": "STOCK_RESPONSE_BACKEND",
            "status": 302,
            "headers": [{
              "name": "Location",
              "value": "http://www.example.com"
            }]
          }
        }
      ]
    }
  3. Enregistrez le fichier JSON contenant la spécification de déploiement d'API.
  4. Utilisez comme suit la spécification de déploiement d'API lorsque vous créez ou mettez à jour un déploiement d'API :

    • En spécifiant le fichier JSON dans la console lorsque vous sélectionnez l'option Charger une API existante.
    • En spécifiant le fichier JSON dans une demande à l'API REST du service Passerelle d'API.

    Pour plus d'informations, voir Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API et Mise à jour d'une passerelle d'API.

  5. (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).