Création d'une spécification de déploiement d'API
Découvrez comment créer une spécification d'API (une définition lisible par la machine d'une API au format JSON) à utiliser avec API Gateway.
Pour pouvoir déployer une API sur une passerelle d'API, vous devez créer une spécification de déploiement d'API. Chaque déploiement d'API comporte une spécification de déploiement d'API.
Chaque spécification de déploiement d'API décrit un ensemble de ressources ainsi que les méthodes (par exemple, GET, PUT) qui peuvent être exécutées sur chaque ressource.
Vous pouvez utiliser une seule passerelle d'API comme composant frontal pour plusieurs services back-end en :
- créant un seul déploiement d'API sur la passerelle d'API, avec une spécification de déploiement d'API qui définit plusieurs services back-end,
- créant plusieurs déploiements d'API sur la même passerelle d'API, chacun comportant une spécification de déploiement d'API qui définit des services back-end.
En règle générale, les services back-end sont situés dans le même réseau cloud virtuel que la passerelle d'API sur laquelle vous déployez une API. Ce n'est toutefois pas obligatoire. Dans la spécification de déploiement d'API, vous pouvez décrire des services back-end qui se trouvent sur un sous-réseau public ou privé de votre location, ainsi que des services situés en dehors de votre location (y compris sur le réseau Internet public). Quel que soit leur emplacement, les services back-end doivent pouvoir être acheminés à partir du sous-réseau contenant la passerelle d'API sur laquelle l'API est déployée. Par exemple, si le service back-end se trouve sur le réseau Internet public, le réseau cloud virtuel doit disposer d'une passerelle Internet pour permettre à la passerelle d'API d'acheminer les demandes vers le service back-end.
Vous pouvez créer une spécification de déploiement d'API en :
- utilisant les boîtes de dialogue de la console lors de la création d'un déploiement d'API,
- utilisant l'éditeur JSON de votre choix pour créer un fichier JSON distinct. Vous pouvez ensuite indiquer ce fichier JSON lorsque vous utilisez la console, l'interface de ligne de commande ou l'API pour créer un déploiement d'API.
- utilisant un fichier de description d'API que vous téléchargez vers le serveur pour une ressource d'API. Le fichier de description d'API fournit certaines valeurs initiales pour la spécification de déploiement d'API, que vous pouvez modifier et étendre lors du déploiement de la ressource d'API sur une passerelle d'API. Reportez-vous à Création d'une ressource d'API avec une description d'API.
Les instructions contenues dans cette rubrique présentent une spécification de déploiement d'API de base avec un back-end unique, un seul routage et aucune stratégie de demande ou de réponse. Reportez-vous à Exemple de spécification de déploiement d'API avec plusieurs back-ends pour découvrir une spécification de déploiement d'API plus standard qui inclut plusieurs back-ends, chacun comportant des routages.
En outre, vous pouvez ajouter des stratégies de demande et de réponse qui s'appliquent aux routages d'une spécification de déploiement d'API (reportez-vous à Ajout de stratégies de demande et de réponse aux spécifications de déploiement d'API).
Utilisation de la console pour créer une spécification de déploiement d'API
Pour créer une spécification de déploiement d'API lors de la création d'un déploiement d'API à l'aide des boîtes de dialogue de la console, reportez-vous à Utilisation de la console pour créer un déploiement d'API entièrement nouveau.
Utilisation d'un éditeur JSON pour créer une spécification de déploiement d'API dans un fichier JSON distinct
Pour créer 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, créez la spécification de déploiement d'API dans un fichier JSON au format suivant :
{ "requestPolicies": {}, "routes": [ { "path": "<api-route-path>", "methods": ["<method-list>"], "backend": { "type": "<backend-type>", "<backend-target>": "<identifier>" }, "requestPolicies": {} } ] }
où :
"requestPolicies"
indique des stratégies facultatives permettant de contrôler le comportement d'un déploiement d'API. Pour appliquer des stratégies à tous les routages dans une spécification de déploiement d'API, placez les stratégies en dehors de la sectionroutes
. Pour appliquer les stratégies uniquement à un routage spécifique, placez les stratégies dans la sectionroutes
. Reportez-vous à Ajout de stratégies de demande et de réponse aux spécifications de déploiement d'API.-
<api-route-path>
spécifie un 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).
<method-list>
indique les méthodes acceptées par le service back-end, séparées par des virgules. Par exemple,"GET, PUT"
.<backend-type>
indique le type de service back-end. Valeurs valides :ORACLE_FUNCTIONS_BACKEND
,HTTP_BACKEND
etSTOCK_RESPONSE_BACKEND
.<backend-target>
et<identifier>
spécifient le service back-end. Les valeurs valides pour<backend-target>
et<identifier>
dépendent de la valeur de<backend-type>
, comme suit :- Si vous définissez
<backend-type>
surORACLE_FUNCTIONS_BACKEND
, remplacez<backend-target>
parfunctionId
et<identifier>
par l'OCID de la fonction. Par exemple,"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab5b..."
. Reportez-vous à Ajout d'une fonction dans OCI Functions en tant que back-end de passerelle d'API. - Si vous définissez
<backend-type>
surHTTP_BACKEND
, remplacez<backend-target>
parurl
et<identifier>
par l'URL du service back-end. Par exemple,"url": "https://api.weather.gov"
. Reportez-vous à Ajout d'une URL HTTP ou HTTPS en tant que back-end de passerelle d'API. - Si vous définissez
<backend-type>
surSTOCK_RESPONSE_BACKEND
, remplacez<backend-target>
et<identifier>
par les paires clé-valeur appropriées. Reportez-vous à Ajout de réponses par défaut en tant que back-end de passerelle d'API.
- Si vous définissez
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" } } ] }
Pour obtenir un exemple plus complexe qui définit plusieurs back-ends, reportez-vous à Exemple de spécification de déploiement d'API avec plusieurs back-ends.
- 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.
Utilisation d'un fichier de description d'API pour créer une spécification de déploiement d'API
Afin de créer une spécification de déploiement d'API basée sur un fichier de description d'API téléchargé vers le serveur pour une ressource d'API, reportez-vous à Création d'une ressource d'API avec une description d'API.
Le fichier de description d'API fournit certaines valeurs initiales pour la spécification de déploiement d'API, que vous pouvez modifier et étendre lors du déploiement de la ressource d'API sur une passerelle d'API.
Exemple de spécification de déploiement d'API avec plusieurs back-ends
Vous pouvez créer un déploiement d'API unique sur une passerelle d'API, avec une spécification de déploiement d'API qui définit plusieurs services back-end.
Par exemple, la spécification de déploiement d'API suivante définit une fonction simple sans serveur Hello World dans OCI Functions comme un seul back-end, et l'API National Weather Service comme un second back-end.
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
},
{
"path": "/weather",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov"
}
}
]
}