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 的功能檔案名稱清單。每個名稱都必須解析為範本相同目錄中的檔案。 [] 否
parameters 參數值清單，可為功能提供預設值。 [] 否
endpoints 定義基本路徑和路徑的端點清單。 [] 否
targets 定義後端連線的目標清單。 [] 否

文件類型：功能

功能是可重複使用的設定單元，可納入範本中。 功能會保留政策和資源，並可將流程、端點和目標提供給已編譯的 Proxy。除了一般頂層欄位外，功能還包含下列欄位。

名稱 說明 預設 是否必要
displayName 使用者可理解的顯示名稱。 不適用 否
uid 用來為功能政策和資源設定命名空間的專屬 ID。如未設定，則會使用 name。 不適用 否
documentation 擴充這項功能的說明文件。 不適用 否
categories 任意形式的類別標籤清單。 [] 否
parameters 這項功能定義的參數清單。 [] 否
defaultEndpoint Proxy 端點：流程和預設錯誤規則會合併至已編譯 Proxy 的每個端點。使用這個方法，將功能的政策附加至要求或回應流程。 不適用 否
defaultTarget 做為預設後端連線的Proxy 目標。 不適用 否
endpoints 要新增至 Proxy 的Proxy 端點清單。如果現有端點的名稱相同，系統會予以取代。 [] 否
targets 要新增至 Proxy 的Proxy 目標清單。如果目標名稱與現有目標相同，系統會取代現有目標。 [] 否
policies 這項功能提供的政策清單。編譯期間，政策名稱會自動加上功能的前置字串 uid (或 name)。 [] 否
resources 這項功能提供的資源清單，例如 JavaScript 或屬性檔案。 [] 否

文件類型：委任書

當 CLI 使用範本及其功能編譯時，會產生完全解析的文件，即為 Proxy。您通常不會直接編寫這類內容，但這裡會說明，因為這是 API Proxy 套件的形狀。

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

巢狀物件

參數

參數會為特徵提供值。參數值會解析為其 default。

名稱 說明 預設 是否必要
name 參數名稱。在功能內容中參照為 {name}。 不適用 是
displayName 使用者可解讀的名稱。 不適用 否
description 參數說明。 不適用 否
default 預設值。取代功能字串中的 {name}。 不適用 否
examples 範例值清單。 [] 否
maps 值替換對應。如果解析後的值是對應中的鍵，則會替換為對應的值。 不適用 否
paths JSONPath 運算式清單。這個版本不支援，使用時會導致錯誤。 不適用 否

endpoint

用於範本的 endpoints 清單。

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

proxyEndpoint

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

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

路徑

名稱 說明 預設 是否必要
name 路線名稱。 不適用 是
target 要將流量轉送至的目標端點名稱。 不適用 否
condition 這個條件必須為 true，系統才會套用這個路徑。 不適用 否

心流狀態

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

步驟

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

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

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。使用流程處理和原始連線覆寫，擴充 target。

名稱 說明 預設 是否必要
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 中，您會以這些規則表示 XML content：

  • 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 (或 name)。 不適用 是
type 資源類型，決定套件中的子目錄，例如 jsc (JavaScript) 或 properties。 不適用 是
content 原始檔案內容。 不適用 否

此版本不支援的欄位

  • paths 參數 (JSONPath)。使用這個函式會導致編譯失敗。
  • tests 任何文件。系統會接受這個欄位，但會忽略該欄位，且不會將其納入產生的套件組合。

限制

產生的 API Proxy 套件不得超過 10 MiB (未壓縮) 或 256 個檔案。

後續步驟