透過 OpenAPI 規格建立 API Proxy | Apigee Edge

本教學課程將說明如何使用 Apigee Edge 管理 UI，從 OpenAPI 規格建立 Edge API Proxy。使用 cURL 等 HTTP 用戶端呼叫 API Proxy 時，API Proxy 會將要求傳送至 Apigee 模擬目標服務。

關於 Open API Initiative

「Open API Initiative (OAI) 致力於根據 Swagger 規格，建立、發展及推廣與供應商無關的 API 說明格式。」如要進一步瞭解 Open API Initiative，請參閱 https://openapis.org。

OpenAPI 規格會使用標準格式說明 RESTful API。 OpenAPI 規格可採用 JSON 或 YAML 格式，不僅機器可讀，人類也能輕鬆閱讀及理解。規格會說明 API 的基本路徑、路徑和動詞、標頭、查詢參數、作業、內容類型、回應說明等元素。此外，OpenAPI 規格通常用於產生 API 說明文件。

關於 Apigee 模擬目標服務

本教學課程使用的 Apigee 模擬目標服務託管於 Apigee，並會傳回簡單資料。不需要 API 金鑰或存取權杖。事實上，你可以在網路瀏覽器中存取這項服務。如要試用，請按一下下列連結：

http://mocktarget.apigee.net

目標服務會傳回問候語 Hello, guest!

如要瞭解模擬目標服務支援的完整 API 集，請按一下下列連結：

http://mocktarget.apigee.net/help

軟硬體需求

Apigee Edge 帳戶。如果沒有帳戶，請按照「建立 Apigee Edge 帳戶」一文中的指示註冊。
OpenAPI 規格。在本教學課程中，您將使用 mocktarget.yaml OpenAPI 規格，說明 Apigee 的模擬目標服務 http://mocktarget.apigee.net。詳情請參閱 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi。
電腦上已安裝 cURL，可從指令列發出 API 呼叫；或使用網路瀏覽器。

建立 API Proxy

邊緣

如要使用 Edge UI，透過 OpenAPI 規格建立 API Proxy，請按照下列步驟操作：

登入 https://apigee.com/edge。
按一下主視窗中的「API Proxies」。
或者，您也可以在左側導覽列中選取「開發」>「API Proxy」。
按一下「+ Proxy」。
在「建立 Proxy」精靈中，按一下「Reverse proxy (most common)」範本的「Use OpenAPI Spec」。
按一下「從網址匯入」，然後輸入下列資訊：
- OpenAPI 規格網址：GitHub 上原始內容的路徑，請在「網址」欄位中輸入：
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- 規格名稱：OpenAPI 規格的名稱，例如「模擬目標」。
  這個名稱用於將 OpenAPI 規格儲存在規格儲存庫中。請參閱「管理規格」。

按一下「匯入」。

「Create Proxy」精靈會顯示「詳細資料頁面」。系統會使用 OpenAPI 規格中定義的值預先填入欄位，如下圖所示：

下表說明使用 OpenAPI 規格中的屬性預先填入的預設值。下表後方會顯示 OpenAPI 規格的摘錄內容，說明使用的屬性。

欄位	說明	預設
名稱	API Proxy 的名稱。例如：`Mock-Target-API`。	OpenAPI 規格中的 `title` 屬性，並以破折號取代空格
基本路徑	路徑元件，可在機構內唯一識別這個 API Proxy。這個 API Proxy 的公開網址包含機構名稱、部署這個 API Proxy 的環境，以及這個基準路徑。例如：`http://myorg-test.apigee.net/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
...

按照下列說明編輯「Description」(說明) 欄位：API proxy for the Apigee mock target service endpoint.
點選 [下一步]。
在「Common policies」(通用政策) 頁面的「Security: Authorization」(安全性：授權) 下方，確認已選取「Pass through (no authorization)」(直通 (無授權))，然後按一下「Next」(下一步)：
在「流程」頁面中，確認已選取所有作業。
提示：系統會根據 OpenAPI 規格中 paths 物件內定義的作業，自動產生條件流程。條件流程會告訴 Edge「看到這個時，請執行這項邏輯」。舉例來說，當 API 呼叫是針對 /xml 資源的 GET (條件) 時，請將回應轉換為 JSON (透過附加至條件式流程的政策)。每筆交易只會執行一個流程，也就是條件評估結果為 true 的第一個流程。
點選 [下一步]。
在「虛擬主機」頁面中，選取「default」和「secure」，然後按一下「下一步」。
在「摘要」頁面，確認已在「選用部署」下方選取「測試」環境，然後按一下「建立並部署」：

Apigee 會建立新的 API Proxy，並部署至測試環境：
按一下「編輯 Proxy」，即可顯示 API Proxy 的「總覽」頁面。

Classic Edge (Private Cloud)

如要使用 Classic Edge UI，透過 OpenAPI 規格建立 API Proxy，請按照下列步驟操作：

登入 https://apigee.com/edge。
按一下主視窗中的「API Proxies」。
或者，您也可以在左側導覽列中選取「開發」>「API Proxy」。
按一下「+ Proxy」。
在「建立 Proxy」精靈中，選取「Reverse proxy (most common)」，然後按一下「Use OpenAPI」。
按一下「從網址匯入」，輸入 OpenAPI 規範的名稱，然後在「網址」欄位中輸入 GitHub 上 OpenAPI 規範原始內容的路徑：

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
按一下「選取」。

按一下「下一步」。

「Create Proxy」精靈會顯示「詳細資料頁面」。系統會使用 OpenAPI 規格中定義的值預先填入欄位，如下圖所示。

下表說明使用 OpenAPI 規格中的屬性預先填入的預設值。下表後方會顯示 OpenAPI 規格的摘錄內容，說明使用的屬性。

欄位	說明	預設
Proxy 名稱	API Proxy 的名稱。例如：`Mock-Target-API`。	OpenAPI 規格中的 `title` 屬性，並以破折號取代空格
Proxy 底層路徑	路徑元件，可在機構內唯一識別這個 API Proxy。這個 API Proxy 的公開網址包含機構名稱、部署這個 API Proxy 的環境，以及這個基準路徑。例如：`http://myorg-test.apigee.net/mock-target-api`	「名稱」欄位內容已轉換為全小寫
現有 API	代表這個 API Proxy 呼叫的目標網址。您可以使用任何可透過開放網路存取的網址。例如： `http://mocktarget.apigee.net`	OpenAPI 規格中的 `servers` 屬性
說明	API Proxy 的說明。	OpenAPI 規格中的 `description` 屬性

