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.

APIs mit Oracle Integration zu Oracle Cloud Infrastructure API Gateway migrieren

Einführung

Mit dem Oracle Cloud Infrastructure API Gateway-(OCI-API-Gateway-)Service können Sie APIs mit zugänglichen privaten Endpunkten in Ihrem Netzwerk veröffentlichen. Sie können aber auch öffentliche IP-Adressen dafür angeben. Endpunkte unterstützen API-Validierung, Anforderungs- und Antworttransformation, CORS, Authentifizierung und Autorisierung sowie Anforderungsbegrenzung.

Mit dem OCI-API-Gateway-Service erstellen Sie API-Gateways in einem regionalen Subnetz, um API-Clienttraffic zu verarbeiten und an Backend-Services weiterzuleiten. Sie können ein einzelnes API-Gateway verwenden, um mehrere Backend-Services (wie Load Balancer, Compute-Instanzen und Oracle Cloud Infrastructure Functions) mit einem einzelnen konsolidierten API-Endpunkt zu verknüpfen.

Sie können auf den OCI-API-Gateway-Service zugreifen, um API-Gateways und API-Deployments mit der OCI-Konsole und der REST-API zu definieren.

Der OCI API Gateway-Service ist in Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) integriert, was eine einfache Authentifizierung mit nativen Oracle Cloud Infrastructure-(OCI-)Identitätsfunktionen ermöglicht.

Mit dem OCI-API-Gateway kann das API-Deployment durch Importieren einer JSON-Struktur erfolgen. Hier wird das Format dieser Struktur API-Deployment-Spezifikation erstellen angezeigt.

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

Neben der Konsole können Sie die API über die Oracle Cloud Infrastructure-Befehlszeilenschnittstelle (OCI-CLI) und auch den OCI-REST-Service für das OCI-API-Gateway bereitstellen. Nachfolgend finden Sie die Dokumentation zum Deployment:

Wenn Ihre API-Struktur bereits im OCI-API-Gateway-Standardformat bereitgestellt werden soll, können Sie sie einfach über die Konsole (Import), die OCI-CLI oder durch einen REST-Aufruf bereitstellen. Durch die Bereitstellung dieser Struktur ist es einfach, Code zur Verarbeitung mehrerer JSON-Dateien zu erstellen. Dieses Beispiel unten zeigt, wie Dateien mit bash-Skriptcode verarbeitet werden:

#!/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 einigen Fällen müssen API-Metadateninformationen verarbeitet werden. Wir könnten dies durch Code mit Python, Java oder einer anderen Sprache tun, aber der Zweck dieses Tutorials ist es, Oracle Integration zu verwenden, um es zu automatisieren. Es gibt mehrere Vorteile, dies auf diese Weise zu tun. Sie können ganz einfach:

Führen Sie REST-Aufrufe aus OCI API Gateway aus, um Ihre APIs bereitzustellen.
Ordnen Sie Attribute von Quelle zu Ziel zu, einschließlich der entsprechenden Transformationen.
Implementieren Sie den Ablauf, um alle Einstellungen grafisch zu verarbeiten.

Ziele

Erläutern Sie, wie Sie die Legacy-APIs-Spezifikation in das OCI-API-Gateway importieren.
Erläutern Sie die bekannten Formate und das Format, das OCI API Gateway nativ importieren kann.
Erstellen Sie einen Oracle Integration-Prozess, um eine Quell-API-Deployment-Definition in das OCI-API-Gateway zu migrieren.
Mehrere Quelldefinitionen verarbeiten
Unterscheiden Sie REST- und SOAP-Definitionen.
Ordnen Sie die Quellattribute dem OCI-Ziel-API-Gateway zu.
In der richtigen Umgebung bereitstellen (QA, DEV).

Voraussetzungen

Eine Oracle Integration-Instanz.
Zwei OCI API Gateway-Instanzen (in diesem Tutorial haben wir eine für die Qualitätssicherung und eine andere für DEV-Umgebungen erstellt).
Die Oracle Integration-Instanz muss die OCI API Gateway-Instanzen erreichen (Aufmerksamkeit für private Netzwerke).

Aufgabe 1: Quell-API-Datenstruktur verstehen

