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.

Uso de OCI API Gateway, Functions y Observability para validar el contenido JSON y supervisar las cabeceras y el cuerpo de la API

Introducción

Cuando desarrollamos aplicaciones distribuidas, especialmente en arquitecturas basadas en microservicios, queremos componentes que se escalen y funcionen bien en su ejecución. Tienen arquitecturas muy complejas, componentes que ejecutan otros componentes, que ejecutan otros componentes, etc. en un número infinito de llamadas sin fin.

Planear cómo desarrollar cada uno de ellos es una tarea enorme. Puede exponer los microservicios creados en un cluster de Kubernetes a través de Oracle Cloud Infrastructure API Gateway (OCI API Gateway). Hay una serie de utilidades, como realizar autenticación y autorización de llamadas, validación de datos y optimización de llamadas, por nombrar solo algunas. También existe la posibilidad de ejecutar llamadas con OCI Functions con el objetivo de crear mecanismos de autenticación y autorización personalizados, cuando los métodos existentes no son suficientes para resolver la necesidad.

En este tutorial se mostrará cómo utilizar el mecanismo personalizado para validar algunos casos de uso como:

Valide el tamaño de los datos de parámetros JSON.
Valide el número máximo de elementos JSON.

A pesar de ser un mecanismo de autenticación y autorización en OCI API Gateway, podría ayudar con otras necesidades, como:

Capture datos de HEADER, parámetros de consulta o el cuerpo de la llamada REST.
Envíe estos datos a OCI Observability con el objetivo de facilitar la depuración de problemas, que a menudo son imposibles de detectar sin esta información.

Nota: Si envía datos a Observability, tenga en cuenta en el código, como mejor práctica, el uso de la redacción para contenido HEADER o BODY, como contraseñas o datos confidenciales. Otro enfoque podría ser activar/desactivar la función con fines de depuración.

Objetivos

Configurar un despliegue de API.
Desarrolle una función de OCI para capturar HEADER y BODY a partir de la solicitud de API.
Valide los datos JSON de un cuerpo.
Envíe la información de HEADER y BODY a OCI Observability.

Requisitos

Un inquilino operativo de Oracle Cloud. Para probar este tutorial, puede crear una cuenta de Oracle Cloud gratuita con $ 300.00 durante un mes. Consulte Creación de una cuenta de Oracle Cloud gratuita.
Una instancia de OCI API Gateway creada y expuesta a Internet, consulte Creación de su primer gateway de API en Oracle Cloud.

Tarea 1: Configuración de OCI Observability

Cree un log en su arrendamiento de OCI para ingerir los logs de su función. Vaya a Observación y gestión y seleccione Logs en la consola de OCI.
Haga clic en Crear log personalizado.
Introduzca un nombre en el campo Nombre de log personalizado y seleccione un compartimento y un grupo de logs adecuados.

Nota: Es importante capturar el OCID del log, lo necesitará para el código.

log-4

Tarea 2: Creación de una función de OCI para capturar los HEADER y BODY desde la solicitud de API

Para ejecutar los siguientes pasos, descargue el código desde aquí function.zip.

Capture HEADER y BODY desde la solicitud de API.
Valide los datos JSON del cuerpo; hay un método para validar el número de elementos en cada matriz.

Envíe la información de HEADER y BODY a OCI Observability.

import io
import json
import logging
import requests
import oci

from fdk import response
from datetime import timedelta

def count_items(dictData):
    counting = 0
    for item in dictData:
        if type(dictData[item]) == list:
            counting += len(dictData[item])
        else:
            if not type(dictData[item]) == str:
                counting += count_items(dictData[item])
    return counting

