[手把手教學] Apigee 使用 OpenAPI Spec 快速建立反向代理服務 Reverse Proxy

為了迎接新一代 OpenAPI 開放生態圈的商業浪潮,想要將內部開發的 API 相關服務串接到外部的合作廠商,建立跨界生態圈 Eco System,千頭萬緒一下子不知道該從哪兒下手?

只要準備好 OpenAPI 的 YAML 檔案描述的內容,透過 Apigee Spec 內建的功能,透過精靈逐步引導的方式,就能夠輕鬆地建立反向代理服務,將 HTTP requests 需求從 Internet 轉送後端 Backend service。接下來,就讓我們一起來初步探究這個好用的 API 神器!

Apigee 提供一個 API 應用程式軟體管理平台,您可以參考 GCP專門家部落格另一篇介紹 [1] [2]

1. RESTful API 及 OpenAPI

1.1 Apigee API 代理服務及 RESTful API

基於 HTTP 的 RESTful API 與服務訊息交換目的,您可以建立 Apigee API Proxy 代理服務,容易使用的 API 管理介面,可提高開發人員的生產率並加快產品上市時間 [3]

API Proxy 代理服務,可以用來保護 API 呼叫、阻擋惡意攻擊、限制流量、中介消息、控制錯誤處理、快取功能、建立開發人員網站、管理 API 文件、分析 API 流量資料、依據 API 用量收費等豐富的功能。

1.2 OpenAPI 描述及 Mock Target 範例

一種用於 YAML 或 JSON 格式設計 RESTful API 描述內容檔案,準備好 OpenAPI 的描述檔案,透過 Apigee Spec 可以建立 API Proxy 代理服務,並產生 API 程式說明文件 [4] [5] [6]

這篇文章內使用 Mock Target API 的範例,用來模擬後端 Mock Target Service 提供訊息回應,可以從 GitHub 下載 OpenAPI 原始規格 YAML 檔,完整的 URL 網址為: https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml

只要透過瀏覽器存取 http://mocktarget.apigee.net,不需要透過 API Key 或 Token 權杖,就能夠得到 Hello, Guest! 的回應 [7],此範例其他的功能說明 [8]

2. 前置作業

2.1 Apigee Edge 雲端版試用

首先到 Apigee Edge 登入網頁註冊試用一個為期 30 天的帳號,就可以使用 Apigee SaaS 雲端版開始進行測試 [9]

2.2 Apigee 試用帳號申請流程

(1) 點選 Apigee 帳號註冊網頁,於瀏覽器內輸入相關個人資料、電子郵件帳號 Email 及密碼,公司及國家資訊等,勾選同意隱私權條款及接收 Google Cloud 產品資訊,按下【Create Account】[10]。 

(2) 提醒您接收電子郵件做確認並啟用帳號。

(3) 開啟 Apigee 的來信標題為 ”Active your Apigee account”,從中間點選【Active your account】連結。 

(4) 接著會收到標題為 ”Welcome to Apigee Edge” 的郵件,點選其中的登入連結。

(5) 於 Apigee Edge 登入畫面,輸入帳號密碼登入後就出現 Apigee Edge 的管理畫面,帳號下方顯示 “username-eval”,此為自動產生的組織名稱方便識別。

3.使用 Apigee Edge 服務及測試

Apigee Edge 支援幾種 API Proxy 代理服務,不同的使用時機與目的如下表說明,這篇文章使用第一種: 反向代理 Reverse Proxy  [11]

項目 API Proxy 型態 使用時機
1 Reverse proxy (大多數) 將 JSON 或 XML API 前端需求轉送到後端 HTTP backend service,也可以直接使用 OpenAPI Spec 規格產生反向代理服務
2 SOAP service 使用 WSDL 檔案產生 API 代理服務
3 No Target 沒有轉送到任何 API 後端的代理服務
4 Hosted Target 將前端需求轉送到後端 Node.js backend service
5 Proxy bundle 匯入既有 zip 壓縮設定檔,用來產生代理服務
6 Node.js App 此服務已暫停,被 Hosted Target 功能取代