以下是 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
...

按照下列說明編輯「Description」(說明) 欄位：API proxy for the Apigee mock target service endpoint.
點選 [下一步]。
在「流程」頁面中，確認已選取所有作業。
提示：系統會根據 OpenAPI 規格中 paths 物件內定義的作業，自動產生條件流程。條件流程會告訴 Edge「看到這個時，請執行這項邏輯」。舉例來說，當 API 呼叫是針對 /xml 資源的 GET (條件) 時，請將回應轉換為 JSON (透過附加至條件式流程的政策)。每筆交易只會執行一個流程，也就是條件評估結果為 true 的第一個流程。
點選 [下一步]。
在「安全性」頁面中，選取「Pass through (none)」(直通 (無)) 做為安全性選項，然後按一下「下一步」。
在「虛擬主機」頁面中，確認已選取所有虛擬主機，然後按一下「下一步」。
在「Build」頁面中，確定已選取「test」環境，然後按一下「Build and Deploy」。
在「摘要」頁面中，您會看到確認訊息，表示新的 API Proxy 已成功建立並部署至測試環境。
點選「Mock-Target-API」，顯示 API Proxy 的「總覽」頁面。

恭喜！您已使用 OpenAPI 規格建立 API Proxy。接著測試看看是否正常運作。

測試 API Proxy

您可以使用 cURL 或網路瀏覽器測試 Mock-Target-API API。

在終端機視窗中，執行下列 cURL 指令。在網址中代入貴機構的名稱。

curl http://<org_name>-test.apigee.net/mock-target-api

回應

畫面上應會顯示下列回應內容：

Hello, Guest!

太棒了！您已使用 OpenAPI 規格建構簡單的 API Proxy，並完成測試。

新增 XML 至 JSON 政策

接著，將 XML 轉 JSON 政策新增至「View XML Response」條件流程。這個流程是在您從 OpenAPI 規格建立 API Proxy 時自動產生。這項政策會將目標的 XML 回應轉換為 JSON 回應。

首先，請呼叫 API，以便比較結果與新增政策後收到的結果。在終端機視窗中執行下列 cURL 指令。您要呼叫目標服務的 /xml 資源，該資源會原生傳回簡單的 XML 區塊。在網址中代入貴機構的名稱。

curl http://<org_name>-test.apigee.net/mock-target-api/xml

回應

畫面上應會顯示下列回應內容：

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

現在，我們來將 XML 回應轉換為 JSON。將 XML 轉 JSON 政策新增至 API Proxy 的「View XML Response」條件流程。

在 Edge UI 的「Mock-Target-API Overview」頁面，按一下右上角的「Develop」分頁標籤。
在左側的「Navigator」窗格中，依序點選「Proxy Endpoints」>「default」，然後按一下「View XML Response」條件式流程。
點選流程「Response」對應的底部「+Step」按鈕。

「新增步驟」對話方塊隨即開啟，並顯示所有可新增政策的分類清單。
捲動至「中介服務」類別，然後選取「XML to JSON」(XML 轉 JSON)。
保留「顯示名稱」和「名稱」的預設值。
按一下「Add」。XML 轉 JSON 政策會套用至回應。
按一下 [儲存]。

新增政策後，請使用 cURL 再次呼叫 API。請注意，您仍會呼叫相同的 /xml 資源。目標服務仍會傳回 XML 區塊，但 API Proxy 中的政策現在會將回應轉換為 JSON。撥打這通電話：

curl http://<org_name>-test.apigee.net/mock-target-api/xml

請注意，XML 回應會轉換為 JSON：

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

恭喜！您已成功測試新增至條件流程的政策執行情況。