def handler(ctx, data: io.BytesIO = None):
    jsonData = "API Error"
    c = 0
    try:
        config = oci.config.from_file("./config","DEFAULT")
        logging = oci.loggingingestion.LoggingClient(config)
        rdata = json.dumps({
            "active": True,
            "context": {
                "requestheader": data.getvalue().decode('utf-8'),
            },
        })

        jsonData = data.getvalue().decode('utf-8')
        # Get the body content from the API request
        body = dict(json.loads(data.getvalue().decode('utf-8')).get("data"))["body"]
        body = dict(json.loads(body))
        # Count the number of items on arrays inside the JSON body
        c = count_items(body)

        # If JSON body content has more than 1 item in arrays, block the authorization for the API backend
        if (c > 1):
            # Send a log to observability with out of limit of items in array
            put_logs_response = logging.put_logs(
                log_id="ocid1.log.oc1.iad.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                put_logs_details=oci.loggingingestion.models.PutLogsDetails(
                    specversion="EXAMPLE-specversion-Value",
                    log_entry_batches=[
                        oci.loggingingestion.models.LogEntryBatch(
                            entries=[
                                oci.loggingingestion.models.LogEntry(
                                    data="out of limit of items in array " + str(c),
                                    id="ocid1.test.oc1..00000001.EXAMPLE-id-Value")],
                            source="EXAMPLE-source-Value",
                            type="EXAMPLE-type-Value")]))

            return response.Response(
                ctx,
                status_code=401,
                response_data=json.dumps({"active": False, "wwwAuthenticate": "API Gateway JSON"})
            )

        # Send a log to observability with HEADERs and BODY content
        put_logs_response = logging.put_logs(
            log_id="ocid1.log.oc1.iad.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            put_logs_details=oci.loggingingestion.models.PutLogsDetails(
                specversion="EXAMPLE-specversion-Value",
                log_entry_batches=[
                    oci.loggingingestion.models.LogEntryBatch(
                        entries=[
                            oci.loggingingestion.models.LogEntry(
                                data=jsonData,
                                id="ocid1.test.oc1..00000001.EXAMPLE-id-Value")],
                        source="EXAMPLE-source-Value",
                        type="EXAMPLE-type-Value")]))

        return response.Response(
            ctx, response_data=rdata,
            status_code=200,
            headers={"Content-Type": "application/json"}
        )
    except(Exception) as ex:
        jsonData = 'error parsing json payload: ' + str(ex) + ", " + json.dumps(jsonData)
        pass

    return response.Response(
        ctx,
        status_code=401,
        response_data=json.dumps({"active": False, "wwwAuthenticate": jsonData})
    )

Descripción del código

Este código se puede encontrar aquí function.zip.

Nota: si no sabe cómo desarrollar una función y llamarla en API Gateway, consulte Llamada a una función mediante API Gateway.

Método count_items utilizado para contar elementos en cualquier matriz dentro de la estructura JSON.
Esta parte del código utiliza el SDK de OCI para Python para cargar el archivo de configuración y la clave privada para acceder a su arrendamiento de OCI.
rdata capturará los parámetros de la solicitud y preparará la respuesta para autorizar a la función a llamar al backend de la configuración de API Gateway. active = True ejecutará la autorización.
jsonData se utilizará para generar el contenido de HEADER y BODY en OCI Observability.
Este código capturará solo la estructura JSON de CUERPO de la solicitud.
A continuación, el código contará los elementos de las matrices dentro de la estructura JSON de BODY. Si el recuento de artículos supera más de 1 artículo, activo se definirá en Falso y se enviará un log de errores a OCI Observability. Para enviar el log, deberá utilizar el SDK de OCI de Python.

Nota: Sustituya la variable log_id por el log de OCID generado en la Tarea 1.

Si el recuento es menor o igual que 1, se generará un log con el contenido de HEADER y BODY de la solicitud en OCI Observability. Recuerde sustituir la variable log_id por el log de OCID.

Nota: Puede producir logs en un log de OCI diferente. En este tutorial, solo se ha creado un log, pero puede crear más logs.
En caso de error, se generará aquí un mensaje con el error.

Configuración de la autenticación SDK en OCI

Debe configurar el archivo de configuración y colocar la clave privada y la huella de OCI con su función antes de desplegarlo en OCI. Debe tener los archivos config y private key generados en la instalación y configuración de la interfaz de línea de comandos (CLI de OCI) de Oracle Cloud Infrastructure.