透過 Apigee Edge 管理介面,如何使用 OpenAPI Spec 範例建立反向代理 Reverse Proxy。首先由前端 HTTP Client 呼叫 API Proxy,API Proxy 再轉送需求 Request 給後端 Backend service;接著由後端回應 Response 結果,再經由 API Proxy 回傳 Response 給前端 HTTP Client [7]

過程中包含這幾個步驟,底下詳細說明裡面的內容:

  • 步驟 1: 匯入 OpenAPI Spec 規格及 URL 網址 ( YAML 範例),在 Apigee Edge 快速建立反向代理 Reverse Proxy
  • 步驟 2: 依據產生 API Spec 規格,測試 OpenAPI 的基本操作
  • 步驟 3: 使用新建的 API Proxy 進行測試,追蹤後端的回應及前端得到的結果

3.1 匯入 OpenAPI Spec 規格及 URL 網址,建立Reverse Proxy

(1) 於 Apigee Edge 管理介面,左側點選 Develop -> API Proxies

(2) 進入 Proxies 頁面,從右上角點選【+Proxy】。

(3) 自動帶出 Create Proxy 頁面,預設已選好 Reverse proxy,點選下方的【Use OpenAPI】。

(4) 自動帶出產生規格 Spec 的對話視窗,選擇【Import from a URL】,輸入規格名稱 MOCK-TARGET 及 OpenAPI 範例的 URL 網址,然後按下【Select】。

(5) 自動帶入這個測試環境 OpenAPI Spec 文件內容的網址,接著按【Next】。

(6) 在 Create Proxy 第二步驟 Details 頁面,自動帶入 Proxy Name、Proxy Base Path、Existing API 及 Description,保留預設值繼續按【Next】。

(7) 在 Create Proxy 第三步驟 Flows 頁面,自動帶入想要開放的相關路徑及指令說明,保留預設全部勾選按【Next】。

(8) 在 Create Proxy 第四步驟 Security 頁面,這裡先跳過身分驗證的測試,將預設帶入 OAuth 2.0 項目改選【Pass through (none)】然後按【Next】。

(9) 在 Create Proxy 第五步驟 Virtual Hosts 頁面,保留預設勾選 default 及 secure,對外提供 http 及 https 的服務,接著點選【Next】。

(10) 在 Create Proxy 第六步驟 Build 頁面,預設已勾選 test 發布到測試環境,並說明前面的選項,點選【Build and Deploy】開始進行部署。

(12) 三個部署過程順利完成,下方會提示查看新建 API Proxy 的連結,點選【Mock-Target-API】進行檢視。

(13) 自動帶出 API Proxies 內 Mock-Target-API 的 OVERVIEW 頁面,工具列看到目前版本是 Revision 1,Deployment 下拉看到已部署到 test 測試環境,狀態 Status 是綠燈,也能看到對外服務的網址 URL。

3.2 依據產生 API Spec 規格,測試 OpenAPI 的基本操作

(1) 從左側點選 Develop->Specs,右邊頁面看到一些已建立的規格檔,點選新建的【MOCK-TARGET】。

(2) Specs 右邊視窗帶出 Home 頁面,中間區塊可以看到 OpenAPI 範例 Swagger 2.0 的程式碼規格及參數,右邊區塊可以看到支援的各種指令,點選第一個【GET / View personailzed greeting】查看內容。

(3) 右邊區塊第一個 GET / 指令內,中間參數 Parameters 可以點選【Try it out】。

(4) 右邊區塊第一個指令 GET / 內容,於 User 下方輸入字串 “Smith”,然後點選【Execute】執行,底下教導如何使用客製化參數姓名的兩種指令。

  • curl -X GET “http://mocktarget.apigee.net/?user=Smith” -H “accept: text/plain” 