Sie können mit einer API-Metadatenstruktur beginnen. Die bekanntesten Definitionen wären OpenAPI oder Swagger.

Wenn Sie über einen SWAGGER oder eine OpenAPI verfügen, können Sie Ihre API-Daten in OCI API Gateway importieren, indem Sie sie in Ihre OCI-Konsole, OCI-CLI oder OCI API Gateway-REST-Service importieren. Informationen hierzu finden Sie unter API-Ressource mit einer API-Beschreibung erstellen.

Wenn diese Formate (Swagger/OpenAPI) nicht vorhanden sind, müssen Sie die API-Datendefinitionen in einem anderen Format strukturieren. In dieser Aufgabe arbeiten wir mit einer Excel-Struktur und wandeln sie aus dieser Struktur in JSON um.

Es gibt also eine JSON-Struktur, mit der gearbeitet werden kann.

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

Diese API-Datenstrukturen finden Sie hier: source_apis.json. Sie können Ihre API-Definitionsdaten in einem beliebigen Format strukturieren. Dies ist nur ein Beispiel.

Aufgabe 2: OCI API Gateway-Deployment-Daten verstehen

In dieser Aufgabe wird das native Format zum Importieren Ihrer API-Definitionen in das OCI-API-Gateway angezeigt. Oft reicht eine einfache Struktur aus, um eine API zu implementieren. Da jedoch Details wie Sicherheit, Headerregeln, Parameter oder andere Details angezeigt werden, wird die JSON-Struktur größer. Dies wäre die vollständige JSON-Struktur für jeden Deployment-Typ. Wir verwenden sie in unserem Oracle Integration-Ablauf. Die Datei finden Sie hier: 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"
              }
            ]
          }
        }
      }
    }
  ]
}

Aufgabe 3: Verbindungen erstellen

Es gibt 2 Verbindungen, die wir schaffen müssen. Die erste Verbindung ist die Trigger-REST-Verbindung. Mit dieser Verbindung wird ein Endpunkt in Oracle Integration bereitgestellt. Mit diesem Endpunkt können Sie den Migrationsprozess als REST-Service aufrufen und die Quelldaten Ihrer APIs übergeben.

Mit der zweiten Verbindung wird der OCI-API-Gateway-REST-Service aufgerufen, um Ihre APIs bereitzustellen. Die OCI API Gateway-REST-Dokumentation finden Sie hier: APIs über REST bereitstellen.

Erstellen Sie eine Oracle Integration-Verbindung. Informationen hierzu finden Sie unter REST-Verbindung erstellen.

Suchen Sie den REST-Adapter.
Geben Sie einen Namen und eine ID an. Beispiel: Geben Sie den Namen "REST_EXPOSE" an. Dies ist die erste Verbindung. Wählen Sie die Triggerrolle aus. Triggerrolle bedeutet, dass Sie die Verbindung als REST-Endpunkt angeben und auf Erstellen klicken.
Für den Triggerendpunkt können Sie eine Anforderung mit der Basisauthentifizierung von Oracle Integration ausführen. Sie können also einen Benutzernamen und ein Kennwort verwenden.
Geben Sie in der zweiten Verbindung wie in der ersten Verbindung einen Namen und eine ID an (z.B. "APIGW_REST_API"). Denken Sie daran, den Aufruftyp im Gegensatz zur ersten Konfiguration auszuwählen. Wählen Sie den richtigen OCI API Gateway-REST für Ihre Region aus (im Beispiel ist die Region Ashburn). Hier finden Sie den richtigen Endpunkt für die OCI-API-Gateway-Endpunkte Ihrer Region. Rufen Sie Ihre OCI-Zugangsdaten ab, um Zugriff auf den OCI API Gateway-Service zu ermöglichen.

Aufgabe 4: Integration erstellen

Die Migration Ihrer API-Quellmetadaten zum OCI API Gateway läuft wie folgt ab:

Geben Sie den Trigger als REST-Service in Oracle Integration an.
Initialisieren Sie die OCI-Ziel-API-Gateways (Umgebungen wie Qualitätssicherung und DEV).
Initialisieren Sie die Compartments für die Ziele.
Führen Sie eine Schleife aus, um alle APIs in den Quellmetadaten zu verarbeiten.
Übersetzen Sie die Quellmetadaten in die OCI API Gateway-Metadaten.
Führen Sie einen Anforderungs-REST-Service an das OCI-API-Gateway aus.

