Remarques :

Ce tutoriel nécessite un accès à Oracle Cloud. Pour vous inscrire à un compte gratuit, reportez-vous à Introduction au niveau gratuit d'Oracle Cloud Infrastructure.
Il utilise des exemples de valeur pour les informations d'identification, la location et les compartiments Oracle Cloud Infrastructure. A la fin de l'exercice, remplacez ces valeurs par des valeurs propres à votre environnement cloud.

Migration d'API vers Oracle Cloud Infrastructure API Gateway avec Oracle Integration

Introduction

Le service Oracle Cloud Infrastructure API Gateway (OCI API Gateway) vous permet de publier des API avec des adresses privées accessibles sur votre réseau. Vous pouvez les exposer avec des adresses IP publiques si vous voulez qu'elles acceptent le trafic Internet. Les adresses prennent en charge la validation d'API, la transformation des demandes et des réponses, l'authentification et l'autorisation CORS, ainsi que la limitation des demandes.

A l'aide du service OCI API Gateway, vous pouvez créer des passerelles d'API sur un sous-réseau régional pour traiter le trafic client d'API et l'acheminer vers des services back-end. Vous pouvez utiliser une seule passerelle d'API pour lier plusieurs services back-end (tels que des équilibreurs de charge, des instances de calcul et Oracle Cloud Infrastructure Functions) à une seule adresse d'API consolidée.

Vous pouvez accéder au service OCI API Gateway pour définir des passerelles d'API et des déploiements d'API à l'aide de la console OCI et de l'API REST.

Le service OCI API Gateway est intégré à Oracle Cloud Infrastructure Identity and Access Management (OCI IAM), qui facilite l'authentification à l'aide de la fonctionnalité d'identité Oracle Cloud Infrastructure (OCI) native.

OCI API Gateway permet d'effectuer le déploiement d'API en important une structure JSON. Ici, vous pouvez voir le format de cette structure Création d'une spécification de déploiement d'API.

{
  "requestPolicies": {},
  "routes": [
    {
      "path": "<api-route-path>",
      "methods": ["<method-list>"],
      "backend": {
        "type": "<backend-type>",
        "<backend-target>": "<identifier>"
      },
      "requestPolicies": {}
    }
  ]
}

Outre la console, il est possible de déployer l'API à l'aide de l'interface de ligne de commande Oracle Cloud Infrastructure (interface de ligne de commande OCI) et du service REST OCI pour OCI API Gateway. Voici la documentation pour comprendre comment déployer :

Si votre structure d'API doit déjà être déployée au format OCI API Gateway standard, il est facile de la déployer à l'aide de la console (import), de l'interface de ligne de commande OCI ou en effectuant un appel REST. Grâce à cette structure, il est facile de créer du code pour traiter plusieurs fichiers JSON. L'exemple ci-dessous montre comment traiter des fichiers à l'aide du code de script bash :

#!/bin/bash
# Folder containing JSON files
folder="/<your path to the JSON Files>"
# Loop through the JSON files in the folder
for file in "$folder"/*.json; do
    service="${file##*/}"; service="${service%.*}"
    echo "Service: $service"        # Read and display the contents of the JSON file
    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxx --display-name $service --gateway-id ocid1.apigateway.oc1.iad.xxxxxxxxxxxxxxxxxxxxxxxxxxxx --path-prefix "/$service" --specification file://$file --debug
    echo "-------------------"
done

Dans certains cas, les informations de métadonnées d'API devront être gérées. Pour ce faire, nous pourrions utiliser du code en Python, Java ou un autre langage, mais le but de ce tutoriel est d'utiliser Oracle Integration pour l'automatiser. Il y a plusieurs avantages à le faire de cette façon. Vous pouvez facilement :

Exécutez des appels REST à partir d'OCI API Gateway pour déployer vos API.
Mapper des attributs de la source vers la destination, y compris effectuer les transformations appropriées.
Implémentez le flux pour traiter tous les paramètres sous forme graphique.

Objectifs

