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.

Utiliser OCI API Gateway, Functions and Observability pour valider le contenu JSON et surveiller les en-têtes et le corps d'API

Introduction

Lorsque nous développons des applications distribuées, en particulier dans des architectures basées sur des microservices, nous voulons des composants qui évoluent et fonctionnent bien dans leur exécution. Ils ont des architectures très complexes, des composants qui exécutent d'autres composants, qui exécutent d'autres composants, etc., dans un nombre infini d'appels.

Planifier comment développer chacun d'eux est une tâche énorme. Vous pouvez exposer vos microservices basés sur un cluster Kubernetes via Oracle Cloud Infrastructure API Gateway (OCI API Gateway). Il existe une série d'installations, telles que l'authentification et l'autorisation des appels, la validation des données et l'optimisation des appels, pour n'en nommer que quelques-unes. Il est également possible d'exécuter des appels avec OCI Functions dans le but de créer des mécanismes d'authentification et d'autorisation personnalisés, lorsque les méthodes existantes ne sont pas suffisantes pour résoudre le besoin.

Ce tutoriel explique comment utiliser le mécanisme personnalisé pour valider certains cas d'utilisation tels que :

Validez la taille des données de paramètre JSON.
Validez le nombre maximal d'éléments JSON.

Bien qu'il s'agisse d'un mécanisme d'authentification et d'autorisation dans OCI API Gateway, il peut répondre à d'autres besoins, tels que les suivants :

Capturez des données à partir de HEADER, des paramètres de requête ou du corps de l'appel REST.
Envoyez ces données à OCI Observability dans le but de faciliter le débogage des problèmes, qui sont souvent impossibles à détecter sans ces informations.

Remarque : si vous envoyez des données à Observability, considérez dans votre code, comme une meilleure pratique, l'utilisation de la protection par occultation pour le contenu HEADER ou BODY, comme les mots de passe ou les données sensibles. Vous pouvez également activer/désactiver votre fonction à des fins de débogage.

Objectifs

Configurez un déploiement d'API.
Développez une fonction OCI pour capturer HEADER et BODY à partir de la demande d'API.
Valider un corps de données JSON.
Envoyez les informations HEADER et BODY à OCI Observability.

Prérequis

Un locataire Oracle Cloud opérationnel. Vous pouvez créer un compte Oracle Cloud gratuit de 300,00 USD pour un mois afin d'essayer ce tutoriel. Reportez-vous à Création d'un compte Oracle Cloud gratuit.
Instance OCI API Gateway créée et exposée à Internet. Reportez-vous à Création de votre première passerelle d'API dans Oracle Cloud.

Tâche 1 : configurer OCI Observability

Créez un journal dans votre location OCI pour inclure les journaux de votre fonction. Accédez à Observation et gestion et sélectionnez Journaux dans la console OCI.
Cliquez sur Créer un journal personnalisé.
Entrez un nom dans le champ Nom du journal personnalisé et choisissez un compartiment et un groupe de journaux appropriés.

Remarque : il est important de capturer l'OCID de votre journal. Vous en aurez besoin pour votre code.

journalisation-4

Tâche 2 : créer une fonction OCI pour capturer les EN-têtes et le corps à partir de la demande d'API

Pour exécuter les étapes suivantes, téléchargez le code à partir d'ici function.zip.

Capturez le HEADER et le corps à partir de la demande d'API.
Validez les données JSON du corps, il existe une méthode pour valider le nombre d'éléments sur chaque tableau.

Envoyez les informations HEADER et BODY à 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})
    )

Comprendre le code

Ce code est disponible ici : function.zip.

Remarque : si vous ne savez pas comment développer une fonction et l'appeler dans API Gateway, reportez-vous à Appel d'une fonction à l'aide d'API Gateway.

Méthode count_items utilisée pour compter les éléments dans n'importe quel tableau de la structure JSON.
Cette partie de code utilise le kit SDK OCI pour Python afin de charger le fichier de configuration et la clé privée pour accéder à votre location OCI.
rdata capture les paramètres de la demande et prépare la réponse pour autoriser la fonction à appeler le back-end de la configuration de passerelle d'API. active = True exécute l'autorisation.
jsonData sera utilisé pour générer les contenus HEADER et BODY vers OCI Observability.
Ce code capture uniquement la structure JSON BODY de la demande.
En dessous du code, les éléments des tableaux de la structure JSON du corps sont comptés. Si le nombre d'éléments dépasse 1 élément, actif est défini sur Faux et un journal d'erreurs est envoyé à OCI Observability. Pour envoyer le journal, vous devez utiliser le kit SDK OCI Python.

