使用 OpenAPI 規格建立 API Proxy

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

課程內容

在本教學課程中，您將學習：

• 使用 OpenAPI 規格建立 Apigee API Proxy。
• 使用 cURL 呼叫 API Proxy。
• 在條件式流程中加入政策。
• 使用 cURL 測試政策叫用作業。

您將瞭解如何使用 Apigee UI，根據 OpenAPI 規格建立 Apigee API Proxy。當您使用 HTTP 用戶端 (例如 cURL) 呼叫 API Proxy 時，API Proxy 會將要求傳送至 Apigee 模擬目標服務。

關於開放 API 計畫

「Open API Initiative (OAI) 專注於根據 Swagger 規範，建立、改進及推廣供應商中立的 API 說明格式。」如要進一步瞭解 Open API 計畫，請參閱 OpenAPI 規格。

OpenAPI 規格使用標準格式說明 RESTful API。OpenAPI 規格採用 JSON 或 YAML 格式編寫，可供機器讀取，但也便於人類閱讀和理解。規格說明會描述 API 的各個元素，例如基本路徑、路徑和動詞、標頭、查詢參數、作業、內容類型、回應說明等。此外，OpenAPI 規格通常用於產生 API 說明文件。

關於 Apigee 模擬目標服務

本教學課程中使用的 Apigee 模擬目標服務由 Apigee 代管，並傳回簡單資料。不需要 API 金鑰或存取權杖。事實上，您可以透過網路瀏覽器存取這項功能。請點選下列按鈕試用：

http://mocktarget.apigee.net

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

如要瞭解模擬目標服務支援的完整 API 集合，請參閱 Apigee 範例 API

事前準備

• 開始前，請務必完成 總覽和先決條件中的步驟。
• OpenAPI 規格。在本教學課程中，您將使用 mocktarget.yaml OpenAPI 規格，該規格說明 Apigee 的模擬目標服務 http://mocktarget.apigee.net。詳情請參閱 apigee/api-platform-samples。
• 在電腦上安裝 cURL，以便透過指令列或網路瀏覽器發出 API 呼叫。

建立 API Proxy

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

1. 如果您使用的是 Cloud 控制台中的 Apigee UI：請依序選取「Proxy development」>「API Proxies」。

   如果您使用的是傳統 Apigee UI：請依序選取「Develop」>「API Proxies」，然後在「Proxies」窗格中選取 Proxy 的環境。

2. 按一下主視窗中的「API Proxy」。

   或者，您也可以在左側導覽列中依序選取「Develop」>「API Proxies」。

   

3. 按一下「建立新項目」。

   

4. 在「建立 Proxy」精靈中，按一下「反向 Proxy (最常見)」範本的「使用 OpenAPI 規格」。

   
5. 按一下「網址」，然後輸入下列資訊：

   OpenAPI 規格網址：GitHub 上 OpenAPI 規格的原始內容路徑，請填入「網址」欄位：

   https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml

6. 按一下「選取」。

   「Create Proxy」精靈的「Proxy details」頁面隨即顯示。這些欄位會使用 OpenAPI 規格中定義的值預先填入，如以下圖所示：

   

   下表說明使用 OpenAPI 規範預先填入的預設值：

   欄位	說明	預設
   名稱	API Proxy 的名稱。例如 Mock-Target-API。	OpenAPI 規格的 title 屬性，其中空格已替換為破折號
   基本路徑	路徑元件，可用於在機構內唯一識別此 API 代理程式。這個 API Proxy 的公開網址由外部或內部網域名稱和這個基礎路徑組成。例如： http://apitest.acme.com/mock-target-api	Name 欄位內容已轉換為全小寫
   說明	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
   ...
   

7. 在「Proxy details」(Proxy 詳細資料) 頁面中，按照以下說明編輯「Description」欄位：

   API proxy for the Apigee mock target service endpoint.

8. 點按「Next」。
9. 在「Common policies」頁面的「Security: Authorization」下方，確認已選取「Pass through (no authorization)」，然後按一下「Next」：

   

10. 在「流程」頁面上，確認已選取所有作業。
    提示：系統會根據 OpenAPI 規格中 paths 物件中定義的作業，自動產生條件式流程。條件式流程會告訴 Apigee：「當您看到這個時，請執行這個邏輯。」舉例來說，如果 API 呼叫是 /xml 資源上的 GET (條件)，請將回應轉換為 JSON (透過附加至條件式流程的政策)。每筆交易只會執行一個流程，也就是條件評估為 true 的第一個流程。
    
11. 點按「Next」。
12. 在「Summary」頁面中，確認已選取「Optional Deployment」下方的環境，然後按一下「Create and deploy」：

    

    Apigee 會建立新的 API Proxy，並部署至您的環境：

13. 按一下「編輯 Proxy」，即可顯示 API Proxy 的「總覽」頁面。

恭喜！您已使用 OpenAPI 規格建立 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!

做得好！您已根據 OpenAPI 規格建構簡單的 API Proxy，並進行測試。

新增 XML 到 JSON 政策

接下來，您將在 View XML Response 中加入 XML 到 JSON 政策，這是在您根據 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 代理程式中的「View XML Response」條件流程。

注意：Apigee 推出了新版 Proxy 編輯器，可讓您更輕鬆地管理 Proxy。

下方前兩個分頁中的操作說明，分別說明如何使用新版 Proxy 編輯器或傳統 Proxy 編輯器。

全新 Proxy 編輯器傳統 Proxy 編輯器 更多選項

1. 在 Apigee UI 的「Mock-Target-API Overview」頁面中，按一下「Develop」分頁標籤。



2. 在左側窗格中，依序點選「Proxy Endpoints」>「default」下方的「View XML Response」條件式流程。
3. 在左側窗格中，按一下「政策」列中的「+」按鈕。

4. 在「Create policy」對話方塊中，點選「Select policy type」欄位，向下捲動至「Mediation」，然後選取「XMLToJSON」。請保留「Display Name」和「Name」的預設值。

5. 按一下「建立」，建立政策。

6. 在「Response」中，按一下「View XML response」流程旁邊的「+」按鈕。

   

7. 在「Add Policy Step」對話方塊中，按一下「Select existing policy」欄位，然後選取「XML to JSON-1」。

8. 按一下「Add」(新增)。系統會將 XML 轉 JSON 政策套用至回應。

   

   如要查看「View XML Response」條件式流程的程式碼，請按一下「Switch To Code Editor」。

9. 按一下 [儲存]。

1. 在 Apigee UI 的「Mock-Target-API Overview」頁面中，按一下「Develop」分頁標籤。

   

2. 在左側的導覽器窗格中，依序點選「Proxy Endpoints」>「default」下方的「View XML Response」條件式流程。

   

3. 按一下底部的「+Step」按鈕，對應流程的「Response」。

   

   「Add Step」對話方塊隨即開啟，並列出可新增的所有政策，並依類別分類。

4. 捲動至「中介服務」類別，然後選取「從 XML 轉換為 JSON」。

   
5. 請保留「Display Name」和「Name」的預設值。

6. 按一下「Add」(新增)。系統會將 XML 轉換為 JSON 政策套用至回應。

   
7. 按一下 [儲存]。

政策已新增完成，請使用 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"}}

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