Zeigen Sie die Integration mit der zuvor erstellten Trigger-REST-Verbindung an.
Geben Sie dem Anforderungsendpunkt einen Namen.
Geben Sie einen Pfad an (z.B. /convert), und wählen Sie die POST-Methode aus. Denken Sie daran, eine Anforderungs-Payload einzurichten.
Jetzt können Sie das "JSON-Beispiel" auswählen und Ihre JSON-Quellstruktur einfügen.
Fügen Sie die JSON hier ein.
Lassen Sie uns nun die Variablen für Ihre API Gateway-Instanzen initialisieren (jede Umgebung ist eine neue API Gateway-Instanz). Erstellen Sie eine Variable für die Methode. Denken Sie daran, dass Sie mehrere Methoden in REST verwenden können (GET, POST, PUT, DELETE, ANY) und POST in SOAP Services verwenden müssen.
Erstellen Sie eine FOR EACH-Schleife. Dadurch wird die JSON-Quellliste verarbeitet.
Bearbeiten Sie die Option "Für jede Aktion", und ziehen Sie das Array auf Loop-Ebene per Drag-and-Drop in das Attribut Wiederholungselement.
Jetzt konfigurieren wir die Umgebungsumleitung. Erstellen Sie eine Switch-Aktion, und legen Sie die IFs und die Zuweisungen für jede Bedingung fest.
Erstellen Sie die erste Bedingung für die QS-Umgebung.
Prüfen Sie im Attribut ENVIRONMENT der Quellmetadaten, und testen Sie, ob es den Wert "QA" aufweist.
Wenn die Bedingung wahr ist, müssen Sie die richtige Umgebung zuweisen. GatewayID und CompartmentID sind OCID-Werte. Sie müssen den Variablen die richtigen Kennungen zuweisen.
Machen Sie dasselbe für die anderen Umgebungen.
Lassen Sie uns nun sehen, ob Ihre API ein REST- oder SOAP-Service ist. Wenn Ihre API ein SOAP-Service ist, müssen Sie die Methode als POST konfigurieren.
Erstellen Sie eine IF-Bedingung, um den Servicetyp zu testen.
Weisen Sie der Methodenvariable den POST-Wert zu.
In anderen Situationen gibt das Quellattribut die richtige Methode an.
Mappen Sie die Quellmetadatenattribute den OCI-API-Gateway-Parametern. Vor der Zuordnungsaktion müssen Sie den OCI-API-Gateway-REST-Adapter konfigurieren.
Konfigurieren Sie die Verbindung.
Geben Sie einen Namen für diesen Service an. Der Pfad muss /deployments und die Methode POST sein. Denken Sie daran, die Anforderungs-Payload zu konfigurieren.
Sie können die JSON-OCI-API-Gateway-Struktur aufgrund der großen Größe nicht einfügen. Sie müssen also eine Datei mit dem Inhalt hochladen. Die vollständige JSON-Struktur finden Sie hier: apigw_structure.JSON.
Ordnen Sie die Zielmetadaten zu.

Hinweis: Das Oracle Integration-Artefakt wird hier angezeigt: Oracle Integration: Quell-API zu OCI-API-Gateway migrieren. Dieses Artefaktbeispiel ist nicht als endgültiger Prozess für die Migration gedacht und hat nur das Ziel, den Prozess zu veranschaulichen. Verwenden Sie dieses Artefakt, um Ihre echte Implementierung zu steuern.

Aufgabe 5: Migration testen

Weitere Informationen finden Sie unter den folgenden Links, und führen Sie die folgenden Schritte aus.

Fügen Sie die JSON-Quelldaten hinzu.
Klicken Sie auf Testen, und warten Sie, bis der Vorgang abgeschlossen ist.
Gehen Sie zu den OCI API Gateway-Instanz-Deployments, und sehen Sie sich die Erstellung Ihrer APIs an.

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

Migrate APIs to Oracle Cloud Infrastructure API Gateway with Oracle Integration

F88509-01

October 2023