Remarque : remplacez la variable log_id par le journal OCID généré dans la tâche 1.

Si le nombre est inférieur ou égal à 1, un journal avec le contenu HEADER et BODY de la demande sera généré dans OCI Observability. N'oubliez pas de remplacer la variable log_id par votre journal OCID.

Remarque : vous pouvez générer des journaux dans un autre journal OCI. Dans ce tutoriel, un seul journal a été créé, mais vous pouvez en créer d'autres.
En cas d'erreur, un message contenant l'erreur est généré ici.

Configuration de l'authentification du kit SDK vers OCI

Vous devez configurer le fichier de configuration et placer votre clé privée OCI et votre empreinte digitale avec votre fonction avant de le déployer vers OCI. Vous devez générer les fichiers config et private key sur l'installation et la configuration de l'interface de ligne de commande (CLI) Oracle Cloud Infrastructure.

Pour installer et configurer l'interface de ligne de commande OCI, reportez-vous à Installation de l'interface de ligne de commande OCI. Cette installation et cette configuration généreront deux fichiers pour vous. Recherchez le fichier config et private key (la valeur par défaut est oci_api_key.pem). Le chemin du dossier sera indiqué dans les instructions d'installation.

code-2

Téléchargez function.zip pour voir le code, le fichier de configuration et la clé privée. Remplacez les fichiers de configuration et de clé privée par vos fichiers d'interface de ligne de commande OCI.

Créer et déployer la fonction OCI

Cette étape consiste à utiliser l'interface de ligne de commande OCI pour créer les fonctions OCI et déployer du code dans votre location. Pour créer une fonction OCI, reportez-vous à OCI Functions QuickStart et recherchez l'option Python. Vous devrez créer votre fonction avec ces informations :

Application : fn_apigw_json

N'oubliez pas le compartiment dans lequel vous avez déployé la fonction. Vous aurez besoin de ces informations pour configurer votre déploiement OCI API Gateway.

Tâche 3 : configurer la fonction OCI dans API Gateway

Déployons votre API et intégrons-la à vos fonctions OCI pour valider et envoyer les paramètres de demande (en-tête et corps) à OCI Observability. Si vous ne savez pas comment exposer votre back-end dans OCI API Gateway, reportez-vous à OCI API Gateway : configuration, création et déploiement d'une API.

Ouvrez Modifier le déploiement.
Cliquez sur la section Authentification.
Cliquez sur Authentification unique et sélectionnez Fonction d'autorisation.
Choisissez votre compartiment de fonctions (où vous avez déployé la fonction), sélectionnez l'application fn_apigw_json et la fonction python-json-header.
Configurez les arguments Functions pour capturer HEADER et BODY. Capturez le HEADER nommé header et header2, ainsi que le contenu BODY qui sera nommé body.
Cliquez sur Routages et configurez la transformation d'en-tête. Cette configuration est facultative, uniquement pour afficher le contenu de la réponse avec les données de la demande (contenu HEADER et BODY) ou les erreurs générées sur la demande. Il sera utile de déboguer votre fonction.

Tâche 4 : tester votre demande

Remarque : dans votre déploiement d'API, un cache pour les arguments Functions sera activé si vous configurez la fonction d'autorisation et les arguments Functions. Vous pouvez déterminer le type de données qui sera mis en mémoire cache. Vous pouvez configurer le cache pour le paramètre de requête ou l'en-tête, mais pas pour le contenu du corps.

Nous pouvons tester la demande d'API. Testons avec un seul élément sur un tableau dans le corps.

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

header3 a été envoyé mais affiché dans le journal car il n'a pas été configuré en tant qu'argument de fonction dans OCI API Gateway. Il n'y a qu'1 élément dans le tableau BODY JSON. Il s'agit donc d'une demande d'autorisation valide.

test-1

Mettons un élément de plus sur le tableau et testons-le.

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

test-2

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

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

F89782-01

November 2023