Nota

• Questa esercitazione richiede l'accesso a Oracle Cloud. Per iscriverti a un account gratuito, consulta Inizia a utilizzare Oracle Cloud Infrastructure Free Tier.
• Utilizza valori di esempio per le credenziali, la tenancy e i compartimenti di Oracle Cloud Infrastructure. Al termine del laboratorio, sostituisci questi valori con quelli specifici del tuo ambiente cloud.

Utilizza OCI API Gateway, Functions e Observability per convalidare il contenuto JSON e monitorare le intestazioni e il corpo delle API

Introduzione

Quando sviluppiamo applicazioni distribuite, in particolare in architetture basate su microservizi, vogliamo componenti scalabili e performanti nella loro esecuzione. Hanno architetture molto complesse, componenti che eseguono altri componenti, che eseguono altri componenti e così via in un numero infinito di chiamate infinite.

Pianificare come sviluppare ognuno di loro è un compito enorme. Puoi esporre i tuoi microservizi basati su un cluster Kubernetes tramite Oracle Cloud Infrastructure API Gateway (OCI API Gateway). Esistono una serie di strutture, come l'esecuzione dell'autenticazione e dell'autorizzazione delle chiamate, la convalida dei dati e l'ottimizzazione delle chiamate, solo per citarne alcune. C'è anche la possibilità di eseguire chiamate con OCI Functions con l'obiettivo di creare meccanismi di autenticazione e autorizzazione personalizzati, quando i metodi esistenti non sono sufficienti per risolvere la necessità.

In questa esercitazione viene illustrato come utilizzare il meccanismo personalizzato per convalidare alcuni casi d'uso, ad esempio:

• Convalidare la dimensione dei dati dei parametri JSON.

• Convalidare il numero massimo di elementi JSON.

Pur essendo un meccanismo per l'autenticazione e l'autorizzazione nel gateway API OCI, potrebbe aiutare con alcune altre esigenze, come:

• Acquisisce i dati da HEADER, dai parametri di query o dal corpo della chiamata REST.

• Invia questi dati a OCI Observability con l'obiettivo di facilitare il debug dei problemi, che sono spesso impossibili da rilevare senza queste informazioni.

  Nota: se si inviano dati a Observability, considerare nel codice, come best practice, l'uso della protezione dati sensibili per i contenuti HEADER o BODY, come password o dati riservati. Un altro approccio potrebbe essere quello di attivare / disattivare la funzione per scopi di debug.

Obiettivi

• Configurare una distribuzione API.

• Sviluppa una funzione OCI per acquisire HEADER e BODY dalla richiesta API.

• Convalidare i dati JSON del corpo.

• Invia le informazioni HEADER e BODY a OCI Observability.

Prerequisiti

• Un tenant Oracle Cloud operativo. Puoi creare un account Oracle Cloud gratuito con 300,00 USD per un mese per provare questa esercitazione. Vedere Crea un account Oracle Cloud gratuito.

• Un'istanza del gateway API OCI creata ed esposta a Internet. Vedere Creazione del primo gateway API in Oracle Cloud.

Task 1: configurare l'osservabilità OCI

1. Creare un log nella tenancy OCI per includere i log dalla funzione. Passare a Osservabilità e gestione e selezionare Log nella console OCI.

   

2. Fare clic su Crea log personalizzato.

   

3. Immettere un nome nel campo Nome log personalizzato e scegliere un compartimento e un gruppo di log appropriati.

   

Nota: è importante acquisire l'OCID del log, necessario per il codice.

Task 2: creare una funzione OCI per acquisire HEADER e CORPO dalla richiesta API

Per eseguire i passaggi seguenti, scaricare il codice da qui function.zip.

• Acquisire HEADER e BODY dalla richiesta API.

• Convalidare i dati JSON del corpo. Esiste un metodo per convalidare il numero di elementi in ogni array.

• Invia le informazioni HEADER e 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})
      )
  

Comprendere il codice

Questo codice è disponibile all'indirizzo function.zip.

Nota: se non si sa come sviluppare una funzione e chiamarla in Gateway API, vedere Chiamare una funzione utilizzando Gateway API.

• Metodo count_items utilizzato per conteggiare gli elementi in qualsiasi array all'interno della struttura JSON.

  

• Questa parte del codice utilizza l'SDK OCI per Python per caricare il file di configurazione e la chiave privata per accedere alla tenancy OCI.

  

• rdata acquisirà i parametri dalla richiesta e preparerà la risposta per autorizzare la funzione a chiamare il backend della configurazione del gateway API. L'autorizzazione verrà eseguita da active = True.

  

• Verrà utilizzato jsonData per generare il contenuto HEADER e BODY in OCI Observability.

  

• Questo codice acquisirà dalla richiesta solo la struttura JSON BODY.

  

