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.

Migra le API a Oracle Cloud Infrastructure API Gateway con Oracle Integration

Introduzione

Il servizio Oracle Cloud Infrastructure API Gateway (OCI API Gateway) ti consente di pubblicare API con endpoint privati accessibili sulla tua rete e che puoi esporre con indirizzi IP pubblici se vuoi che accettino il traffico Internet. Gli endpoint supportano la convalida delle API, la trasformazione delle richieste e delle risposte, il CORS, l'autenticazione e l'autorizzazione e la limitazione delle richieste.

Il servizio gateway API OCI consente di creare uno o più gateway API in una subnet regionale per elaborare il traffico del client API e instradarlo ai servizi backend. Puoi utilizzare un singolo gateway API per collegare più servizi backend (ad esempio load balancer, istanze di computazione e Oracle Cloud Infrastructure Functions) in un unico endpoint API consolidato.

Puoi accedere al servizio gateway API OCI per definire i gateway API e le distribuzioni API utilizzando la console OCI e l'API REST.

Il servizio OCI API Gateway è integrato con Oracle Cloud Infrastructure Identity and Access Management (OCI IAM), che fornisce una facile autenticazione con la funzionalità di identità nativa Oracle Cloud Infrastructure (OCI).

OCI API Gateway consente di eseguire la distribuzione delle API importando una struttura JSON. Qui è possibile visualizzare il formato di questa struttura Creazione di una specifica di distribuzione API.

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

Oltre alla console, è possibile distribuire l'API utilizzando l'interfaccia della riga di comando di Oracle Cloud Infrastructure (OCI CLI) e anche il servizio REST OCI per il gateway API OCI. Di seguito è riportata la documentazione per comprendere come distribuire:

Se hai già la struttura API da distribuire nel formato standard del gateway API OCI, è facile distribuirla utilizzando la console (importazione), l'interfaccia CLI OCI o effettuando una chiamata REST. Avendo questa struttura pronta, è facile creare codice per elaborare più file JSON. L'esempio seguente illustra come elaborare i file utilizzando il codice 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

In alcune situazioni, sarà necessario gestire le informazioni sui metadati API. Potremmo farlo attraverso il codice utilizzando Python, Java o un altro linguaggio, ma lo scopo di questa esercitazione è quello di utilizzare Oracle Integration per automatizzarlo. Ci sono diversi vantaggi nel farlo in questo modo. È possibile:

Esegui le chiamate REST dal gateway API OCI per distribuire le API.
Mappare gli attributi dall'origine alla destinazione, incluse le trasformazioni appropriate.
Implementa il flusso per elaborare graficamente tutte le impostazioni.

Obiettivi

Spiegare come importare la specifica API legacy nel gateway API OCI.
Spiegare i formati noti e il formato che OCI API Gateway può importare in modo nativo.
Crea un processo Oracle Integration per eseguire la migrazione di una definizione di distribuzione API di origine nel gateway API OCI.
Elabora più definizioni di origine.
Differenzia le definizioni REST e SOAP.
Mappa gli attributi di origine al gateway API OCI di destinazione.
Distribuisci nell'ambiente corretto (QA, DEV).

Prerequisiti

Istanza Oracle Integration.
Due istanze di OCI API Gateway (in questa esercitazione ne abbiamo create una per il controllo qualità e un'altra per gli ambienti DEV).
L'istanza di Oracle Integration deve raggiungere le istanze del gateway API OCI (attenzione alle reti private).

Task 1: Comprendere la struttura dei dati API di origine

Possiamo iniziare da una struttura di metadati API. Le definizioni più note sarebbero un OpenAPI o un Swagger.

Se si dispone di un servizio SWAGGER o OpenAPI, è possibile importare i dati API nel gateway API OCI importando i dati nella console OCI, nell'interfaccia CLI OCI o nel servizio REST del gateway API OCI. Vedere Creazione di una risorsa API con una descrizione API.

Se non si dispone di questi formati (Swagger/OpenAPI), è necessario strutturare le definizioni di dati API in un altro formato. In questo compito, lavoreremo con una struttura Excel e, da questa struttura, la trasformeremo in JSON.

Quindi, c'è una struttura JSON con cui lavorare.

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

Queste strutture di dati API sono disponibili qui: source_apis.json. È possibile strutturare i dati delle definizioni API in qualsiasi formato, questo è solo un esempio.

Task 2: Comprendere i dati di distribuzione di OCI API Gateway

In questo task è possibile visualizzare il formato nativo per importare le definizioni API nel gateway API OCI. Spesso, una struttura semplice è sufficiente per implementare un'API, ma poiché vengono visualizzati dettagli come sicurezza, regole di intestazione, parametri o altri dettagli, la struttura JSON diventa più grande. Questa sarebbe la struttura JSON completa per qualsiasi tipo di distribuzione. Verrà utilizzato nel flusso di Oracle Integration. Il file è disponibile all'indirizzo: 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"
              }
            ]
          }
        }
      }
    }
  ]
}

Task 3: Crea connessioni

