주:
- 이 사용지침서에서는 Oracle Cloud에 접근해야 합니다. 무료 계정에 등록하려면 Oracle Cloud Infrastructure Free Tier 시작하기를 참조하십시오.
- Oracle Cloud Infrastructure 인증서, 테넌시 및 구획에 대한 예제 값을 사용합니다. 실습을 완료하면 이러한 값을 클라우드 환경에 고유한 값으로 대체합니다.
Oracle Integration을 사용하여 API를 Oracle Cloud Infrastructure API Gateway로 이전
소개
Oracle Cloud Infrastructure API Gateway(OCI API Gateway) 서비스를 사용하면 네트워크에서 액세스 가능한 전용 끝점이 있는 API를 게시할 수 있으며, 인터넷 트래픽을 허용하려는 경우 공용 IP 주소로 노출할 수 있습니다. 엔드포인트는 API 검증, 요청 및 응답 변환, CORS, 인증 및 권한 부여, 요청 제한 등을 지원합니다.
OCI API 게이트웨이 서비스를 사용하면 지역 서브넷에 하나 이상의 API 게이트웨이를 생성하여 API 클라이언트 트래픽을 처리하고 백엔드 서비스로 라우팅할 수 있습니다. 단일 API 게이트웨이를 사용하여 여러 백엔드 서비스(예: 로드 밸런서, 컴퓨트 인스턴스 및 Oracle Cloud Infrastructure Functions)를 단일 통합 API 엔드포인트에 연결할 수 있습니다.
OCI API 게이트웨이 서비스에 액세스하여 OCI 콘솔 및 REST API를 사용하여 API 게이트웨이 및 API 배치를 정의할 수 있습니다.
OCI API 게이트웨이 서비스는 Oracle Cloud Infrastructure Identity and Access Management(OCI IAM)와 통합되어 기본 OCI(Oracle Cloud Infrastructure) ID 기능을 통한 손쉬운 인증을 제공합니다.
OCI API 게이트웨이를 사용하면 JSON 구조를 임포트하여 API 배치를 수행할 수 있습니다. 여기에서 API 배포 사양 생성 구조의 형식을 볼 수 있습니다.
{
"requestPolicies": {},
"routes": [
{
"path": "<api-route-path>",
"methods": ["<method-list>"],
"backend": {
"type": "<backend-type>",
"<backend-target>": "<identifier>"
},
"requestPolicies": {}
}
]
}
콘솔 외에도 Oracle Cloud Infrastructure 명령행 인터페이스(OCI CLI)와 OCI API 게이트웨이용 OCI REST 서비스를 사용하여 API를 배포할 수 있습니다. 배포 방법을 이해하기 위한 설명서는 다음과 같습니다.
표준 OCI API 게이트웨이 형식으로 배포할 API 구조가 이미 있는 경우 콘솔(임포트), OCI CLI를 사용하거나 REST 호출을 통해 쉽게 배포할 수 있습니다. 이 구조를 준비하면 여러 JSON 파일을 처리하는 코드를 쉽게 생성할 수 있습니다. 아래 예제는 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
경우에 따라 API 메타데이터 정보를 처리해야 합니다. Python, Java 또는 다른 언어를 사용하는 코드를 통해 이를 수행할 수 있지만 이 자습서의 목적은 Oracle Integration을 사용하여 자동화하는 것입니다. 이런 식으로 하는 것은 여러 가지 장점이 있다. 다음 작업을 쉽게 수행할 수 있습니다.
-
OCI API 게이트웨이에서 REST 호출을 실행하여 API를 배치합니다.
-
적절한 변환을 포함하여 소스에서 대상으로 속성을 매핑합니다.
-
모든 설정을 그래픽으로 처리하는 플로우를 구현합니다.
목표
-
레거시 API 사양을 OCI API 게이트웨이로 임포트하는 방법을 설명합니다.
-
알려진 형식과 OCI API Gateway가 기본적으로 임포트할 수 있는 형식에 대해 설명합니다.
-
Oracle Integration 프로세스를 생성하여 소스 API 배치 정의를 OCI API 게이트웨이로 이전합니다.
-
다중 소스 정의를 처리합니다.
-
REST 및 SOAP 정의 구별
-
소스 속성을 대상 OCI API 게이트웨이에 매핑합니다.
-
올바른 환경(QA, DEV)에 배포합니다.
필요 조건
-
Oracle Integration 인스턴스입니다.
-
OCI API Gateway 인스턴스 2개(이 자습서에서는 QA용 인스턴스와 DEV 환경용 인스턴스를 각각 생성했습니다).
-
Oracle Integration 인스턴스는 OCI API 게이트웨이 인스턴스(전용 네트워크 주의)에 연결해야 합니다.
작업 1: 소스 API 데이터 구조 이해
API 메타데이터 구조에서 시작할 수 있습니다. 가장 잘 알려진 정의는 OpenAPI 또는 Swagger입니다.
SWAGGER 또는 OpenAPI가 있는 경우 OCI 콘솔, OCI CLI 또는 OCI API 게이트웨이 REST 서비스에서 임포트하여 API 데이터를 OCI API 게이트웨이로 임포트할 수 있습니다. API 설명을 사용하여 API 리소스 생성을 참조하십시오.
이러한 형식(Swagger/OpenAPI)이 없는 경우 API 데이터 정의를 다른 형식으로 구조화해야 합니다. 이 작업에서는 Excel 구조로 작업하고 이 구조에서 JSON으로 변환합니다.
따라서 작업할 JSON 구조가 있습니다.
[ {
"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" : ""
} ]
이러한 API 데이터 구조는 source_apis.json에서 찾을 수 있습니다. 어떤 형식으로든 API 정의 데이터를 구조화할 수 있습니다. 예를 들 수 있습니다.
작업 2: OCI API Gateway 배치 데이터 이해
이 작업에서는 기본 형식을 확인하여 API 정의를 OCI API Gateway로 임포트할 수 있습니다. 종종 API를 구현하기에 간단한 구조가 충분하지만 보안, 헤더 규칙, 매개변수 또는 기타 세부정보와 같은 세부정보가 나타나면 JSON 구조가 커집니다. 이는 모든 유형의 배포를 위한 완전한 JSON 구조입니다. Oracle Integration 플로우에서 사용할 것입니다. 파일은 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"
}
]
}
}
}
}
]
}
작업 3: 접속 생성
2개의 연결을 만들어야 합니다. 첫번째 연결은 Trigger REST Connection입니다. 이 접속은 Oracle Integration에서 끝점을 노출하는 데 사용됩니다. 이 끝점을 사용하면 마이그레이션 프로세스를 REST 서비스로 호출하여 API의 소스 데이터를 전달할 수 있습니다.
두번째 접속은 OCI API 게이트웨이 REST 서비스를 호출하여 API 배치를 생성하는 데 사용됩니다. OCI API 게이트웨이 REST 문서는 여기에서 확인할 수 있습니다. REST를 통한 API 배포.
Oracle Integration 연결을 생성합니다. REST 연결 생성을 참조하십시오.
-
REST 어댑터를 검색합니다.
-
이름과 식별자를 제공하십시오(예: "REST_EXPOSE"). 첫번째 접속입니다. Trigger Role을 선택합니다. 트리거 롤은 접속을 REST 끝점으로 노출하고 생성을 누르면 됩니다.
-
트리거 끝점에 대해 Oracle Integration 기본 인증을 사용하여 요청을 실행할 수 있습니다. 따라서 유저 이름과 암호를 사용할 수 있습니다.
-
두번째 연결에서 첫번째 연결에서와 같이 이름 및 식별자(예: "APIGW_REST_API")를 지정합니다. 첫번째 구성과 달리 Invoke 유형을 선택해야 합니다. 해당 지역에 적절한 OCI API 게이트웨이 REST를 선택합니다(예: 리전은 애슈번). OCI API 게이트웨이 엔드포인트 영역에 적합한 엔드포인트를 보려면 여기를 참조하십시오. OCI API 게이트웨이 서비스에 대한 액세스 권한을 제공하려면 OCI 인증서를 얻으십시오.
태스크 4: 통합 생성
API 소스 메타데이터를 OCI API 게이트웨이로 이전하는 프로세스는 다음과 같습니다.
-
트리거를 Oracle Integration에서 REST 서비스로 표시합니다.
-
대상 OCI API 게이트웨이(QA 및 DEV와 같은 환경)를 초기화합니다.
-
대상에 대한 구획을 초기화합니다.
-
루프를 실행하여 소스 메타데이터의 모든 API를 처리합니다.
-
소스 메타데이터를 OCI API Gateway 메타데이터로 변환합니다.
-
OCI API 게이트웨이에 대한 요청 REST 서비스를 실행합니다.
-
이전에 생성한 트리거 REST 연결과의 통합을 노출합니다.
-
요청 끝점에 이름을 제공하십시오.
-
경로(예:
/convert)를 지정하고 POST 메소드를 선택합니다. 요청 페이로드를 설정해야 합니다.
-
이제 "JSON 샘플"을 선택하고 JSON 소스 구조를 붙여 넣을 수 있습니다.
-
여기에 JSON을 붙여넣습니다.
-
이제 API 게이트웨이 인스턴스의 변수를 초기화하겠습니다(각 환경은 새 API 게이트웨이 인스턴스임). METHOD에 대한 변수를 생성합니다. REST(GET, POST, PUT, DELETE, ANY)에서 여러 가지 방법을 사용할 수 있으며 SOAP 서비스에서 POST를 사용해야 합니다.
-
FOR EACH 루프를 생성합니다. 소스 JSON 목록을 처리합니다.
-
For Each 작업을 편집하고 루프 레벨 배열을 반복 요소 속성으로 끌어 놓습니다.
-
이제 환경 재지정을 구성합니다. Switch Action을 생성하고 각 조건에 대해 IF와 할당을 배치합니다.
-
QA 환경에 대한 첫번째 조건을 만듭니다.
-
소스 메타 데이터 ENVIRONMENT 속성에서 "QA" 값이 있는지 테스트합니다.
-
조건이 true인 경우 올바른 환경을 지정해야 합니다. GatewayID 및 CompartmentID는 OCID 값입니다. 변수에 올바른 ID를 지정해야 합니다.
-
다른 환경에 대해서도 동일한 작업을 수행합니다.
-
이제 API가 REST 또는 SOAP 서비스인지 살펴보겠습니다. API가 SOAP 서비스인 경우 메소드를 POST로 구성해야 합니다.
-
서비스 유형을 테스트하는 IF 조건을 생성합니다.
-
POST 값을 메소드 변수에 지정합니다.
-
다른 경우에는 소스 속성이 올바른 방법을 제공합니다.
-
소스 메타데이터 속성을 OCI API 게이트웨이 매개변수에 매핑합니다. 매핑 작업 전에 OCI API 게이트웨이 REST 어댑터를 구성해야 합니다.
-
연결을 구성합니다.
-
이 서비스의 이름을 제공합니다. 경로는
/deployments이고 메소드는 POST여야 합니다. 요청 페이로드를 구성해야 합니다.
-
크기가 너무 커서 JSON OCI API 게이트웨이 구조를 붙여넣을 수 없습니다. 따라서 콘텐츠가 포함된 파일을 업로드해야 합니다. 전체 JSON 구조는 apigw_structure.json에 있습니다.
-
대상 메타데이터를 매핑합니다.
참고: Oracle Integration: 소스 API를 OCI API 게이트웨이로 이전에서 Oracle Integration 아티팩트를 확인할 수 있습니다. 이 아티팩트 예는 마이그레이션의 최종 프로세스로 사용되지 않으며 프로세스를 설명하는 목표만 있습니다. 이 아티팩트를 사용하여 실제 구현을 안내합니다.
작업 5: 이전 테스트
자세한 내용은 다음 링크를 참조하고 아래 단계를 따르십시오.
-
소스 JSON 데이터를 추가합니다.
-
테스트를 누르고 완료될 때까지 기다립니다.
-
OCI API Gateway 인스턴스 배치로 이동하여 API 생성을 확인합니다.
관련 링크
수락
- 작성자 - Cristiano Hoshikawa(Oracle LAD A-Team 솔루션 엔지니어)
추가 학습 자원
docs.oracle.com/learn에서 다른 실습을 살펴보거나 Oracle Learning YouTube 채널에서 더 많은 무료 학습 콘텐츠에 액세스하십시오. 또한 Oracle Learning Explorer가 되려면 education.oracle.com/learning-explorer를 방문하십시오.
제품 설명서는 Oracle Help Center를 참조하십시오.
Migrate APIs to Oracle Cloud Infrastructure API Gateway with Oracle Integration
F88509-01
October 2023
Copyright © 2023, Oracle and/or its affiliates.