• Sotto il codice verranno conteggiati gli elementi negli array all'interno della struttura JSON BODY. Se il conteggio degli articoli supera più di 1 articolo, l'opzione Attivo verrà impostata su Falso e verrà inviato un log degli errori a Osservabilità OCI. Per inviare il log, dovrai utilizzare l'SDK OCI Python.

  Nota: sostituire la variabile log_id con il log OCID generato nel task 1.

  

  Se il conteggio è minore o uguale a 1, in OCI Observability verrà generato un log con contenuto di richiesta HEADER e BODY. Ricordarsi di sostituire la variabile log_id con il log OCID.

  Nota: è possibile produrre log in Log OCI diversi. In questa esercitazione è stato creato un solo log, ma è possibile creare più log.

  

• In caso di errore, qui verrà generato un messaggio con l'errore.

  

Configurare l'autenticazione SDK su OCI

Devi configurare il file di configurazione e inserire la chiave privata e l'impronta digitale OCI con la tua funzione prima di distribuirla in OCI. È necessario che i file config e chiave privata siano generati nell'installazione e nella configurazione dell'interfaccia della riga di comando di Oracle Cloud Infrastructure (OCI CLI).

Per installare e configurare l'interfaccia CLI OCI, vedere Installa l'interfaccia CLI OCI. Questa installazione e configurazione genereranno automaticamente due file. Trovare i file config e chiave privata (l'impostazione predefinita è oci_api_key.pem). Il percorso della cartella verrà informato nelle istruzioni di installazione.

Scaricare function.zip per visualizzare il codice, il file di configurazione e la chiave privata. Sostituire i file di configurazione e di chiave privata con i file dell'interfaccia CLI OCI.

Crea e distribuisci la funzione OCI

In questo passo, sarà necessario utilizzare l'interfaccia CLI OCI per creare le funzioni OCI e distribuire il codice nella tenancy. Per creare una funzione OCI, vedere Funzioni OCI QuickStart e cercare l'opzione Python. Dovrai creare la tua funzione con queste informazioni:

• Applicazione: fn_apigw_json

Ricordare il compartimento in cui è stata distribuita la funzione. Queste informazioni saranno necessarie per configurare la distribuzione del gateway API OCI.

Task 3: configurare la funzione OCI nel gateway API

Distribuiamo la tua API e la integriamo con le tue funzioni OCI per convalidare e inviare i parametri di richiesta (Header e BODY) a OCI Observability. Se non si sa come esporre il backend in uso nel gateway API OCI, vedere Gateway API OCI: Impostazione, creazione e distribuzione di un'interfaccia API.

1. Aprire Modifica distribuzione.

   

2. Fare clic sulla sezione Autenticazione.

   

3. Fare clic su Autenticazione singola e selezionare Funzione autorezer.

   

4. Scegliere il compartimento delle funzioni (in cui è stata distribuita la funzione), selezionare l'applicazione fn_apigw_json e la funzione python-json-header.

   

5. Configurare gli argomenti delle funzioni per acquisire HEADER e BODY. Acquisire il contenuto HEADER denominato header e header2 e il contenuto BODY che verrà denominato body.

   

6. Fare clic su Cicli e configurare la trasformazione intestazione. Questa configurazione è facoltativa, solo per visualizzare il contenuto della risposta con i dati della richiesta (contenuto HEADER e BODY) o gli errori generati sulla richiesta. Sarà utile eseguire il debug della funzione.

   

Task 4: Testare la richiesta

Nota: nella distribuzione API verrà attivata una cache per gli argomenti Funzioni se si configura la funzione del responsabile autorizzazioni e si impostano gli argomenti Funzioni. È possibile stabilire il tipo di dati che verrà inserito nella cache. È possibile configurare la cache per il parametro o l'intestazione della query, ma non per il contenuto del corpo.

Possiamo testare la richiesta API. Proviamo con un solo elemento su un array nel corpo.

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

L'header3 è stato inviato ma mostrato nel log perché non è stato configurato come argomento di funzione nel gateway API OCI. L'array BODY JSON contiene solo 1 elemento, pertanto si tratta di una richiesta di autorizzazione valida.

Mettiamo un altro elemento su array e test.

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

Collegamenti correlati

• Panoramica di OCI API Gateway

• Panoramica delle funzioni OCI

• OCI Observability - Observability and Management in the Cloud

• Riferimento API SDK OCI - LoggingClient

• Esempio di SDK OCI Python

• Creazione del primo gateway API in Oracle Cloud

• Funzioni: chiamare una funzione utilizzando API Gateway

• Installare l'interfaccia CLI OCI

• Funzioni QuickStart

• OCI API Gateway: impostazione, creazione e distribuzione di un'API

Conferme

• Autore - Cristiano Hoshikawa (Solution Engineer Oracle LAD A-Team)

Altre risorse di apprendimento

Esplora altri laboratori su docs.oracle.com/learn o accedi a più contenuti gratuiti sulla formazione su Oracle Learning YouTube channel. Inoltre, visita education.oracle.com/learning-explorer per diventare Oracle Learning Explorer.

Per la documentazione del prodotto, visitare Oracle Help Center.

---

Titolo e informazioni sul copyright

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

F89782-01

November 2023

Copyright © 2023, Oracle and/or its affiliates.