本頁面適用於 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 編譯範本時,會按照下列方式解析各項功能參數:
- 如果範本的
parameters清單中,有項目的name相符,且default不為空白,CLI 就會使用該值。如果特徵集設定uid,範本項目的名稱必須為FEATURE_NAME.UID.PARAMETER_NAME。 - 否則,CLI 會使用功能參數的
default。 - 如果兩者皆未設定值,參數會解析為空白字串。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 個檔案。