API Proxy YAML 設定參考資料

本頁面適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁面說明 Apigee 功能範本的 YAML 格式:template、feature 和 proxy 文件類型及其所有欄位。如需概念簡介,請參閱「使用 YAML 設定 Proxy」。如需逐步操作說明,請參閱「從 YAML 範本建立 API Proxy」。

慣例

  • 欄位名稱使用駝峰式大小寫。例如:schemaVersion、basePath、displayName、faultRules、defaultFaultRule、httpTargetConnection。
  • 結構定義嚴格。匯入檔案時,不明欄位會導致錯誤。
  • 必填欄位。剖析檔案時,系統只會驗證 gateway 和 schemaVersion。下表中標示為「是」的其他欄位,在實際操作中也必須填寫,才能產生可運作的 API Proxy。

常見的頂層欄位

每個 template、feature 和 proxy 文件都以以下欄位開頭。

名稱 說明 預設 是否必要
gateway 目標閘道。必須為 apigee。 不適用 是
schemaVersion 文件的結構定義版本。必須為 1.0.0。 不適用 是
name 文件名稱。如果是範本或 Proxy,則為寫入套件的 API Proxy 名稱。 不適用 是
type 文件類型:template、feature 或 proxy。 不適用 是
description 人類可讀的說明。 不適用 否
priority 這個整數可控制編譯期間套用功能的順序。數字越小,越先套用。 100 否

文件類型:範本

範本是您匯入的進入點。它會組合功能,並定義 Proxy 的端點和路徑。範本不含政策或資源,這些項目來自範本參照的功能。

名稱 說明 預設 是否必要
features 要組成 Proxy 的功能檔案清單。每個項目都是特徵檔案的路徑,相對於包含範本的目錄 (例如 ./features/spike-arrest.yaml)。 [] 否
parameters 參數清單,用於設定特徵參數的值。項目的 default 會覆寫具有相同 name 的功能參數 default。請參閱參數。 [] 否
endpoints 定義基本路徑和路徑的端點清單。 [] 否
targets 定義後端連線的目標清單。 [] 否

文件類型:功能

功能是範本中可重複使用的設定單位。功能包含政策和資源,可為編譯的 Proxy 提供流程、端點和目標。除了常見的頂層欄位,地圖項目還包含下列欄位。

名稱 說明 預設 是否必要
displayName 人類可讀的顯示名稱。 不適用 否
uid 如果範本多次包含該功能,則使用專屬 ID 區分功能的政策和資源。如果功能設定了 uid,CLI 會在每項政策和資源名稱前加上 UID-,並更新相關參照。如果功能未設定 uid,CLI 會使用寫入的名稱。 不適用 否
documentation 功能的延伸說明文件。 不適用 否
categories 任意形式類別標籤清單。 [] 否
parameters 功能定義的參數清單。 [] 否
defaultEndpoint Proxy 端點:其流程和預設錯誤規則會合併至已編譯 Proxy 的每個端點。使用這個元素,將功能的政策附加至要求或回應流程。 不適用 否
defaultTarget 做為預設後端連線的Proxy 目標。 不適用 否
endpoints 要新增至 Proxy 的Proxy 端點清單。如果端點名稱與現有端點相同,則會取代現有端點。 [] 否
targets 要新增至 Proxy 的Proxy 目標清單。如果目標名稱與現有目標相同,則會取代現有目標。 [] 否
policies 功能提供的政策清單。如果特徵集設定了 uid,CLI 會在編譯期間為每個政策名稱加上 UID- 前置字元,例如 sa1-SA-SpikeArrest。否則,CLI 會使用寫入的政策名稱。 [] 否
resources 功能提供的資源清單,例如 JavaScript 或屬性檔案。 [] 否

文件類型:Proxy

Proxy 是 CLI 編譯範本及其功能時產生的完整解析文件。您通常不會直接建立這種類型,這裡之所以會說明,是因為它是 API Proxy 繫結的形式。

Proxy 的欄位與功能相同,但使用 endpoints 和 targets (而非 defaultEndpoint 或 defaultTarget),且一律代表完整、可部署的 Proxy。type為 proxy。

巢狀物件

參數

參數會為特徵提供值。功能會宣告其參數,而範本可以在自己的 parameters 清單中設定其值。CLI 編譯範本時,會按照下列方式解析各項功能參數:

  1. 如果範本的 parameters 清單中,有項目的 name 相符,且 default 不為空白,CLI 就會使用該值。如果特徵集設定 uid,範本項目的名稱必須為 FEATURE_NAME.UID.PARAMETER_NAME。
  2. 否則,CLI 會使用功能參數的 default。
  3. 如果兩者皆未設定值,參數會解析為空白字串。CLI 不會回報錯誤。

沒有指令列旗標可在匯入時設定參數值。如要變更值,請編輯範本。

名稱 說明 預設 是否必要
name 參數名稱。在功能內容中參照為 {name}。 不適用 是
displayName 人類可讀的名稱。 不適用 否
description 參數說明。 不適用 否
default 範本未設定值時,功能會使用的值。在範本中,同名特徵參數的值。CLI 會忽略空白值。CLI 會將功能字串中的 {name} 替換為解析後的值。 不適用 否
examples 範例值清單。 [] 否
maps 值替換對應。如果解析後的值是地圖中的鍵,則會替換為對應的值。 不適用 否
paths JSONPath 運算式清單。這個版本不支援:使用會導致錯誤。 不適用 否

endpoint

用於範本的 endpoints 清單。

名稱 說明 預設 是否必要
name 端點名稱。 不適用 是
basePath 用戶端用來呼叫 Proxy 的基本路徑,例如 /v1/gemini。 不適用 否
routes 路徑清單,用於將要求對應至目標。 [] 否

