Observação:

Este tutorial requer acesso ao Oracle Cloud. Para se inscrever e obter uma conta gratuita, consulte Conceitos Básicos do Oracle Cloud Infrastructure Free Tier.
Ele usa valores de exemplo para credenciais, tenancy e compartimentos do Oracle Cloud Infrastructure. Ao concluir seu laboratório, substitua esses valores por valores específicos do seu ambiente de nuvem.

Migrar APIs para o Oracle Cloud Infrastructure API Gateway com o Oracle Integration

Introdução

O serviço Oracle Cloud Infrastructure API Gateway (OCI API Gateway) permite que você publique APIs com pontos finais privados acessíveis na sua rede e que você possa expor com endereços IP públicos se quiser que eles aceitem o tráfego da internet. Os pontos finais suportam validação de API, transformação de solicitação e resposta, CORS, autenticação e autorização e limitação de solicitação.

Usando o Serviço de Gateway de API do OCI, você cria um ou mais Gateways de API em uma sub-rede regional para processar o tráfego do cliente de API e roteá-lo para serviços de backend. Você pode usar um único Gateway de API para vincular vários serviços de backend (como balanceadores de carga, instâncias de computação e Oracle Cloud Infrastructure Functions) em um único ponto final de API consolidado.

Você pode acessar o OCI API Gateway Service para definir Gateways de API e implementações de API usando a Console do OCI e a API REST.

O serviço OCI API Gateway é integrado ao Oracle Cloud Infrastructure Identity and Access Management (OCI IAM), que fornece fácil autenticação com funcionalidade nativa de identidade do OCI (Oracle Cloud Infrastructure).

O Gateway de API do OCI permite que a implantação de API seja feita importando uma estrutura JSON. Aqui você pode ver o formato desta estrutura Criando uma Especificação de Implantação de API.

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

Além da console, é possível implantar a API usando a interface de linha de comando (CLI) do OCI (Oracle Cloud Infrastructure) e também o serviço REST do OCI para o Gateway de API do OCI. Aqui está a documentação para entender como implantar:

Se você já tiver sua estrutura de API para implantar no formato padrão do OCI API Gateway, será fácil implantá-la usando a console (importação), a CLI do OCI ou fazendo uma chamada REST. Ao ter essa estrutura pronta, é fácil criar código para processar vários arquivos JSON. Este exemplo abaixo demonstra como processar arquivos usando o código de 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

Em algumas situações, as informações de metadados da API precisarão ser tratadas. Podemos fazer isso por meio de código usando Python, Java ou outra linguagem, mas o propósito deste tutorial é usar o Oracle Integration para automatizá-lo. Existem várias vantagens em fazer isso dessa maneira. Você pode facilmente:

Execute chamadas REST do OCI API Gateway para implantar suas APIs.
Mapeie atributos da origem para o destino, incluindo as transformações apropriadas.
Implemente o fluxo para processar todas as definições graficamente.

Objetivos

Explique como importar sua especificação de APIs Legadas para o OCI API Gateway.
Explicar os formatos conhecidos e qual formato o OCI API Gateway pode importar de forma nativa.
Crie um processo do Oracle Integration para migrar uma definição de implantação de API de origem para o OCI API Gateway.
Processar várias definições de origem.
Diferencie as definições REST e SOAP.
Mapeie os atributos de origem para o Gateway de API do OCI de destino.
Implante no ambiente correto (QA, DEV).

Pré-requisitos

Uma instância do Oracle Integration.
Duas instâncias do OCI API Gateway (neste tutorial, criamos uma para QA e outra para ambientes DEV).
A instância do Oracle Integration precisa acessar as instâncias do OCI API Gateway (atenção a redes privadas).

Tarefa 1: Compreender a estrutura de dados da API de Origem

Podemos começar com base em uma estrutura de metadados da API. As definições mais conhecidas seriam OpenAPI ou Swagger.

Se você tiver um SWAGGER ou um OpenAPI, poderá importar seus dados de API para o OCI API Gateway importando na Console do OCI, na CLI do OCI ou no Serviço REST do OCI API Gateway, consulte Criando um Recurso de API com uma Descrição de API.

Se você não tiver esses formatos (Swagger/OpenAPI), precisará estruturar suas definições de dados da API em outro formato. Nesta tarefa, trabalharemos com uma estrutura do Excel e, a partir dessa estrutura, transformá-la em JSON.

Portanto, há uma estrutura JSON com a qual trabalhar.

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

Essas estruturas de dados da API podem ser encontradas aqui: source_apis.json. Você pode estruturar seus dados de definições de API em qualquer formato. Este é apenas um exemplo.

Tarefa 2: Compreender os Dados de Implantação do Gateway de API do OCI

Nesta tarefa, você pode ver o formato nativo para importar suas definições de API para o OCI API Gateway. Muitas vezes, uma estrutura simples é suficiente para implementar uma API, mas como detalhes como segurança, regras de cabeçalho, parâmetros ou outros detalhes aparecem, a estrutura JSON se torna maior. Esta seria a estrutura JSON completa para qualquer tipo de implantação. Usaremos isso em nosso fluxo do Oracle Integration. Você pode encontrar o arquivo aqui: 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"
              }
            ]
          }
        }
      }
    }
  ]
}

Tarefa 3: Criar Conexões