Para instalar y configurar la CLI de OCI, consulte Instalación de la CLI de OCI. Esta instalación y configuración generarán dos archivos para usted. Busque el archivo config y private key (el valor predeterminado es oci_api_key.pem). La ruta de la carpeta se informará en las instrucciones de instalación.

código-2

Descargue function.zip para ver el código, el archivo de configuración y la clave privada. Sustituya los archivos de configuración y clave privada por los archivos de la CLI de OCI.

Creación y despliegue de la función OCI

En este paso, necesitaremos utilizar la CLI de OCI para crear las funciones de OCI y desplegar el código en su arrendamiento. Para crear una función de OCI, consulte OCI Functions QuickStart y busque la opción Python. Necesitará crear su función con esta información:

Aplicación: fn_apigw_json

Recuerde el compartimento que ha desplegado la función. Necesitará esta información para configurar el despliegue de OCI API Gateway.

Tarea 3: Configuración de la función OCI en API Gateway

Vamos a desplegar la API e integrarla con OCI Functions para validar y enviar parámetros de solicitud (cabecera y cuerpo) a OCI Observability. Si no sabe cómo exponer el backend en el gateway de API de OCI, consulte Gateway de API de OCI: configuración, creación y despliegue de una API.

Abra Editar despliegue.
Haga clic en la sección Autenticación.
Haga clic en Autenticación única y seleccione Función de autorizador.
Seleccione el compartimento de funciones (donde ha desplegado la función), seleccione la aplicación fn_apigw_json y la función python-json-header.
Configure los argumentos de Functions para capturar HEADER y BODY. Capture el HEADER denominado header y header2, y el contenido BODY que se denominará body.
Haga clic en Rutas y configure la Transformación de cabecera. Esta configuración es opcional, solo para ver el contenido de la respuesta con los datos de la solicitud (contenido de HEADER y BODY) o los errores generados en la solicitud. Será útil depurar la función.

Tarea 4: Prueba de la solicitud

Nota: en el despliegue de API, se activará una caché para los argumentos de Functions si configura la función de responsable de autorización y configura los argumentos de Functions. Puede establecer qué tipo de datos se almacenará en caché. Puede configurar la caché para el parámetro de consulta o la cabecera, pero no para el contenido del cuerpo.

Podemos probar la solicitud de API. Vamos a probar con un solo elemento en una matriz en el cuerpo.

curl --location 'https://xxxxxxxxxxxxxxxxxxxx.apigateway.us-ashburn-1.oci.customer-oci.com/path_index/path' \
    --header 'Content-Type: text/plain' \
    --header 'header: header' \
    --header 'header2: header2' \
    --header 'header3: header3' \
    --data '{"data": {"clientID": "xxxxxxxxxxxxxxxxxxx", "secretID": "xxxxxxxxxxxxxxxxxxx", "jList":[{"added_by":"Ani","description":"example description.","start_date":"2014-10-10","mark":255,"id":975}]}}' -i

Se ha enviado header3, pero se muestra en el log porque no se ha configurado como argumento de función en OCI API Gateway. Solo hay 1 elemento en la matriz BODY JSON, por lo que es una solicitud de autorización válida.

prueba-1

Pongamos un elemento más en la matriz y probemos.

curl --location 'https://xxxxxxxxxxxxxxxxxxxx.apigateway.us-ashburn-1.oci.customer-oci.com/path_index/path' \
--header 'Content-Type: text/plain' \
--header 'header: header' \
--header 'header2: header2' \
--header 'header3: header3' \
--data '{"data": {"clientID": "xxxxxxxxxxxxxxxxxxx", "secretID": "xxxxxxxxxxxxxxxxxxx", "jList":[{"added_by":"Ani","description":"example description.","start_date":"2014-10-10","mark":255,"id":975}, {"added_by":"Ani","description":"example description.","start_date":"2014-10-10","mark":255,"id":975}]}}' -i

prueba-2

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

Use OCI API Gateway, Functions and Observability to Validate JSON Content and Monitor API Headers and Body

F89782-01

November 2023