本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
課程內容
在本教學課程中，您將學習如何：
- 使用 OpenAPI 規格建立 Apigee API Proxy。
- 使用 cURL 呼叫 API Proxy。
- 在條件流程中新增政策。
- 使用 cURL 測試政策叫用。
您將瞭解如何使用 Apigee UI，從 OpenAPI 規格建立 Apigee API Proxy。使用 cURL 等 HTTP 用戶端呼叫 API Proxy 時，API Proxy 會將要求傳送至 Apigee 模擬目標服務。
關於 Open API Initiative
「Open API Initiative (OAI) 致力於根據 Swagger 規格，建立、演進及推廣與供應商無關的 API 說明格式。」如要進一步瞭解 Open API Initiative，請參閱「OpenAPI 規格」。
OpenAPI 規格採用標準格式說明 RESTful API。 OpenAPI 規格可採用 JSON 或 YAML 格式，不僅可供機器讀取，也方便使用者閱讀及瞭解。規格會說明 API 的基本路徑、路徑和動詞、標頭、查詢參數、作業、內容類型、回應說明等元素。此外，OpenAPI 規格通常用於產生 API 說明文件。
關於 Apigee 模擬目標服務
本教學課程使用的 Apigee 模擬目標服務託管於 Apigee，並會傳回簡單資料。不需要 API 金鑰或存取權杖。事實上，你可以在網路瀏覽器中存取這項服務。如要試用，請按一下下列連結：
目標服務會傳回問候語 Hello, guest!
如要瞭解模擬目標服務支援的完整 API 集，請參閱「Apigee 範例 API」。
事前準備
- 開始之前，請務必先完成「 總覽和必要條件」中的步驟。
- OpenAPI 規格。在本教學課程中，您將使用
mocktarget.yamlOpenAPI 規格，說明 Apigee 的模擬目標服務http://mocktarget.apigee.net。 詳情請參閱 apigee/api-platform-samples。 - 電腦上已安裝 cURL，可從指令列發出 API 呼叫；或使用網路瀏覽器。
建立 API Proxy
如要使用 OpenAPI 規格建立 API Proxy，請按照下列步驟操作：
Cloud 控制台中的 Apigee
-
在 Google Cloud 控制台中，前往「Proxy development」(Proxy 開發) >「API proxies」(API Proxy) 頁面。
- 在「API Proxies」窗格中，按一下「+ Create」。
- 在「建立 Proxy」窗格中，依序選取「Proxy 範本」>「OpenAPI 規格範本」， 然後選取「反向 Proxy (最常見)」。
- 在網路瀏覽器中前往下列網址：
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
- 在顯示的程式碼上按一下滑鼠右鍵，然後選取「另存新檔」。
- 按一下「儲存」，將
mocktarget3.0.yaml儲存至所需位置。 - 在「OpenAPI specs」(OpenAPI 規格) 欄位中，按一下「Browse」(瀏覽) 按鈕。
- 找到
mocktarget3.0.yaml檔案，然後按一下「開啟」。 - 點選「下一步」。
- 「建立 Proxy」精靈的「Proxy details」(Proxy 詳細資料) 步驟會直接從 OpenAPI 規格擷取值，並自動填入欄位。
- 在「Proxy details」(Proxy 詳細資料) 步驟中，按照下列說明編輯「Description」(說明) 欄位：
API proxy for the Apigee mock target service endpoint.
- 點選「下一步」。
- 在「流程」步驟中，確認已選取所有作業。
- 點選「下一步」。
- 在「部署」步驟中，選取一或多個環境，然後按一下「確定」。
- 點選「建立」。
下表說明使用 OpenAPI 規格預先填入的預設值：
| 欄位 | 說明 | 預設 |
|---|---|---|
| Proxy 名稱 | API Proxy 的名稱。例如 Mock-Target-API。 |
OpenAPI 規格中的 title 屬性，並以破折號取代空格 |
| 基本路徑 | 路徑元件，可在機構內唯一識別這個 API Proxy。
這個 API Proxy 的公開網址由外部或內部網域名稱和這個基本路徑組成。例如：
http://apitest.acme.com/mock-target-api |
「名稱」欄位內容轉換為全小寫 |
| 說明 | API Proxy 的說明。 | OpenAPI 規格中的 description 屬性 |
| 目標 (現有 API) | 代表這個 API Proxy 呼叫的目標網址。您可以使用任何可透過開放式網際網路存取的網址。例如：
http://mocktarget.apigee.net |
OpenAPI 規格中的 servers 屬性
|
以下是 OpenAPI 規範的摘錄內容，顯示用於預先填入欄位的屬性。
openapi: 3.0.0
info:
description: OpenAPI Specification for the Apigee mock target service endpoint.
version: 1.0.0
title: Mock Target API
paths:
/:
get:
summary: View personalized greeting
operationId: View a personalized greeting
description: View a personalized greeting for the specified or guest user.
parameters:
- name: user
in: query
description: Your user name.
required: false
schema:
type: string
responses:
"200":
description: Success
...
servers:
- url: http://mocktarget.apigee.net
- url: https://mocktarget.apigee.net
...
傳統版 Apigee UI
- 依序選取「開發」>「API Proxy」 ，然後在「Proxy」窗格中，選取 Proxy 的環境。
- 在主視窗中按一下「API Proxy」。
或者，您也可以在左側導覽列中選取「Develop」>「API Proxies」。
按一下「建立新項目」。
-
在「建立 Proxy」精靈中，按一下「反向 Proxy (最常見)」範本的「使用 OpenAPI 規格」。
- 按一下「網址」，然後輸入下列資訊：
OpenAPI 規格網址：在「網址」欄位中，輸入 GitHub 上 OpenAPI 規格原始內容的路徑：
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
- 按一下「選取」。
「建立 Proxy」精靈會顯示「Proxy details」(Proxy 詳細資料) 頁面。系統會使用 OpenAPI 規格中定義的值預先填入欄位，如下圖所示：
下表說明使用 OpenAPI 規格預先填入的預設值：
欄位 說明 預設 名稱 API Proxy 的名稱。例如 Mock-Target-API。OpenAPI 規格中的 title屬性，並以破折號取代空格基本路徑 路徑元件，可在機構內唯一識別這個 API Proxy。 這個 API Proxy 的公開網址由外部或內部網域名稱和這個基本路徑組成。例如： http://apitest.acme.com/mock-target-api「名稱」欄位內容轉換為全小寫 說明 API Proxy 的說明。 OpenAPI 規格中的 description屬性目標 (現有 API) 代表這個 API Proxy 呼叫的目標網址。您可以使用任何可透過開放式網際網路存取的網址。例如： http://mocktarget.apigee.netOpenAPI 規格中的 servers屬性以下是 OpenAPI 規範的摘錄內容，顯示用於預先填入欄位的屬性。
openapi: 3.0.0 info: description: OpenAPI Specification for the Apigee mock target service endpoint. version: 1.0.0 title: Mock Target API paths: /: get: summary: View personalized greeting operationId: View a personalized greeting description: View a personalized greeting for the specified or guest user. parameters: - name: user in: query description: Your user name. required: false schema: type: string responses: "200": description: Success ... servers: - url: http://mocktarget.apigee.net - url: https://mocktarget.apigee.net ... - 在「Proxy details」(Proxy 詳細資料) 頁面中，按照以下說明編輯「Description」(說明) 欄位：
API proxy for the Apigee mock target service endpoint.
- 點選「下一步」。
- 在「Common policies」頁面的「Security: Authorization」下方，確認已選取「Pass through (no authorization)」，然後按一下「Next」：
- 在「流程」頁面中，確認已選取所有作業。
- 點選「下一步」。
- 在「摘要」頁面中，確認已在「選用部署」下方選取環境，然後按一下「建立並部署」：
Apigee 會建立新的 API Proxy，並將其部署至您的環境：
- 按一下「編輯 Proxy」，即可顯示 API Proxy 的「總覽」頁面。
測試 API Proxy
您可以使用 cURL 或網頁瀏覽器測試 Mock-Target-API API。
curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy
其中 YOUR_ENV_GROUP_HOSTNAME 是環境群組主機名稱。請參閱「
尋找環境群組主機名稱」。
例如：
curl -v -k https://apitest.acme.com/myproxy
回應
您應會看到以下回應內容：
Hello, Guest!
新增 XML 至 JSON 政策
接下來，請將 XML 轉 JSON 政策新增至查看 XML 回應條件流程。這個流程是在您從 OpenAPI 規格建立 API Proxy 時自動產生。這項政策會將目標的 XML 回應轉換為 JSON 回應。
首先，請呼叫 API，以便比較結果與新增政策後收到的結果。在終端機視窗中執行下列 cURL 指令。您要呼叫目標服務的 /xml 資源，該資源會原生傳回簡單的 XML 區塊。
curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml
其中 YOUR ENV_GROUP_HOSTNAME 是環境群組主機名稱。請參閱「
找出環境群組主機名稱」。
回應
您應會看到以下回應內容：
<root> <city>San Jose</city> <firstName>John</firstName> <lastName>Doe</lastName> <state>CA</state> </root>
現在，我們來將 XML 回應轉換為 JSON。將 XML 轉 JSON 政策新增至 API Proxy 的「View XML Response」條件流程。
Cloud 控制台中的 Apigee
在 Apigee UI 的「Mock-Target-API Overview」(模擬目標 API 總覽) 頁面中，按一下「Develop」(開發) 分頁標籤。
- 在左側窗格中，依序點選「Proxy Endpoints」>「default」，然後按一下「View XML Response」條件流程。
- 在左側窗格中，按一下「政策」列中的「+」按鈕。
在「建立政策」對話方塊中，按一下「選取政策類型」欄位， 向下捲動至「中介服務」，然後選取「XMLToJSON」。 保留「顯示名稱」和「名稱」的預設值。
- 按一下「建立」，建立政策。
在「回應」中，按一下「查看 XML 回應」流程旁的「+」按鈕。
- 在「新增政策步驟」對話方塊中，按一下「選取現有政策」欄位，然後選取「XML to JSON-1」。
按一下「Add」(新增)。系統會將 XML 轉為 JSON 政策套用至回應。
如要查看「View XML Response」條件流程的程式碼，請按一下「Switch To Code Editor」。
- 按一下 [儲存]。
傳統版 Apigee UI
在 Apigee UI 的「Mock-Target-API Overview」(模擬目標 API 總覽) 頁面中，按一下「Develop」(開發) 分頁標籤。
在左側的「Navigator」窗格中，依序點選「Proxy Endpoints」>「default」，然後按一下「View XML Response」條件流程。
按一下底部的「+步驟」按鈕，對應流程的「回覆」。
「新增步驟」對話方塊隨即開啟，並顯示所有可新增政策的分類清單。
捲動至「中介服務」類別，然後選取「XML to JSON」。
- 保留「顯示名稱」和「名稱」的預設值。
按一下「Add」(新增)。系統會將 XML 轉為 JSON 政策套用至回應。
- 按一下 [儲存]。
新增政策後，請使用 cURL 再次呼叫 API。請注意，您仍會呼叫相同的 /xml 資源。目標服務仍會傳回 XML 區塊，但 API 代理程式中的政策現在會將回應轉換為 JSON。撥打以下電話：
curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml
其中 YOUR ENV_GROUP_HOSTNAME 是環境群組主機名稱。請參閱「
找出環境群組主機名稱」。
請注意，XML 回應會轉換為 JSON：
{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}