使用 YAML 設定 Proxy

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

您可以透過 YAML 定義 Apigee API Proxy，並使用 Google Cloud CLI 部署，不必編寫傳統的 XML Proxy 套件。您可以在稱為 Apigee 功能範本的 YAML 檔案中，說明 Proxy 的端點、路徑、政策和後端目標，Apigee 會將這些檔案編譯成標準 API Proxy 套件。

由於結果是一般的 Apigee API Proxy 套件，因此以這種方式建構的 Proxy 會在相同的 Apigee 執行階段中執行，且具有與在 Apigee UI 中或從 XML 套件建構的 Proxy 相同的政策和行為。

使用 YAML 定義 Proxy 的好處

傳統的 Apigee API Proxy 格式是 XML 檔案的 ZIP 封存檔。許多開發人員認為 YAML 比較容易閱讀、撰寫和審查，而且很適合搭配 AI 輔助和代理工具使用。Apigee 功能範本適用於：

  • 偏好簡潔宣告式格式，並希望將 Proxy 設定保留在來源控管中的 API 開發人員和架構師。
  • AI 實務人員：希望以標準化方式在模型後端前方放置 Apigee 閘道。
  • 平台和 DevOps 團隊：想要封裝可重複使用的 Proxy 設定片段，並在多個 Proxy 中一致地套用這些片段。

基本概念

Apigee 功能範本使用三種文件類型。每個檔案都是 YAML 檔案，並以 type 欄位識別。

文件類型 type 值 目的
範本 template 您部署的進入點。範本會組成一或多個功能，並定義 Proxy 的端點和路徑。
功能 feature 可重複使用的設定單元，例如驗證檢查、速率限制或後端目標，可納入範本。功能會保留政策和資源。
Proxy proxy CLI 在編譯範本及其功能時產生的完整解析 Proxy。雖然這通常是 CLI 產生的中繼輸出內容，但您也可以直接匯入 Proxy 檔案，將其翻譯成 API Proxy 套裝組合。

您會撰寫範本和功能。Apigee 會在編譯期間為您產生Proxy。

運作方式

匯入範本時，Google Cloud CLI 會在本地執行下列步驟，然後將結果上傳至 Apigee：

  1. 編譯。CLI 會讀取範本和參照的特徵檔案、合併這些檔案，然後產生單一 Proxy 定義。
  2. 轉換。CLI 會將 Proxy 定義轉換為標準 Apigee API Proxy 套件 (Apigee 預期的 XML 檔案 ZIP 檔)。
  3. 匯入。CLI 會將套件上傳至 Apigee，並建立新的 API Proxy 修訂版本。

匯入 Proxy 不會讓 Proxy 生效。您必須另外部署修訂版本至環境，就像部署任何其他 API Proxy 一樣：

YAML template + feature files
  |  gcloud beta apigee apis import --from-template
  v
API proxy revision   (created, not yet serving traffic)
  |  gcloud apigee apis deploy
  v
Deployed proxy       (serving traffic in an environment)

如需逐步操作說明，請參閱從 YAML 範本建立 API Proxy。

最簡單的範例

下列範本定義的 Proxy 會組成兩項功能，一項是新增後端目標，另一項是新增回應訊息：

gateway: apigee
schemaVersion: 1.0.0
name: HelloWorld-v1
type: template
description: API proxy for HelloWorld-v1
features:
- proxy-apigeemock.yaml
- response-helloworld.yaml

每個參照的特徵檔案都必須與範本位於同一個目錄中。如需可執行的完整範例和使用的功能檔案，請參閱「從 YAML 範本建立 API Proxy」。

建議做法

  • 在 YAML 中定義 Proxy 的端點、基本路徑、路徑、流程和後端目標。
  • 將可重複使用的政策和資源封裝為功能，並在範本中撰寫這些功能。
  • 為 Google Cloud 目標新增後端驗證 (例如 Vertex AI 後端的 Google 存取權杖)。
  • 使用 Google Cloud CLI 將範本匯入為新的 API Proxy 修訂版本，然後使用標準部署指令部署。

限制

製作範本和功能時，請注意下列事項：

  • 特徵是本機檔案。範本只能參照同一個目錄中的功能檔案。系統不支援透過網址或共用目錄參照功能。
  • 參數值會使用預設值。功能可以定義參數，但參數值會解析為功能中定義的預設值。沒有指令列旗標可在匯入時覆寫參數值。
  • 系統不支援 JSONPath 參數。使用 paths (JSONPath) 運算式的參數會導致編譯失敗。
  • 不支援測試。結構定義接受 tests 區段，但會忽略該區段，且不會納入產生的套件。
  • 結構定義十分嚴格。不明欄位會導致錯誤。僅支援 gateway: apigee 和 schemaVersion: 1.0.0。
  • 疑難排解會使用產生的 XML。Apigee UI 和執行階段會使用產生的套件。使用者介面不會來回切換至 YAML 來源。

後續步驟