Expliquez comment importer la spécification d'API héritées vers OCI API Gateway.
Expliquez les formats connus et le format qu'OCI API Gateway peut importer en natif.
Créez un processus Oracle Integration pour migrer une définition de déploiement d'API source vers OCI API Gateway.
Traiter plusieurs définitions de source.
Différencier les définitions REST et SOAP.
Mettez en correspondance les attributs source avec la passerelle d'API OCI cible.
Déployer dans l'environnement approprié (QA, DEV).

Prérequis

Une instance Oracle Integration.
Deux instances OCI API Gateway (dans ce tutoriel, nous en avons créé une pour l'assurance qualité et une autre pour les environnements DEV).
L'instance Oracle Integration doit atteindre les instances OCI API Gateway (attention aux réseaux privés).

Tâche 1 : comprendre la structure de données de l'API source

Nous pouvons partir d'une structure de métadonnées d'API. Les définitions les plus connues sont OpenAPI ou Swagger.

Si vous disposez d'un SWAGGER ou d'un OpenAPI, vous pouvez importer vos données d'API vers OCI API Gateway en les important dans la console OCI, l'interface de ligne de commande OCI ou le service REST OCI API Gateway. Reportez-vous à Création d'une ressource d'API avec une description d'API.

Si vous ne disposez pas de ces formats (Swagger/OpenAPI), vous devez structurer vos définitions de données d'API dans un autre format. Dans cette tâche, nous allons travailler avec une structure Excel et, à partir de cette structure, la transformer en JSON.

Il existe donc une structure JSON avec laquelle travailler.

[ {
  "API_NAME" : "cep",
  "TYPE" : "REST",
  "METHOD" : "GET",
  "PATH_PREFIX" : "/okecep",
  "PATH" : "/cep",
  "ENDPOINT" : "http://x.x.x.x/cep",
  "QUERY_PARAMETERS" : "cep",
  "GROOVY_SCRIPT" : "",
  "AUTHENTICATION_TYPE" : "BASIC",
  "ENVIRONMENT" : "QA",
  "HEADER" : "",
  "HEADER_VALUE" : ""
}, {
  "API_NAME" : "calculator",
  "TYPE" : "SOAP",
  "METHOD" : "POST",
  "PATH_PREFIX" : "/dneonline",
  "PATH" : "/calculator",
  "ENDPOINT" : "http://www.example.com/calculator.asmx",
  "QUERY_PARAMETERS" : "",
  "GROOVY_SCRIPT" : "",
  "AUTHENTICATION_TYPE" : "BASIC",
  "ENVIRONMENT" : "DEV",
  "HEADER" : "",
  "HEADER_VALUE" : ""
} ]

Ces structures de données d'API sont disponibles ici : source_apis.json. Vous pouvez structurer vos données de définitions d'API dans n'importe quel format, ceci n'est qu'un exemple.

Tâche 2 : comprendre les données de déploiement d'OCI API Gateway

Dans cette tâche, vous pouvez voir le format natif permettant d'importer vos définitions d'API dans OCI API Gateway. Souvent, une structure simple suffit pour implémenter une API, mais à mesure que des détails tels que la sécurité, les règles d'en-tête, les paramètres ou d'autres détails apparaissent, la structure JSON devient plus grande. Il s'agit de la structure JSON complète pour tout type de déploiement. Nous l'utiliserons dans notre flux Oracle Integration. Le fichier est disponible ici : apigw_structure.json.

{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      "tokenHeader": "",
      "tokenQueryParam": "",
      "tokenAuthScheme": "authentication-scheme",
      "isAnonymousAccessAllowed": false,
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "maxClockSkewInSeconds": 0,
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "client-id",
          "clientSecretId": "secret-ocid",
          "clientSecretVersionNumber": 0
        },
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "well-known-uri"
        },
        "isSslVerifyDisabled": true,
        "maxCacheDurationInHours": 0,
        "additionalValidationPolicy": {
          "issuers": ["issuer-url", "issuer-url"],
          "audiences": ["intended-audience"],
          "verifyClaims": [{
            "key": "claim-name",
            "values": ["acceptable-value", "acceptable-value"],
            "isRequired": true
          }]
        }
      },
      "tokenHeader": "Authorization",
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1",
          "clientSecretId": "ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q",
          "clientSecretVersionNumber": 1
        },
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "https://my-idp/oauth2/default/.well-known/openid-configuration"
        },
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    },
    "mutualTls":{
      "isVerifiedCertificateRequired": true,
      "allowedSans": ["api.weather.com"]
    }
  },
  "routes": [
    {
      "path": "/weather",
      "methods": ["GET"],
      "backend": {
        "type": "HTTP_BACKEND",
        "url": "https://api.weather.gov/${request.auth[region]}"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [ "weatherwatcher" ]
        },
        "headerValidations": {
          "headers": {
            "name": "header-name",
            "required": true
          },
          "validationMode": "ENFORCING|PERMISSIVE|DISABLED"
        },
        "queryParameterValidations": {
          "parameters": {
            "name": "query-parameter-name",
            "required": true
          },
          "validationMode": "ENFORCING|PERMISSIVE|DISABLED"
        },
        "bodyValidation": {
          "required": true,
          "content": {
            "media-type-1": {
              "validationType": "NONE"
            },
            "media-type-2": {
              "validationType": "NONE"
            }
          },
          "validationMode": "ENFORCING|PERMISSIVE|DISABLED"
        },
        "headerTransformations": {
          "renameHeaders": {
            "items": [
              {
                "from": "original-name",
                "to": "new-name"
              }
            ]
          },
          "setHeaders": {
            "items": [
              {
                "name": "header-name",
                "values": ["header-value"],
                "ifExists": "OVERWRITE|APPEND|SKIP"
              }
            ]
          }
        },
        "queryParameterTransformations": {
          "filterQueryParameters": {
            "type": "BLOCK|ALLOW",
            "items": [
              {
                "name": "query-parameter-name"
              }
            ]
          },
          "renameQueryParameters": {
            "items": [
              {
                "from": "original-name",
                "to": "new-name"
              }
            ]
          },
          "setQueryParameters": {
            "items": [
              {
                "name": "query-parameter-name",
                "values": ["query-parameter-value"],
                "ifExists": "OVERWRITE|APPEND|SKIP"
              }
            ]
          }
        }
      },
      "responsePolicies": {
        "headerTransformations": {
          "filterHeaders": {
            "type": "BLOCK|ALLOW",
            "items": [
              {
                "name": "header-name"
              }
            ]
          },
          "renameHeaders": {
            "items": [
              {
                "from": "original-name",
                "to": "new-name"
              }
            ]
          },
          "setHeaders": {
            "items": [
              {
                "name": "header-name",
                "values": ["header-value"],
                "ifExists": "OVERWRITE|APPEND|SKIP"
              }
            ]
          }
        }
      }
    }
  ]
}

