Note:

Este tutorial requiere acceso a Oracle Cloud. Para registrarse en una cuenta gratuita, consulte Introducción a la cuenta gratuita de Oracle Cloud Infrastructure.
Utiliza valores de ejemplo para credenciales, arrendamiento y compartimentos de Oracle Cloud Infrastructure. Al finalizar el laboratorio, sustituya estos valores por otros específicos del entorno en la nube.

Migración de API a Oracle Cloud Infrastructure API Gateway con Oracle Integration

Introducción

El servicio Oracle Cloud Infrastructure API Gateway (OCI API Gateway) permite publicar API con puntos finales privados accesibles en la red y que se pueden exponer con direcciones IP públicas si desea que acepten tráfico de Internet. Los puntos finales admiten la validación de API, la transformación de solicitud y respuesta, CORS, la autenticación y autorización, y la limitación de solicitudes.

Con el servicio de gateway de API de OCI, crea uno o varios gateways de API en una subred regional para procesar el tráfico de cliente de API y direccionarlo a servicios de backend. Puede utilizar una única puerta de enlace de API para enlazar varios servicios de backend (como equilibradores de carga, instancias informáticas y Oracle Cloud Infrastructure Functions) en un único punto final de API consolidado.

Puede acceder al servicio OCI API Gateway para definir gateways y despliegues de API mediante la consola de OCI y la API de REST.

El servicio OCI API Gateway está integrado con Oracle Cloud Infrastructure Identity and Access Management (OCI IAM), que proporciona una autenticación sencilla con la funcionalidad de identidad nativa de Oracle Cloud Infrastructure (OCI).

OCI API Gateway permite realizar el despliegue de API importando una estructura JSON. Aquí puede ver el formato de esta estructura Creación de una especificación de despliegue de API.

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

Además de la consola, es posible desplegar la API mediante la interfaz de línea de comandos (CLI de OCI) de Oracle Cloud Infrastructure y también el servicio REST de OCI para OCI API Gateway. A continuación se muestra la documentación para comprender cómo desplegar:

Si ya tiene la estructura de API que desplegar en el formato estándar de OCI API Gateway, es fácil desplegarla mediante la consola (importación), la CLI de OCI o realizando una llamada REST. Al tener esta estructura lista, es fácil crear código para procesar varios archivos JSON. En este ejemplo, se muestra cómo procesar archivos mediante el código 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

En algunas situaciones, será necesario manejar la información de metadatos de API. Podríamos hacerlo mediante código con Python, Java u otro lenguaje, pero el objetivo de este tutorial es utilizar Oracle Integration para automatizarlo. Hay varias ventajas de hacerlo de esta manera. Puede:

Ejecute llamadas REST desde OCI API Gateway para desplegar sus API.
Asigne atributos del origen al destino, incluida la realización de las transformaciones adecuadas.
Implante el flujo para procesar todos los valores de forma gráfica.

Objetivos

Explicar cómo importar la especificación de API heredadas al gateway de API de OCI.
Explicar los formatos conocidos y el formato que OCI API Gateway puede importar de forma nativa.
Cree un proceso de Oracle Integration para migrar una definición de despliegue de API de origen al gateway de API de OCI.
Proceso de varias definiciones de origen.
Diferenciar definiciones de REST y SOAP.
Asigne los atributos de origen al gateway de API de OCI de destino.
Realice el despliegue en el entorno correcto (QA, DEV).

Requisitos

Una instancia de Oracle Integration.
Dos instancias de OCI API Gateway (en este tutorial, hemos creado una para QA y otra para entornos DEV).
La instancia de Oracle Integration debe acceder a las instancias de OCI API Gateway (atención a las redes privadas).

Tarea 1: Descripción de la estructura de datos de la API de origen

Podemos comenzar desde una estructura de metadatos de API. Las definiciones más conocidas serían OpenAPI o Swagger.

Si tiene un SWAGGER o un OpenAPI, puede importar los datos de API a OCI API Gateway importándolos en la consola de OCI, la CLI de OCI o el servicio REST de OCI API Gateway, consulte Creación de un recurso de API con una descripción de API.

Si no tiene estos formatos (Swagger/OpenAPI), debe estructurar las definiciones de datos de API en otro formato. En esta tarea, trabajaremos con una estructura de Excel y, a partir de esta estructura, la transformaremos en JSON.

Por lo tanto, hay una estructura JSON con la que trabajar.

[ {
  "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" : ""
} ]

Estas estructuras de datos de API se pueden encontrar aquí: source_apis.json. Puede estructurar los datos de definiciones de API en cualquier formato. Esto es solo un ejemplo.

Tarea 2: Descripción de los datos de despliegue de OCI API Gateway

En esta tarea, puede ver el formato nativo para importar las definiciones de API a OCI API Gateway. A menudo, una estructura simple es suficiente para implantar una API, pero a medida que aparecen detalles como seguridad, reglas de cabecera, parámetros u otros detalles, la estructura JSON se hace más grande. Esta sería la estructura JSON completa para cualquier tipo de despliegue. Lo utilizaremos en nuestro flujo de Oracle Integration. Puede encontrar el archivo aquí: 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"
              }
            ]
          }
        }
      }
    }
  ]
}

Tarea 3: Creación de conexiones