Ci sono 2 connessioni che dobbiamo creare. La prima connessione è la connessione REST trigger. Questa connessione verrà utilizzata per esporre un endpoint in Oracle Integration. Con questo endpoint, puoi chiamare il processo di migrazione come servizio REST, passando i dati di origine delle API.

La seconda connessione verrà utilizzata per chiamare il servizio REST OCI API Gateway per creare le distribuzioni API. La documentazione REST del gateway API OCI può essere letta qui: Distribuzione delle API tramite REST.

Creare una connessione a Oracle Integration, vedere Creare una connessione REST.

Cercare l'adattatore REST.
Indicare un nome e un identificativo, ad esempio il nome "REST_EXPOSE". Questa è la prima connessione. Selezionare il ruolo trigger. Ruolo trigger indica che la connessione verrà esposta come endpoint REST, quindi fare clic su Crea.
Per l'endpoint trigger, è possibile eseguire una richiesta con l'autenticazione di base di Oracle Integration. È quindi possibile utilizzare un nome utente e una password.
Nella seconda connessione, come nella prima, indicare un nome e un identificativo (ad esempio, "APIGW_REST_API"). Ricordarsi di selezionare il tipo Richiama a differenza della prima configurazione. Selezionare il REST del gateway API OCI appropriato per la propria area (nell'esempio, l'area è Ashburn). Vedere qui per visualizzare l'endpoint appropriato per gli endpoint del gateway API OCI della propria area. Ottenere le credenziali OCI per fornire l'accesso al servizio OCI API Gateway.

Task 4: Creare l'integrazione

Il processo di migrazione dei metadati di origine API nel gateway API OCI è il seguente:

Esporre il trigger come servizio REST in Oracle Integration.
Inizializza i gateway API OCI di destinazione (ambienti come QA e DEV).
Inizializzare i compartimenti per le destinazioni.
Eseguire un loop per elaborare tutte le API nei metadati di origine.
Tradurre i metadati di origine nei metadati del gateway API OCI.
Esegue un servizio REST di richiesta nel gateway API OCI.

Esporre l'integrazione con la connessione REST trigger creata in precedenza.
Assegnare un nome all'endpoint della richiesta.
Fornire un percorso (ad esempio, /convert) e selezionare il metodo POST. Ricordarsi di stabilire un payload di richiesta.
Ora puoi selezionare l'esempio JSON e incollare la struttura di origine JSON.
Incollare qui il JSON.
Inizializziamo ora le variabili per le istanze del gateway API (ogni ambiente è una nuova istanza del gateway API). Creare una variabile per il metodo di pagamento. Ricorda che puoi usare diversi metodi in REST (GET, POST, PUT, DELETE, ANY) e devi usare POST nei servizi SOAP.
Creare un loop FOR EACH. Questa operazione elaborerà la lista JSON di origine.
Modificare l'azione For Each e trascinare la selezione dell'array di livelli di loop nell'attributo Elemento ricorrente.
Configurare il reindirizzamento dell'ambiente. Creare un'azione Switch e inserire i IF e le assegnazioni per ogni condizione.
Creare la prima condizione per l'ambiente QA.
Verificare nell'attributo ENVIRONMENT dei metadati di origine e verificare se il valore è "QA".
Se la condizione è vera, è necessario assegnare l'ambiente corretto. Un valore GatewayID e CompartmentID è un valore OCID. È necessario assegnare gli ID corretti alle variabili.
Fate lo stesso per gli altri ambienti.
Ora vediamo se la tua API è un servizio REST o SOAP. Se l'API è un servizio SOAP, è necessario configurare il metodo come POST.
Creare una condizione IF per eseguire il test del tipo di servizio.
Assegnare il valore POST alla variabile di metodo.
In altre situazioni, l'attributo di origine fornisce il metodo corretto.
Mappiamo gli attributi dei metadati di origine ai parametri del gateway API OCI. Prima dell'azione di mapping, è necessario configurare l'adattatore REST del gateway API OCI.
Configurare la connessione.
Specificare un nome per questo servizio. Il percorso deve essere /deployments e il metodo deve essere POST. Ricordarsi di configurare il payload della richiesta.
Impossibile incollare la struttura del gateway API OCI JSON a causa delle dimensioni elevate. È quindi necessario caricare un file con il contenuto. La struttura JSON completa è disponibile all'indirizzo apigw_structure.json.
Mappare i metadati di destinazione.

Nota: è possibile visualizzare l'artifact di Oracle Integration qui: Oracle Integration: Migra l'API di origine a OCI API Gateway. Questo esempio di artifact non è destinato ad essere utilizzato come processo finale per la migrazione e ha solo l'obiettivo di illustrare il processo. Utilizzare questo artifact per guidare l'implementazione reale.

Task 5: eseguire il test della migrazione

Per ulteriori informazioni, fare riferimento ai collegamenti seguenti e attenersi alla procedura riportata di seguito.

Aggiungere i dati JSON di origine.
Fare clic su Test e attendere il completamento.
Vai alle distribuzioni delle istanze di OCI API Gateway e scopri la creazione delle tue 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

Migrate APIs to Oracle Cloud Infrastructure API Gateway with Oracle Integration

F88509-01

October 2023