Hinweis:

Dieses Tutorial erfordert Zugriff auf Oracle Cloud. Informationen zum Registrieren eines kostenlosen Accounts finden Sie unter Erste Schritte mit Oracle Cloud Infrastructure Free Tier.
Es verwendet Beispielwerte für Oracle Cloud Infrastructure-Zugangsdaten, -Mandanten und -Compartments. Wenn Sie Ihre Übung abgeschlossen haben, ersetzen Sie diese Werte durch spezifische Werte für Ihre Cloud-Umgebung.

Mit OCI API Gateway, Funktionen und Beobachtbarkeit JSON-Inhalt validieren und API-Header und -Body überwachen

Einführung

Wenn wir verteilte Anwendungen entwickeln, insbesondere in Architekturen, die auf Microservices basieren, wollen wir Komponenten, die sich in ihrer Ausführung skalieren und gut ausführen lassen. Sie verfügen über sehr komplexe Architekturen, Komponenten, die andere Komponenten ausführen, andere Komponenten ausführen usw. in einer unendlichen Anzahl von endlosen Aufrufen.

Die Planung, wie man jeden von ihnen entwickelt, ist eine große Aufgabe. Sie können Ihre Microservices, die auf einem Kubernetes-Cluster basieren, über das Oracle Cloud Infrastructure API Gateway (OCI API Gateway) bereitstellen. Es gibt eine Reihe von Funktionen, wie die Durchführung von Anrufauthentifizierung und -autorisierung, Datenvalidierung und Anrufoptimierung, um nur einige zu nennen. Es besteht auch die Möglichkeit, Anrufe mit OCI Functions auszuführen, um personalisierte Authentifizierungs- und Autorisierungsmechanismen zu erstellen, wenn vorhandene Methoden nicht ausreichen, um die Notwendigkeit zu lösen.

In diesem Tutorial wird gezeigt, wie Sie mit dem benutzerdefinierten Mechanismus einige Anwendungsfälle validieren, wie:

Validieren Sie die Größe der JSON-Parameterdaten.
Validieren Sie die maximale Anzahl von JSON-Elementen.

Obwohl es sich um einen Mechanismus zur Authentifizierung und Autorisierung im OCI-API-Gateway handelt, kann es bei einigen anderen Anforderungen helfen, z. B.:

Erfassen Sie Daten aus HEADER, Abfrageparametern oder dem Body des REST-Aufrufs.
Senden Sie diese Daten an OCI Observability, um das Debuggen von Problemen zu erleichtern, die ohne diese Informationen oft nicht zu erkennen sind.

Hinweis: Wenn Sie Daten an Observability senden, sollten Sie in Ihrem Code die Verdeckung für HEADER- oder BODY-Inhalte wie Kennwörter oder sensible Daten als Best Practice verwenden. Ein anderer Ansatz könnte sein, Ihre Funktion für Debugging-Zwecke zu aktivieren/deaktivieren.

Ziele

API-Deployment konfigurieren.
Entwickeln Sie eine OCI-Funktion, um den HEADER und BODY aus der API-Anforderung zu erfassen.
JSON-Haupttextdaten validieren.
Senden Sie die HEADER- und BODY-Informationen an OCI Observability.

Voraussetzungen

Ein operativer Oracle Cloud-Mandant. Sie können einen kostenlosen Oracle Cloud-Account mit einem monatlichen Betrag von 300,00 US-Dollar erstellen. Dieses Tutorial wird unter Kostenlosen Oracle Cloud-Account erstellen beschrieben.
Eine OCI API Gateway-Instanz, die erstellt und im Internet verfügbar gemacht wurde, finden Sie unter Erstes API-Gateway in Oracle Cloud erstellen.

Aufgabe 1: OCI-Beobachtbarkeit konfigurieren

Erstellen Sie ein Log in Ihrem OCI-Mandanten, um die Logs aus Ihrer Funktion aufzunehmen. Navigieren Sie zu Observability and Management, und wählen Sie in der OCI-Konsole die Option Logs aus.
Klicken Sie auf Benutzerdefiniertes Log erstellen.
Geben Sie einen Namen in das Feld Name benutzerdefiniertes Log ein, und wählen Sie ein gültiges Compartment und eine geeignete Loggruppe aus.

Hinweis: Es ist wichtig, die OCID des Logs zu erfassen. Sie benötigen diese für Ihren Code.

Logging-4

Aufgabe 2: OCI-Funktion zum Erfassen der HEADER und BODY aus der API-Anforderung erstellen

Um die folgenden Schritte auszuführen, laden Sie Code von hier function.zip herunter.

Erfassen Sie den HEADER und den BODY aus der API-Anforderung.
Validieren Sie die Body-JSON-Daten. Es gibt eine Methode zur Validierung der Anzahl der Elemente in jedem Array.

Senden Sie die HEADER- und BODY-Informationen an 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})
    )

Code verstehen

Diesen Code finden Sie hier: function.zip.

Hinweis: Wenn Sie nicht wissen, wie Sie eine Funktion entwickeln und in API Gateway aufrufen, lesen Sie Funktion mit API Gateway aufrufen.

Methode count_items, mit der Elemente in einem beliebigen Array innerhalb der JSON-Struktur gezählt werden.
Dieser Teil des Codes verwendet das OCI-SDK für Python, um die Konfigurationsdatei und den Private Key für den Zugriff auf Ihren OCI-Mandanten zu laden.
rdata erfasst die Parameter aus der Anforderung und bereitet die Antwort vor, um die Funktion zum Aufrufen des Backends der API-Gateway-Konfiguration zu autorisieren. active = True führt die Autorisierung aus.
jsonData wird verwendet, um die HEADERs- und BODY-Inhalte in OCI Observability zu generieren.
Dieser Code erfasst nur die BODY-JSON-Struktur aus der Anforderung.
Unter Code werden die Elemente auf den Arrays innerhalb der BODY JSON-Struktur gezählt. Wenn die Artikelanzahl mehr als 1 Artikel überholt, wird aktiv auf Falsch gesetzt, und ein Fehlerlog wird an OCI-Beobachtbarkeit gesendet. Um das Log zu senden, müssen Sie das Python-OCI-SDK verwenden.

