附註：
- 此教學課程需要存取 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，而若要讓 API 接受網際網路流量，則可以公開使用公用 IP 位址。端點支援 API 驗證、要求和回應轉換、CORS、認證和授權，以及要求限制。
您可以使用 OCI API 閘道服務，在區域子網路上建立一或多個 API 閘道，以處理 API 從屬端流量並將其遞送至後端服務。您可以使用單一 API 閘道，將多個後端服務 (例如負載平衡器、運算執行處理和 Oracle Cloud Infrastructure Functions) 連結至單一整合式 API 端點。
您可以使用 OCI 主控台和 REST API 存取 OCI API 閘道服務，以定義 API 閘道和 API 部署。
OCI API Gateway 服務已與 Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) 整合，以原生 Oracle Cloud Infrastructure (OCI) 身分識別功能提供輕鬆的認證。
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。以下是瞭解如何部署的文件：
如果您的 API 結構已使用標準 OCI 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 閘道以原生方式匯入的格式。
-
建立 Oracle Integration 處理作業，將來源 API 部署定義移轉至 OCI API 閘道。
-
處理多個來源定義。
-
區別 REST 和 SOAP 定義。
-
將來源屬性對應至目標 OCI API 閘道。
-
部署到正確的環境 (QA、DEV)。
必要條件
-
Oracle Integration 執行處理。
-
兩個 OCI API 閘道執行處理 (在本教學課程中，我們為 QA 和其他 DEV 環境建立了一個執行處理)。
-
Oracle Integration 執行處理必須連線 OCI API 閘道執行處理 (注意專用網路)。
作業 1：瞭解您的來源 API 資料結構
我們可以從 API 描述資料結構開始。最好的定義是 OpenAPI 或 Swagger。
如果您有 SWAGGER 或 OpenAPI，則可以在 OCI 主控台、OCI CLI 或 OCI API Gateway 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 閘道部署資料
在這項任務中，您可以看到原生格式，將您的 API 定義匯入 OCI API 閘道。簡單的結構通常已經足以實行 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 個連線。第一個連線是觸發 REST 連線。此連線將用來在 Oracle Integration 中顯示端點。透過此端點，您可以將移轉處理作業作為 REST 服務呼叫，以傳遞 API 的來源資料。
第二個連線將會用來呼叫 OCI API 閘道 REST 服務，以建立您的 API 部署。您可以從此處閱讀 OCI API Gateway REST 文件：透過 REST 部署 API 。
建立 Oracle Integration 連線，請參閱建立 REST 連線。
-
搜尋 REST 轉接器。
-
輸入名稱和 ID，例如，提供名稱 "REST_EXPOSE"。這是第一個連線。選取「觸發器角色」。「觸發程式角色」表示您將以 REST 端點形式顯示連線，按一下建立。
-
針對觸發程式端點，您可以使用 Oracle Integration 基本認證執行要求。因此，您可以使用使用者名稱與密碼。
-
在第二個連線中，就像您在第一個連線中一樣，請提供名稱和識別碼 (例如，"APIGW_REST_API")。請記得選取與第一個組態不同的「呼叫」類型。為您的區域選取適當的 OCI API 閘道 REST (例如阿什本區域)。請參閱此處以檢視您區域 OCI API Gateway 端點的正確端點。取得您的 OCI 證明資料，以提供對 OCI API 閘道服務的存取。
任務 4：建立整合
將 API 來源描述資料移轉至 OCI API 閘道的處理作業包括：
-
在 Oracle Integration 中以 REST 服務形式顯示觸發程式。
-
起始目標 OCI API 閘道 (像是 QA 和 DEV 的環境)。
-
起始目標的區間。
-
執行迴圈以處理來源描述資料中的所有 API。
-
將來源描述資料轉譯成 OCI API 閘道描述資料。
-
對 OCI API 閘道執行要求 REST 服務。
-
顯示與先前建立之觸發程式 REST 連線的整合。
-
提供要求端點的名稱。
-
提供路徑 (例如，
/convert)，然後選取 POST 方法。請記得建立要求有效負載。
-
您現在可以選取「JSON 範例」並貼上 JSON 來源結構。
-
將 JSON 貼到此處。
-
現在，讓我們初始化 API 閘道執行處理的變數 (每個環境都是新的 API 閘道執行處理)。為 METHOD 建立變數。請記住，您可以在 REST (GET、POST、PUT、DELETE、ANY) 中使用數種方法，且必須在 SOAP 服務中使用 POST。
-
建立 FOR EACH 迴圈。這將會處理來源 JSON 清單。
-
編輯「針對每個動作」，並將您的「迴圈層次陣列」拖放至重複元素屬性。
-
現在，設定環境重新導向。建立「切換動作」，然後為每個條件放置 IF 與指派。
-
建立品保環境的第一個條件。
-
驗證來源中繼資料 ENVIRONMENT 屬性並測試其是否具有 "QA" 值。
-
如果條件為真，您必須指派正確的環境。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 。
-
對應目標 Metadata。
注意：您可以在此處查看 Oracle Integration 使用者自建物件：Oracle Integration：將來源 API 移轉至 OCI API 閘道。此使用者自建物件範例不是要作為移轉的最終處理作業，而且只有目標能夠說明處理作業。使用此使用者自建物件引導您實際實行。
作業 5：測試移轉
如需詳細資訊，請參閱下列連結並遵循下面的步驟。
-
新增來源 JSON 資料。
-
按一下測試 (Test) 並等待完成。
-
前往 OCI API Gateway 執行處理部署，然後查看 API 的建立。
相關連結
確認書
- 作者 - Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)
其他學習資源
探索 docs.oracle.com/learn 的其他實驗室，或者存取更多 Oracle Learning YouTube 頻道上的免費學習內容。此外，請瀏覽 education.oracle.com/learning-explorer 以成為 Oracle Learning 檔案總管。
如需產品文件，請造訪 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.