proxyEndpoint

用於功能的 defaultEndpoint 和 endpoints,以及已編譯的 Proxy。使用流程處理擴充端點。

名稱 說明 預設 是否必要
flows 流程清單。名為 PreFlow 或 PostFlow 的流程會對應至相應的 Apigee 流程;任何其他名稱都會放在一般流程容器中。 [] 否
postClientFlow 在回應傳送至用戶端後執行的單一流程。 不適用 否
faultRules 做為錯誤規則使用的流程清單。 [] 否
defaultFaultRule 在沒有其他錯誤規則相符時執行的錯誤規則。 不適用 否

路徑

名稱 說明 預設 是否必要
name 路徑名稱。 不適用 是
target 要轉送至的目標端點名稱。 不適用 否
condition 必須符合的條件,才能套用這項路徑。 不適用 否

心流狀態

名稱 說明 預設 是否必要
name 流程名稱。請使用 PreFlow 或 PostFlow 處理標準要求/回應流程。 不適用 是
mode Request 或 Response。決定步驟是在要求或回應中執行。 Request 否
condition 必須為 true 才能執行流程的條件。 不適用 否
steps 步驟 (政策叫用) 的排序清單。 [] 否

步驟

步驟會在流程中執行政策。

名稱 說明 預設 是否必要
name 要執行的政策名稱。在功能中,請使用政策的本機名稱,編譯器會將其重寫為命名空間名稱。 不適用 是
condition 必須符合的條件,步驟才會執行。 不適用 否

faultRule

使用一個額外欄位擴充 flow。

從流程繼承的 mode 欄位「不」適用於錯誤規則。由於錯誤規則會在要求失敗後執行,因此沒有要求或回應階段,其步驟一律會直接執行。如果您在錯誤規則上設定 mode,工具會記錄警告並忽略該欄位。

名稱 說明 預設 是否必要
alwaysEnforce 如果 true,系統一律會強制執行預設錯誤規則。 false 否

目標

用於範本的 targets 清單。

名稱 說明 預設 是否必要
name 目標名稱。由路徑的 target 參照。 不適用 是
url 後端網址。 不適用 否
auth Google Cloud 後端的驗證配置,例如 GoogleAccessToken 或 GoogleIDToken。 不適用 否
scopes 要要求的 OAuth 範圍清單。設定 auth 時適用。 [] 否
aud 權杖的目標對象。設定 auth 時適用。 不適用 否

proxyTarget

用於功能的 defaultTarget 和 targets,以及已編譯的 Proxy。使用流程處理和原始連線覆寫功能擴充目標。

名稱 說明 預設 是否必要
flows 在目標要求或回應上執行的流程清單。 [] 否
faultRules 做為錯誤規則使用的流程清單。 [] 否
defaultFaultRule 錯誤規則。 不適用 否
httpTargetConnection HTTPTargetConnection 元素的原始表示法,用於進階設定。如果設定,則優先順序高於 url、auth、scopes 和 aud。 不適用 否
localTargetConnection LocalTargetConnection 元素的原始表示法。如果設定,則優先於 HTTP 連線。 不適用 否

政策

政策是在功能中定義。其設定會寫在 content 下方,並使用「政策內容慣例」中所述的屬性/文字慣例。

名稱 說明 預設 是否必要
name 用於指定政策名稱。 不適用 是
type Apigee 政策類型,例如 VerifyAPIKey、SpikeArrest 或 Javascript。必須與 content 中的單一頂層鍵相符。 不適用 是
content 單一鍵字典,其中一個鍵等於 type。巢狀值會使用下列慣例說明政策的 XML。 {} 是

政策內容慣例

Apigee 政策為 XML。在 YAML 中,您可以使用下列規則在 content 中表示該 XML:

  • content 字典只有一個鍵,且必須與政策的 type 相符。
  • 元素屬性位於 metadata 鍵下方。
  • 元素文字會放在 _text 鍵下方。舉例來說,<Foo bar="baz">qux</Foo> 會變為 Foo: {metadata: {bar: "baz"}, _text: "qux"}。如果元素只有文字而沒有屬性,您可以直接將文字寫成值。
  • 子項元素會以巢狀結構列在標記名稱下方。重複的標記會變成清單。

舉例來說,這項功能政策:

policies:
- name: VA-VerifyAPIKey
  type: VerifyAPIKey
  content:
    VerifyAPIKey:
      metadata:
        name: VA-VerifyAPIKey
        enabled: "true"
        continueOnError: "false"
      DisplayName: VA-VerifyAPIKey
      APIKey:
        metadata:
          ref: request.header.x-api-key

會編譯成以下政策 XML:

<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey">
  <APIKey ref="request.header.x-api-key"></APIKey>
  <DisplayName>VA-VerifyAPIKey</DisplayName>
</VerifyAPIKey>

資源

資源是功能提供給套件的檔案,例如 JavaScript 檔案或屬性檔案。

名稱 說明 預設 是否必要
name 檔案名稱,例如 hello-world.js。如果功能設定了 uid,CLI 會在編譯期間為資源名稱加上 UID- 前置字元。否則,CLI 會使用所寫的名稱。 不適用 是
type 資源類型,決定套件中的子目錄,例如 jsc (JavaScript) 或 properties。 不適用 是
content 原始檔案內容。 不適用 否

這個版本不支援的欄位

  • 參數上的 paths (JSONPath)。使用這個屬性會導致編譯失敗。
  • 在任何文件上按一下 tests。系統會接受但忽略這個欄位,且不會將其納入產生的套件。

限制

生成的 API Proxy 繫結未壓縮時不得超過 10 MiB,或 256 個檔案。

後續步驟