Tâche 3 : créer des connexions

Il y a 2 connexions que nous devons créer. La première connexion est le déclencheur de connexion REST. Cette connexion sera utilisée pour exposer une adresse dans Oracle Integration. Avec cette adresse, vous pouvez appeler le processus de migration en tant que service REST, en transmettant les données source de vos API.

La deuxième connexion sera utilisée pour appeler le service REST OCI API Gateway afin de créer vos déploiements d'API. La documentation REST OCI API Gateway est disponible ici : Déploiement d'API via REST.

Créez une connexion Oracle Integration. Reportez-vous à Création d'une connexion REST.

Recherchez l'adaptateur REST.
Indiquez un nom et un identificateur, par exemple, le nom "REST_EXPOSE". C'est la première connexion. Sélectionnez le rôle de déclencheur. Le rôle de déclencheur signifie que vous exposerez la connexion en tant qu'adresse REST, puis cliquez sur Créer.
Pour l'adresse de déclencheur, vous pouvez exécuter une demande avec l'authentification de base Oracle Integration. Vous pouvez donc utiliser un nom d'utilisateur et un mot de passe.
Dans la deuxième connexion, comme dans la première, donnez un nom et un identificateur (par exemple, "APIGW_REST_API"). N'oubliez pas de sélectionner le type Invoke contrairement à la première configuration. Sélectionnez le service REST OCI API Gateway approprié pour votre région (dans l'exemple, la région est Ashburn). Reportez-vous à cette section pour visualiser l'adresse appropriée pour les adresses OCI API Gateway de votre région. Obtenez vos informations d'identification OCI pour fournir l'accès au service OCI API Gateway.

