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

本教學課程將說明如何透過 OpenAPI 建立 Edge API Proxy 使用 Apigee Edge 管理 UI 的規格。使用 HTTP 用戶端 (例如 cURL) 會將要求傳送至 Apigee 模擬目標課程中也會快速介紹 Memorystore 這是 Google Cloud 的全代管 Redis 服務

關於 Open API 計畫

敬上
「Open API 計畫 (OAI) 的重點在於根據 Swagger 製作、改良及宣傳各供應商適用的 API 說明格式規格。」如要進一步瞭解 Open API 計畫，請參閱 https://openapis.org。

OpenAPI 規格使用標準格式來描述符合 REST 樣式的 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 用於說明 Apigee 模擬目標的 OpenAPI 規格服務，http://mocktarget.apigee.net。若需更多資訊，請參閲 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi。
在電腦上安裝 cURL，以便發出 API 呼叫建立虛擬機器或是網路瀏覽器

建立 API Proxy

Edge

如何使用 Edge UI 從 OpenAPI 規格建立 API Proxy：

登入 https://apigee.com/edge。
按一下主視窗中的 API Proxy。
您也可以依序選取「開發」>API Proxy。
按一下「+ Proxy」。
在「建立 Proxy」精靈中，按一下「反向 Proxy (最常見)」範本的「使用 OpenAPI 規格」。
按一下 [從網址匯入]，並輸入下列資訊：
- OpenAPI Spec URL：GitHub 上 OpenAPI 規格的原始內容路徑，用於「URL」欄位中的 OpenAPI 規格：
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- 規格名稱：OpenAPI 規格的名稱，例如 Mock Target。
  這個名稱是用來在規格儲存庫中儲存 OpenAPI 規格。請參閱管理規格。

按一下「匯入」。

系統隨即會顯示「Create Proxy」精靈中的「Details」(詳細資料) 頁面。這些欄位會預先填入使用 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.
點選「下一步」。
在「一般政策」頁面的「安全性：授權」下方，確認已選取「通過 (無授權)」，然後點選「下一步」：
在「流程」頁面中，確認已選取所有作業。
提示：條件式流程會自動從 OpenAPI 中 paths 物件中定義的作業規格。條件式流程會向 Edge 告知：「看到這個內容，請執行這個邏輯。」舉例來說，當 API 呼叫是 /xml 資源 (條件) 的 GET 時，將回應轉換為 JSON (透過附加至條件式流程的政策)。僅限則每次交易會執行一個流程—也就是條件評估為正確。
點選「下一步」。
在「虛擬主機」頁面中，選取「預設」和「安全」，然後按一下按一下「下一步」。
在「Summary」頁面中，確認「Test」環境為在「Optional Deployment」下方選取，然後按一下「Create and」 deploy:

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

傳統版 Edge (Private Cloud)

如何使用傳統版 Edge UI 透過 OpenAPI 規格建立 API Proxy：

登入 https://apigee.com/edge。
按一下主視窗中的 API Proxy。
您也可以依序選取「開發」>API Proxy。
按一下「+ Proxy」。
在「建立 Proxy」精靈中，依序選取「反向 Proxy (最常見)」，按一下「使用 OpenAPI」。
按一下「從網址匯入」，輸入 OpenAPI 規格名稱，然後輸入 GitHub 上 OpenAPI 的原始內容路徑「URL」欄位中的規格：

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

點選「下一步」。

系統隨即會顯示「Create Proxy」精靈中的「Details」(詳細資料) 頁面。這些欄位會預先填入使用 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 (透過附加至條件式流程的政策)。僅限則每次交易會執行一個流程—也就是條件評估為正確。
點選「下一步」。
在「安全性」頁面中，針對安全性選取「通過 (無)」選項，然後點選「Next」(下一步)。
在「Virtual Hosts」(虛擬主機) 頁面中，確認已選取所有虛擬主機，然後按一下按一下「下一步」。
在「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 政策至查看 XML 回應 您從 OpenAPI 規格。這項政策會將目標的 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 中的「查看 XML 回應條件式流程」

按一下 Mock-Target-API 右上角的「Develop」(開發) 分頁標籤 Edge UI 中的「Overview」頁面。
在左側「Navigator」窗格中的「Proxy Endpoints >」下方請按一下「資料檢視」 XML 回應條件式流程。
按一下底部「+步驟」按鈕 (與流程的 Response。

「新增步驟」對話方塊隨即開啟，其中列出所有政策的分類清單，以便您能夠選取。
捲動至「中介服務」類別，然後選取「XML 到 JSON」。
保留「Display Name」和「Display Name」的預設值。名稱：
按一下「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"}}

恭喜！您已成功測試新增至條件式流程