Hay 2 conexiones que necesitamos crear. La primera conexión es la conexión REST del disparador. Esta conexión se utilizará para mostrar un punto final en Oracle Integration. Con este punto final, puede llamar al proceso de migración como servicio REST y transferir los datos de origen de sus API.

La segunda conexión se utilizará para llamar al servicio REST de gateway de API de OCI para crear los despliegues de API. La documentación de REST de OCI API Gateway se puede leer aquí: Despliegue de API a través de REST.

Crear una conexión de Oracle Integration. Consulte la documentación sobre la creación de una conexión REST.

Busque el adaptador de REST.
Proporcione un nombre e identificador, por ejemplo, indique el nombre "REST_EXPOSE". Esta es la primera conexión. Seleccione el rol de disparador. El rol de disparador significa que expondrá la conexión como punto final de REST y haga clic en Crear.
Para el punto final del disparador, puede ejecutar una solicitud con la autenticación básica de Oracle Integration. Por lo tanto, puede utilizar un nombre de usuario y una contraseña.
En la segunda conexión, como lo hizo en la primera conexión, proporcione un nombre e identificador (por ejemplo, "APIGW_REST_API"). Recuerde seleccionar el tipo de llamada a diferencia de la primera configuración. Seleccione el REST de gateway de API de OCI adecuado para su región (en el ejemplo, la región es Ashburn). Consulte aquí para ver el punto final adecuado para los puntos finales de OCI API Gateway de su región. Obtenga sus credenciales de OCI para proporcionar acceso al servicio OCI API Gateway.

Tarea 4: Creación de la integración

El proceso de migración de los metadatos de origen de API al gateway de API de OCI es:

Exponga el disparador como un servicio REST en Oracle Integration.
Inicialice los gateways de API de OCI de destino (entornos como QA y DEV).
Inicialice los compartimentos para los destinos.
Ejecute un bucle para procesar todas las API de los metadatos de origen.
Traducir los metadatos de origen a los metadatos de OCI API Gateway.
Ejecute un servicio REST de solicitud en OCI API Gateway.

Exponga la integración con la conexión REST de disparador creada anteriormente.
Proporcione un nombre al punto final de la solicitud.
Proporcione una ruta (por ejemplo, /convert) y seleccione el método POST. Recuerde establecer una carga útil de solicitud.
Ahora puede seleccionar el ejemplo de JSON y pegar la estructura de origen de JSON.
Pegar JSON aquí.
Ahora inicializemos las variables para las instancias de API Gateway (cada entorno es una nueva instancia de API Gateway). Cree una variable para el método. Recuerde que puede utilizar varios métodos en REST (GET, POST, PUT, DELETE, ANY) y necesita utilizar POST en los servicios SOAP.
Cree un bucle FOR EACH. Se procesará la lista JSON de origen.
Edite For Each Action y arrastre y suelte la matriz de nivel de bucle en el atributo Elemento de repetición.
Ahora vamos a configurar la redirección del entorno. Cree una acción de cambio y coloque las IF y las asignaciones para cada condición.
Cree la primera condición para el entorno de QA.
Verifique en el atributo ENVIRONMENT de los metadatos de origen y pruebe si tiene el valor "QA".
Si la condición es verdadera, debe asignar el entorno correcto. Un valor GatewayID y CompartmentID es un valor de OCID. Debe asignar los ID correctos a las variables.
Haga lo mismo para los otros entornos.
Ahora veamos si su API es un servicio REST o SOAP. Si la API es un servicio SOAP, debe configurar el método como POST.
Cree una condición IF para probar el tipo de servicio.
Asigne el valor POST a la variable de método.
En otras situaciones, el atributo de origen proporciona el método correcto.
Asignemos los atributos de metadatos de origen a los parámetros de OCI API Gateway. Antes de la acción de asignación, debe configurar el adaptador de REST de gateway de API de OCI.
Configure la conexión.
Proporcione un nombre para este servicio. La ruta debe ser /deployments y el método debe ser POST. Recuerde configurar la carga útil de la solicitud.
No puede pegar la estructura de JSON OCI API Gateway debido al gran tamaño. Por lo tanto, debe cargar un archivo con el contenido. La estructura JSON completa está aquí apigw_structure.json.
Asigne los metadatos de destino.

Nota: puede ver el artefacto de Oracle Integration aquí: Oracle Integration: migración de la API de origen a OCI API Gateway. Este ejemplo de artefacto no está destinado a utilizarse como proceso final para la migración y solo tiene el objetivo de ilustrar el proceso. Utilice este artefacto para guiar su implantación real.

Tarea 5: Prueba de la migración

Para obtener más información, consulte los siguientes enlaces y siga los pasos a continuación.

Agregue los datos JSON de origen.
Haga clic en Probar y espere hasta que finalice.
Vaya a los despliegues de instancias de OCI API Gateway y vea la creación de sus API.

Agradecimientos

Autor: Cristiano Hoshikawa (ingeniero de soluciones de equipo A de Oracle LAD)

Más recursos de aprendizaje

Explore otros laboratorios en docs.oracle.com/learn o acceda a más contenido de aprendizaje gratuito en el canal YouTube de Oracle Learning. Además, visite education.oracle.com/learning-explorer para convertirse en Oracle Learning Explorer.

Para obtener documentación sobre el producto, visite Oracle Help Center.

Título e Información de Copyright

Migrate APIs to Oracle Cloud Infrastructure API Gateway with Oracle Integration

F88509-01

October 2023