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 :
-
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.
-
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.
-
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 :
- Est relatif au préfixe du chemin du déploiement (voir Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API).
- 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. 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
ettext/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
etapplication/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).
- Si vous spécifiez le nom d'en-tête et la valeur d'en-tête comme
-
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 valeurapplication/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éponseLocation
.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
-
- (Facultatif) Sélectionnez Autre route pour entrer les détails des routes supplémentaires.
- Sélectionnez Suivant pour vérifier les détails que vous avez entrés 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 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 :
-
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" } } ] }
-
Dans la section
routes
, incluez une nouvelle sectionpath
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 :- Est relatif au préfixe du chemin du déploiement (voir Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API).
- 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).
<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 exemple200
"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 sectionheaders:
(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
esttext/plain
, le corps de la réponse peut être"body": "Hello world"
. - Si l'en-tête
Content-Type
estapplication/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).- Si l'en-tête
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éponseLocation
. 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" }] } } ] }
-
- Enregistrez le fichier JSON contenant la spécification de déploiement d'API.
-
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.
- (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).