=> Code Undocuments,結果出現錯誤 TypeError: Failed to fetch

  • http://mocktarget.apigee.net/?user=Smith 

=> Code 200,結果測試成功 Success

(5) 另一個指令 GET /statuscode/ {code} 內,於 HTTP status code 下方輸入代碼”429″,然後點選【Execute】執行,底下教導如何使用客製化參數狀態碼的兩種指令。

  • curl -X GET “http://mocktarget.apigee.net/statuscode/429” -H “accept: text/plain”
    => Code Undocuments,結果出現錯誤 TypeError: Failed to fetch
  • http://mocktarget.apigee.net/statuscode/429
    => Code 200,結果測試成功 Success

3.3 使用新建的 API Proxy 進行測試,追蹤後端回應及前端結果

(1) 從左側點選 Develop->API Proxies,右邊頁面看到一些已建立的 Proxy,點選新建的【Mock-Target-API】。

(2) 自動帶出 Mock-Target-API 的【OVERVIEW】頁面,確認 Revision 1 仍正常部署在 test 測試環境,點選【DEVELOP】頁面。

(3) 在 Mock-Target-API 的【DEVELOP】頁面,於左側 Proxy EndPoints 底下 default 區塊內,看到由 OpenAPI Spec 帶入的指令,匯入 OpenAPI Spec 規格及 URL 網址,由 YAML 範例檔內定義的的每個 API 指令、路徑及條件,都已經可供使用。

(4) 在 Mock-Target-API 的【TRACE】頁面,工具列點選【Start Trace Session】。

(5) Send Requests 區塊右方點選【Send】,一段時間後出現 Status 200 正常,Response Sent to Client 回應 OK,Response Content 回應內容 “Hello, Guest!”。

(6) 模擬使用者前端瀏覽器開啟 Apigee REST Client,貼上客製化姓名的問候指令,
http://ysnick-eval-test.apigee.net/mock-target-api?user=Apigee_Expert按【Send】於下方的 Body 分頁,成功得到 ”Hello, Apigee_Expert!” 的回應。

(7) 回到 Mock-Target-API 的【TRACE】頁面,看到上述的客製化姓名被追蹤得到回應 Status 200,回應給前端 Client 的內容 ”Hello, Apigee_Expert!”。

(8) 接著再開啟命令提示字元,執行一段客製化的指令,

curl -X GET “http://ysnick-eval-test.apigee.net/mock-target-api/statuscode/500” -H “accept: application/json”,底下得到空的回應。

(9) 回到 Mock-Target-API 的【TRACE】頁面,看到上述的客製化狀態碼測試指令已被追蹤 Status 500,回應給前端Client的訊息內容為”500 Internal Server Error”。

4. 總結

Apigee Edge 具備了方便的 API Proxy 代理功能,如果您已經具備 OpenAPI 的基本概念,透過 YAML 或 JSON 格式設計 RESTful API 描述內容檔案,就可以快速地建立新的代理服務,並產生 API 程式說明文件對外發布給開發人員使用。Apigee API 管理平台結合 OpenAPI 統一標準,能夠實現大量的 API 應用程式在短時間內完成上線的需求。

4.1 參考文件

[1] App Economy 最佳領航員!Google API 管理平台 Apigee 四大優勢
[2] Apigee Edge 總覽
[3] Apigee Build RESTful APIs 說明文件
[4] Apigee API 設計概念
[5] OpenAPI 專用的 Cloud Endpoints
[6] Swagger –什麼是OpenAPI
[7] Create an API proxy from an OpenAPI Specification
[8] Apigee Sample APIs-Mock Target
[9] Create an Apigee Edge account
[10] Create Your Apigee Account
[11] Build a simple API proxy

 

相關文章

App Economy 最佳領航員!Google API 管理平台 Apigee 四大優勢

美國抵押貸款領導品牌 Black Knight 透過 Google Cloud API 管理平台:Apigee,一次串連合作夥伴/開發者/客戶

四大提升 API 資訊安全的方法


連絡「GCP 專門家」