Hinweis: Ersetzen Sie die Variable log_id durch das in Aufgabe 1 generierte OCID-Log.

Wenn die Anzahl kleiner oder gleich 1 ist, wird ein Log mit Anforderungs-HEADERs- und BODY-Inhalten in OCI Observability generiert. Denken Sie daran, die Variable log_id durch das OCID-Log zu ersetzen.

Hinweis: Sie können Logs in verschiedenen OCI-Logs erstellen. In diesem Tutorial wurde nur ein Log erstellt. Sie können jedoch weitere Logs erstellen.
Bei einem Fehler wird hier eine Fehlermeldung mit dem Fehler generiert.

SDK-Authentifizierung für OCI konfigurieren

Sie müssen die Konfigurationsdatei konfigurieren und Ihren OCI-Private Key und Fingerprint mit Ihrer Funktion ablegen, bevor Sie sie in OCI bereitstellen. Sie müssen die Dateien config und private key für die Installation und Konfiguration der Oracle Cloud Infrastructure-Befehlszeilenschnittstelle (OCI-CLI) generieren lassen.

Informationen zum Installieren und Konfigurieren der OCI-CLI finden Sie unter OCI-CLI installieren. Bei dieser Installation und Konfiguration werden zwei Dateien für Sie generiert. Suchen Sie die Datei config und private key (Standard ist oci_api_key.pem). Der Ordnerpfad wird in den Installationsanweisungen angegeben.

Code-2

Laden Sie function.zip herunter, um den Code, die Konfigurationsdatei und den Private Key anzuzeigen. Ersetzen Sie die Konfigurations- und Private-Key-Dateien durch Ihre OCI-CLI-Dateien.

OCI-Funktion erstellen und bereitstellen

In diesem Schritt müssen wir die OCI-CLI verwenden, um die OCI-Funktionen zu erstellen und Code in Ihrem Mandanten bereitzustellen. Informationen zum Erstellen einer OCI-Funktion finden Sie unter OCI Functions QuickStart, und suchen Sie nach der Option "Python". Sie müssen Ihre Funktion mit folgenden Informationen erstellen:

Anwendung: fn_apigw_json

Denken Sie an das Compartment, das Sie für Ihre Funktion bereitgestellt haben. Sie benötigen diese Informationen, um das OCI-API-Gateway-Deployment zu konfigurieren.

Aufgabe 3: OCI-Funktion in API Gateway konfigurieren

Stellen Sie Ihre API bereit, und integrieren Sie sie in Ihre OCI-Funktionen, um Anforderungsparameter (Header und BODY) zu validieren und an OCI Observability zu senden. Wenn Sie nicht wissen, wie Sie Ihr Backend im OCI-API-Gateway bereitstellen, finden Sie weitere Informationen unter OCI-API-Gateway: API einrichten, erstellen und bereitstellen.

Öffnen Sie Deployment bearbeiten.
Klicken Sie auf den Abschnitt Authentifizierung.
Klicken Sie auf Einzelne Authentifizierung, und wählen Sie Autorisiererfunktion aus.
Wählen Sie das Funktions-Compartment (in dem Sie Ihre Funktion bereitgestellt haben), wählen Sie die Anwendung fn_apigw_json und die Funktion python-json-header aus.
Konfigurieren Sie die Funktionsargumente, um den HEADER und BODY zu erfassen. Erfassen Sie den HEADER namens header und header2 sowie den BODY-Inhalt, der als body benannt wird.
Klicken Sie auf Routen, und konfigurieren Sie die Headertransformation. Diese Konfiguration ist optional, nur um den Antwortinhalt mit den Anforderungsdaten (HEADER- und BODY-Inhalt) oder die bei der Anforderung generierten Fehler anzuzeigen. Es wird nützlich sein, Ihre Funktion zu debuggen.

Aufgabe 4: Anforderung testen

Hinweis: In Ihrem API-Deployment wird ein Cache für die Functions-Argumente aktiviert, wenn Sie die Autorisiererfunktion konfigurieren und die Functions-Argumente einrichten. Sie können festlegen, welcher Datentyp im Cache gespeichert wird. Sie können den Cache für Abfrageparameter oder Header konfigurieren, jedoch nicht für Textinhalt.

Wir können die API-Anforderung testen. Testen wir nur mit einem Element in einem Array im Body.

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 wurde gesendet, aber im Log angezeigt, weil es nicht als Funktionsargument im OCI-API-Gateway konfiguriert wurde. Es gibt nur 1 Element im BODY-JSON-Array, also eine gültige Autorisierungsanforderung.

Test-1

Lassen Sie uns ein weiteres Element auf Array setzen und testen.

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

Danksagungen

Autor - Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)

Weitere Lernressourcen

Lernen Sie andere Übungen auf docs.oracle.com/learn kennen, oder greifen Sie auf weitere kostenlose Lerninhalte im Oracle Learning YouTube Channel zu. Besuchen Sie außerdem education.oracle.com/learning-explorer, um Oracle Learning Explorer zu werden.

Produktdokumentation finden Sie im Oracle Help Center.

Titel und Copyright-Informationen

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

F89782-01

November 2023