Ajout de réponses par défaut en tant que back-end de passerelle d'API
Découvrez comment définir un chemin vers un back-end de réponse en stock avec API Gateway.
Vous pouvez régulièrement vérifier qu'une API a été correctement déployée sur une passerelle d'API sans avoir à configurer un service back-end réel. Pour ce faire, vous pouvez définir un routage dans la spécification de déploiement d'API possédant un chemin vers un back-end fictif. Lors de la réception d'une demande pour ce chemin, la passerelle d'API fait elle-même office de back-end et renvoie une réponse par défaut que vous avez spécifiée.
De même, dans un déploiement de production, certaines situations exigent qu'un chemin particulier renvoie systématiquement la même réponse par défaut sans envoyer de demande à un back-end. Par exemple, lorsque vous voulez qu'un appel vers un chemin renvoie toujours un code de statut HTTP spécifique dans la réponse.
Le service API Gateway vous permet de définir un chemin vers un back-end de réponse par défaut qui renvoie toujours les éléments suivants à l'identique :
- code de statut HTTP,
- champs d'en-tête HTTP (paires nom-valeur),
- contenu du corps de la réponse.
Les restrictions suivantes s'appliquent lors de la définition de réponses par défaut et des back-ends de réponse par défaut :
- La longueur de chaque nom d'en-tête ne doit pas dépasser 1 ko.
- La longueur de chaque valeur d'en-tête ne doit pas dépasser 4 ko.
- La longueur de chaque corps de réponse ne doit pas dépasser 5 ko (encodage compris).
- Une définition de back-end de réponse par défaut ne doit pas inclure plus de 50 champs d'en-tête.
Vous pouvez ajouter des back-ends de réponse par défaut à une spécification de déploiement d'APi en :
- utilisant la console,
- modifiant un fichier JSON.
Utilisation de la console pour ajouter des réponses par défaut à une spécification de déploiement d'API
Pour ajouter des réponses par défaut à une spécification de déploiement d'API à l'aide de la console, procédez comme suit :
-
Créez ou mettez à jour un déploiement d'API à l'aide de la console, sélectionnez l'option Entièrement nouveau, puis saisissez les détails sur la page Informations de base.
Pour plus d'informations, reportez-vous à 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.
-
Sur la page Authentification, indiquez les options d'authentification.
Pour plus d'informations sur les options d'authentification, reportez-vous à Ajout de l'authentification et de l'autorisation aux déploiements d'API.
-
Sur la page Routages, créez un routage et spécifiez les éléments suivants :
-
Chemin : chemin pour les appels d'API utilisant les méthodes répertoriées vers le service back-end. Le chemin d'accès que vous spécifiez doit remplir les conditions suivantes :
- Il doit être relatif au préfixe de chemin de déploiement (reportez-vous à Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API).
- Il doit être précédé d'une barre oblique (/). Il peut également consister en une unique barre oblique.
- Il peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes), ainsi que se terminer par une barre oblique.
- Il peut inclure des caractères alphanumériques en majuscules et minuscules.
- Il peut inclure les caractères spéciaux
$ - _ . + ! * ' ( ) , % ; : @ & =
. - Il peut inclure des paramètres et des caractères génériques (reportez-vous à Ajout de paramètres de chemin et de caractères génériques aux chemins de routage).
- Méthodes : méthodes acceptées par le service back-end. Par exemple,
GET, PUT
. -
Ajouter un seul back-end : ou Ajouter plusieurs back-ends : indique si toutes les demandes doivent être acheminées vers le même back-end ou si elles doivent l'être vers d'autres back-ends en fonction de la variable de contexte et des règles que vous entrez.
Ces instructions supposent que vous souhaitez utiliser un back-end unique. Sélectionnez donc Ajouter un back-end unique. Si vous souhaitez utiliser des back-ends différents, vous pouvez également sélectionner Ajouter plusieurs back-ends et suivre les instructions fournies dans Utilisation de la console pour ajouter une sélection de back-end dynamique à une spécification de déploiement d'API.
- Type de back-end : type du service back-end (
Stock Response
). - Code de statut : tout code de réponse HTTP valide. Par exemple,
200
. -
Corps : indique éventuellement le contenu du corps de la réponse au format approprié. Par exemple :
- Si pour Nom d'en-tête et Valeur d'en-tête vous renseignez respectivement les valeurs
Content-Type
ettext/plain
, le corps de la réponse peut être"Hello world"
. - Si pour Nom d'en-tête et Valeur d'en-tête vous renseignez respectivement les valeurs
Content-Type
etapplication/json
, le corps de la réponse peut être{"username": "john.doe"}
.
Le corps de la réponse ne doit pas dépasser 5 ko (encodage compris).
- Si pour Nom d'en-tête et Valeur d'en-tête vous renseignez respectivement les valeurs
-
Nom d'en-tête et Valeur d'en-tête : vous pouvez éventuellement indiquer le nom d'un en-tête de réponse HTTP et sa valeur. Par exemple, le nom
Content-Type
et la valeurapplication/json
. Vous pouvez indiquer plusieurs paires nom-valeur d'en-tête (50 au maximum). Dans chaque cas, vous devez respecter les conditions suivantes :- La longueur du nom d'en-tête ne doit pas dépasser 1 ko.
- La longueur de la valeur d'en-tête ne doit pas dépasser 4 ko.
Dans cet exemple, une demande adressée au chemin
/test
renvoie un code de statut 200 et une charge utile JSON dans le corps de la réponse.Champ : Saisissez ce qui suit : Chemin : /test
Méthodes : GET
Type de back-end: 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 adressée au chemin
/test-redirect
renvoie un code de statut 302, ainsi qu'une URL temporaire dans l'en-têteLocation
de la réponse.Champ : Saisissez ce qui suit : Chemin : /test-redirect
Méthodes : GET
Type de back-end: Stock Response
Code de statut : 302
Corps : N/A Nom d'en-tête : Location
Valeur d'en-tête : http://www.example.com
-
- (Facultatif) Sélectionnez Autre routage pour saisir les détails d'autres routages.
- Sélectionnez Suivant afin de vérifier les détails saisis pour le déploiement d'API.
- Sélectionnez Créer ou Enregistrer les modifications pour créer ou mettre à jour le déploiement d'API.
- (Facultatif) Vérifiez que l'API a été déployée en l'appelant (reportez-vous à Appel d'une API déployée sur une passerelle d'API).
Modification d'un fichier JSON pour ajouter des réponses par défaut à une spécification de déploiement d'API
Pour ajouter des réponses par défaut à une spécification de déploiement d'API dans un fichier JSON, procédez comme suit :
-
A l'aide de l'éditeur JSON de votre choix, modifiez la spécification de déploiement d'API existante à laquelle vous voulez ajouter un back-end de réponse par défaut ou créez une spécification de déploiement d'API (reportez-vous à 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 fonction simple sans serveur Hello World dans OCI Functions en tant que back-end unique :
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Dans la section
routes
, incluez une nouvelle sectionpath
pour un back-end de réponse par défaut :{ "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 un chemin pour les appels d'API utilisant les méthodes répertoriées vers le back-end de réponse par défaut. Le chemin d'accès que vous spécifiez doit remplir les conditions suivantes :- Il doit être relatif au préfixe de chemin de déploiement (reportez-vous à Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API).
- Il doit être précédé d'une barre oblique (/). Il peut également consister en une unique barre oblique.
- Il peut contenir plusieurs barres obliques (à condition qu'elles ne soient pas adjacentes), ainsi que se terminer par une barre oblique.
- Il peut inclure des caractères alphanumériques en majuscules et minuscules.
- Il peut inclure les caractères spéciaux
$ - _ . + ! * ' ( ) , % ; : @ & =
. -
Il peut inclure des paramètres et des caractères génériques (reportez-vous à Ajout de paramètres de chemin et de caractères génériques aux chemins de routage).
<method-list>
indique les méthodes acceptées par le back-end de réponse par défaut, séparées par des virgules. Par exemple,"GET, PUT"
."type": "STOCK_RESPONSE_BACKEND"
indique que la passerelle d'API fait elle-même office de back-end et renvoie la réponse par défaut que vous avez définie (code de statut, champs d'en-tête et contenu du corps).<http-response-code>
représente n'importe quel code de réponse HTTP valide. Par exemple,200
."name": "<header-name>", "value": "<header-value>"
(facultatif) indique 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 sectionheaders:
(50 au maximum). Dans chaque cas, vous devez respecter les conditions suivantes :- La longueur de
<header-name>
ne doit pas dépasser 1 ko. - La longueur de
<header-value>
ne doit pas dépasser 4 ko.
- La longueur de
"body": "<body-content>"
(facultatif) spécifie le contenu du corps de la réponse au format approprié. Par exemple :- Si l'en-tête
Content-Type
correspond àtext/plain
, le corps de la réponse peut être"body": "Hello world"
. - Si l'en-tête
Content-Type
correspond àapplication/json
, le corps de la réponse peut être"body": "{\"username\": \"john.doe\"}"
. Dans le cas d'une réponse JSON, les guillemets dans la réponse doivent être précédés d'une barre oblique inverse (\
).
La longueur de
<body-content>
ne doit pas dépasser 5 ko (encodage compris).- Si l'en-tête
Dans cet exemple, une demande adressée au chemin
/test
renvoie un code de statut 200 et une charge utile 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 adressée au chemin
/test-redirect
renvoie un code de statut 302, ainsi qu'une URL temporaire dans l'en-têteLocation
de la réponse. Cet exemple montre également que vous pouvez créer une spécification de déploiement d'API avec un seul routage vers un back-end 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" }] } } ] }
-
- Enregistrez le fichier JSON qui contient la spécification de déploiement d'API.
-
Utilisez 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 Télécharger une API existante,
- spécifiant le fichier JSON dans une demande adressée à l'API REST d'API Gateway.
Pour plus d'informations, reportez-vous à 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.
- (Facultatif) Vérifiez que l'API a été déployée en l'appelant (reportez-vous à Appel d'une API déployée sur une passerelle d'API).