Há 2 conexões que precisamos criar. A primeira conexão é a Conexão REST do Trigger. Esta conexão será usada para expor um ponto final no Oracle Integration. Com esse ponto final, você pode chamar o processo de migração como um serviço REST, passando os dados de origem de suas APIs.

A segunda conexão será usada para chamar o serviço REST do OCI API Gateway a fim de criar suas implantações de APIs. A documentação REST do OCI API Gateway pode ser lida aqui: Implantando APIs via REST.

Crie uma Conexão do Oracle Integration. Consulte Criar uma Conexão REST.

Pesquise o Adaptador REST.
Dê um nome e um identificador, por exemplo, dê o nome "REST_EXPOSE". Esta é a primeira conexão. Selecione a Função do Trigger. Atribuição de Trigger significa que você exporá a conexão como um ponto final REST, clique em Criar.
Para seu Ponto Final de Trigger, você pode executar uma solicitação com a Autenticação Básica do Oracle Integration. Portanto, você pode usar um nome de usuário e uma senha.
Na segunda conexão, como você fez na primeira conexão, forneça um nome e um identificador (por exemplo, "APIGW_REST_API"). Lembre-se de selecionar o tipo Chamar ao contrário da primeira configuração. Selecione o OCI API Gateway REST adequado para sua região (no exemplo, a região é Ashburn). Consulte aqui para exibir o ponto final adequado para sua região pontos finais do OCI API Gateway. Obtenha suas Credenciais do OCI para fornecer acesso ao serviço OCI API Gateway.

Tarefa 4: Criar a Integração

O processo de migração dos metadados de origem da API para o OCI API Gateway é:

Exponha o Trigger como um Serviço REST no Oracle Integration.
Inicialize os Gateways de API do OCI de Destino (ambientes como QA e DEV).
Inicialize os Compartimentos dos destinos.
Execute um Loop para processar todas as APIs nos metadados de origem.
Traduza os metadados de origem para os metadados do OCI API Gateway.
Execute um Serviço REST de Solicitação para o Gateway de API do OCI.

Exponha sua Integração com sua Conexão REST do Trigger criada anteriormente.
Dê um nome ao ponto final da solicitação.
Forneça um caminho (por exemplo, /convert) e selecione o método POST. Lembre-se de estabelecer um payload de solicitação.
Agora você pode selecionar o "JSON Sample" e colar sua estrutura de origem JSON.
Cole o JSON aqui.
Agora vamos inicializar as variáveis das suas instâncias do API Gateway (cada ambiente é uma nova instância do API Gateway). Crie uma variável para o MÉTODO. Lembre-se de que você pode usar vários métodos em REST (GET, POST, PUT, DELETE, ANY) e precisar usar POST nos Serviços SOAP.
Crie um Loop FOR EACH. Isso processará a lista JSON de origem.
Edite a Ação Para Cada e arraste e solte sua Matriz de Nível de Loop no Atributo Elemento Repetitivo.
Agora vamos configurar o redirecionamento do ambiente. Crie uma Ação Switch e coloque os IFs e as atribuições de cada condição.
Crie a primeira condição para o ambiente de QA.
Verifique no atributo ENVIRONMENT dos metadados de origem e teste se ele tem o valor "QA".
Se a condição for verdadeira, você precisará atribuir o ambiente correto. GatewayID e CompartmentID são valores de OCID. É necessário atribuir os IDs corretos às variáveis.
Faça o mesmo para os outros ambientes.
Agora vamos ver se sua API é um serviço REST ou SOAP. Se sua API for um serviço SOAP, configure o método como POST.
Crie uma condição IF para testar o tipo de serviço.
Atribua o valor POST à variável de método.
Em outras situações, o atributo de origem fornece o método correto.
Vamos mapear os atributos de metadados de origem para os parâmetros do Gateway de API do OCI. Antes da ação de mapeamento, você precisa configurar o Adaptador REST do Gateway de API do OCI.
Configure a conexão.
Dê um nome a esse serviço. O caminho deve ser /deployments e o método deve ser POST. Lembre-se de configurar o payload da solicitação.
Você não pode colar a estrutura do Gateway de API do OCI JSON por causa do tamanho grande. Portanto, você precisa fazer upload de um arquivo com o conteúdo. A Estrutura JSON completa está aqui apigw_structure.json.
Mapeie os metadados de destino.

Observação: você pode ver o artefato do Oracle Integration aqui: Oracle Integration: Migrar sua API de Origem para o OCI API Gateway. Este exemplo de artefato não deve ser usado como um processo final para sua migração e tem apenas o objetivo de ilustrar o processo. Use este artefato para orientar sua implementação real.

Tarefa 5: Testar a migração

Para obter mais informações, consulte os links a seguir e siga as etapas abaixo.

Adicione os dados JSON de origem.
Clique em Testar e aguarde até terminar.
Vá para as implantações da instância do OCI API Gateway e veja a criação de suas APIs.

Confirmações

Autor - Cristiano Hoshikawa (Engenheiro de Soluções de Equipe A do Oracle LAD)

Mais Recursos de Aprendizagem

Explore outros laboratórios no site docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal YouTube do Oracle Learning. Além disso, visite education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.

Título e Informações de Copyright

Migrate APIs to Oracle Cloud Infrastructure API Gateway with Oracle Integration

F88509-01

October 2023