透過 OpenAPI 規格建立 API Proxy

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

課程內容

在本教學課程中,您會學到以下內容:

  • 透過 OpenAPI 規格建立 Edge API Proxy。
  • 使用 cURL 呼叫 API Proxy。
  • 在條件式流程中新增政策。
  • 使用 cURL 測試政策叫用。

在這個教學課程中,您將瞭解如何使用 Apigee Edge 管理 UI 透過 OpenAPI 規格建立 Edge API Proxy。您透過 HTTP 用戶端 (例如 cURL) 呼叫 API Proxy 時,API Proxy 會將要求傳送至 Apigee 模擬目標服務。

關於 Open API 計畫

開放式 API 計畫
「Open API 計畫 (OAI) 著重於根據 Swagger 規範,著重建立、改進和推廣供應商中立的 API 說明格式。」如要進一步瞭解 Open API 計畫,請參閱 https://openapis.org

OpenAPI 規格使用標準格式來描述符合 REST 樣式的 API。以 JSON 或 YAML 格式編寫的 OpenAPI 規範是機器可讀取的,但也容易讓使用者閱讀和理解。這個規範將 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

如何透過 Edge UI 從 OpenAPI 規格建立 API Proxy:

  1. 登入 https://apigee.com/edge
  2. 在主視窗中按一下「API Proxy」。

    您也可以在左側導覽列中依序選取「開發」>「API Proxy」

    按一下到達網頁上的「API Proxy」

  3. 按一下「+ Proxy」
    新增 API Proxy
  4. 在「建立 Proxy」精靈中,針對「反向 Proxy (最常用)」範本,按一下「使用 OpenAPI 規格」
    建構 Proxy 類型
  5. 按一下「從網址匯入」,然後輸入下列資訊:
    • OpenAPI Spec URL:GitHub 上的 OpenAPI 規範在「URL」欄位中原始內容的路徑:
      https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
    • Spec name:OpenAPI 規格的名稱,例如「Mock Target」

      這個名稱可用來在規格儲存庫中儲存 OpenAPI 規格。請參閱「管理規格」。

  6. 按一下「匯入」

    「建立 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
    ...
    
  7. 按照下列方式編輯「Description」欄位:API proxy for the Apigee mock target service endpoint.
  8. 按一下「Next」
  9. 在「常用政策」頁面的「安全性:授權」下方,確認已選取「通過 (無授權)」,然後按一下「下一步」

    在「通用政策」頁面上選取「通過 (無授權)」

  10. 在「流程」頁面中,確認已選取所有作業。建立 Proxy 流程
  11. 按一下「Next」
  12. 在「虛擬主機」頁面上,選取「預設」和「安全」,然後點選「下一步」
    在「Virtual Host」(虛擬主機) 頁面上選取預設和安全性 (預設選項)
  13. 在「Summary」頁面上,確認已選取「Optional Deployment」下方的「Test」環境,然後按一下「Create and deploy」

    Apigee 會建立新的 API Proxy,並部署至測試環境:

  14. 按一下「編輯 Proxy」以顯示 API Proxy 的「總覽」頁面。
    模擬目標 API Proxy 摘要

傳統邊緣 (Private Cloud)

如何透過傳統版 Edge UI 從 OpenAPI 規格建立 API Proxy:

  1. 登入 https://apigee.com/edge
  2. 在主視窗中按一下「API Proxy」。

    您也可以在左側導覽列中依序選取「開發」>「API Proxy」

  3. 按一下「+ Proxy」
    新增 API Proxy
  4. 在「建立 Proxy」精靈中,選取「反向 Proxy (最常用)」,然後按一下「使用 OpenAPI」
    建構 Proxy 類型
  5. 按一下「從網址匯入」,輸入 OpenAPI 規範的名稱,然後在「網址」欄位輸入 GitHub 上的 OpenAPI 規範原始內容路徑:

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

    「建立 Proxy」精靈的「詳細資料」頁面會隨即顯示。系統會使用 OpenAPI 規範中定義的值來預先填入欄位,如下圖所示。

    建立 Proxy 詳細資料

    下表說明使用 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
    ...
    
  8. 按照下列方式編輯「Description」欄位:API proxy for the Apigee mock target service endpoint.
  9. 按一下「Next」
  10. 在「流程」頁面中,確認已選取所有作業。建立 Proxy 流程
  11. 按一下「Next」
  12. 在「安全性」頁面中,選取「通過 (無)」做為安全性選項,然後點選「下一步」
  13. 在「Virtual Hosts」頁面中,確認您已選取所有虛擬主機,然後按一下「Next」
  14. 在「建構」頁面中,確定已選取「test」環境,然後按一下「Build and Deploy」
  15. 您會在「摘要」頁面上看到已順利建立新的 API Proxy 並部署至測試環境的確認訊息。
    建立 Proxy 摘要
  16. 按一下「Mock-Target-API」以顯示 API Proxy 的總覽頁面。
    模擬目標 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 政策中,並將在您透過 OpenAPI 規範建立 API Proxy 時自動產生的「查看 XML 回應」條件式流程裡加入。這項政策會將目標的 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 回應」條件式流程。

  1. 在 Edge UI 中,按一下 Mock-Target-API 總覽頁面右上角的「Develop」分頁標籤。
    「開發人員」分頁
  2. 在左側導覽窗格中,按一下「Proxy 端點」>「預設」下方的「查看 XML 回應」條件流程。
    選取「查看 XML 回應」
  3. 按一下與流程的 Response 相對應的底部的「+Step」按鈕。
    選取「+步驟」
    「新增步驟」對話方塊隨即開啟,並列出可新增的所有政策的分類清單。
  4. 捲動至「中介服務」類別,然後選取「從 XML 到 JSON」
    新增步驟對話方塊
  5. 保留「Display Name」和「Name」的預設值。
  6. 按一下「Add」。系統會將 XML 到 JSON 政策套用至回應。流程中的 XML 到 JSON 政策
  7. 點按「儲存」

新增政策後,請使用 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"}}

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