Tâche 4 : créer l'intégration

Le processus de migration des métadonnées de source d'API vers OCI API Gateway est le suivant :

Exposez le déclencheur en tant que service REST dans Oracle Integration.
Initialisez les passerelles d'API OCI cible (environnements tels que QA et DEV).
Initialisez les compartiments des cibles.
Exécutez une boucle pour traiter toutes les API dans les métadonnées source.
Convertissez les métadonnées source en métadonnées OCI API Gateway.
Exécutez un service REST de demande sur OCI API Gateway.

Exposez votre intégration à la connexion REST de déclencheur créée précédemment.
Attribuez un nom à l'adresse de demande.
Indiquez un chemin (par exemple, /convert) et sélectionnez la méthode POST. N'oubliez pas d'établir une charge utile de demande.
Vous pouvez maintenant sélectionner l'échantillon JSON et coller votre structure source JSON.
Collez le JSON ici.
Initialisons maintenant les variables pour vos instances API Gateway (chaque environnement est une nouvelle instance API Gateway). Créez une variable pour la méthode. N'oubliez pas que vous pouvez utiliser plusieurs méthodes dans REST (GET, POST, PUT, DELETE, ANY) et que vous devez utiliser POST dans les services SOAP.
Créez une boucle FOR EACH. La liste JSON source sera traitée.
Modifiez l'action For Each et faites glisser votre tableau de niveau de boucle vers l'attribut Elément répété.
Configurez maintenant la redirection d'environnement. Créez une action Switch et placez les IF et les affectations pour chaque condition.
Créez la première condition pour l'environnement d'assurance qualité.
Vérifiez dans l'attribut ENVIRONMENT des métadonnées source et testez s'il a la valeur "QA".
Si la condition est vraie, vous devez affecter l'environnement approprié. GatewayID et CompartmentID sont des valeurs d'OCID. Vous devez affecter les ID corrects aux variables.
Faites de même pour les autres environnements.
Voyons maintenant si votre API est un service REST ou SOAP. Si votre API est un service SOAP, vous devez configurer la méthode comme POST.
Créez une condition IF pour tester le type de service.
Affectez la valeur POST à la variable de méthode.
Dans d'autres situations, l'attribut source fournit la méthode correcte.
Mappons les attributs de métadonnées source avec les paramètres OCI API Gateway. Avant l'action de mise en correspondance, vous devez configurer l'adaptateur REST OCI API Gateway.
Configurez la connexion.
Indiquez le nom de ce service. Le chemin doit être /deployments et la méthode doit être POST. N'oubliez pas de configurer la charge utile de demande.
Vous ne pouvez pas coller la structure de la passerelle d'API OCI JSON en raison de sa grande taille. Vous devez donc télécharger un fichier avec le contenu. La structure JSON complète est disponible ici : apigw_structure.json.
Mettez en correspondance les métadonnées cible.

Remarque : vous pouvez voir l'artefact Oracle Integration ici : Oracle Integration : migration de l'API source vers OCI API Gateway. Cet exemple d'artefact n'est pas destiné à être utilisé comme processus final pour votre migration et a uniquement pour objectif d'illustrer le processus. Utilisez cet artefact pour guider votre véritable implémentation.

Tâche 5 : tester la migration

Pour plus d'informations, cliquez sur les liens ci-dessous.

Ajoutez les données JSON source.
Cliquez sur Tester et attendez la fin.
Accédez aux déploiements d'instance OCI API Gateway et consultez la création de vos API.

Remerciements

Auteur - Cristiano Hoshikawa (ingénieur solutions Oracle LAD A-Team)

Ressources de formation supplémentaires

Parcourez d'autres ateliers sur docs.oracle.com/learn ou accédez à davantage de contenus de formation gratuits sur le canal Oracle Learning YouTube. De plus, rendez-vous sur education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

Pour obtenir de la documentation sur le produit, visitez Oracle Help Center.

Informations relatives au titre et au copyright

Migrate APIs to Oracle Cloud Infrastructure API Gateway with Oracle Integration

F88509-01

October 2023