從 YAML 範本建立 API Proxy

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

查看 Apigee Edge 說明文件。

本頁說明如何以 YAML 格式將 API Proxy 定義為 Apigee 功能範本，並透過 Google Cloud CLI 部署。您會先建構簡單的 Proxy，然後建構更完整的範例，做為 Gemini 模型的介面。

如需背景資訊，請參閱「使用 YAML 設定 Proxy」。如需完整結構定義，請參閱「API Proxy YAML 設定參考資料」。

事前準備

  • 在 Google Cloud 雲端專案中啟用 Vertex AI API，讓 Proxy 能與 Gemini 模型通訊。
    gcloud services enable aiplatform.googleapis.com
  • 安裝並初始化 Google Cloud CLI。
  • 擁有 Apigee 機構和至少一個環境。請記下機構和環境名稱；範例使用 ORG 和 ENV 做為預留位置。第 2 部分的 AI 閘道還需要中級或完整環境 (而非基本環境)；請參閱「Apigee 環境類型」。
  • 請確認您具備必要權限：
    • 如要匯入 (建立) API Proxy，您必須具備「API 管理員」角色 (roles/apigee.apiAdmin)，或具備可授予 apigee.proxies.create 的同等角色。
    • 如要部署 API Proxy，您必須在目標環境中具備環境管理員 (roles/apigee.environmentAdmin) 權限，並在專案層級具備 API 讀取者 (roles/apigee.apiReaderV2) 權限。
    • 如要建立 API 產品、開發人員和產生 API 金鑰的應用程式，請參閱第 2 部分的步驟 6：API 管理員 (roles/apigee.apiAdmin) 和開發人員管理員 (roles/apigee.developerAdmin)。如需完整角色清單，請參閱 Apigee 角色。

第 1 部分：建立簡單的 API Proxy

在本節中，您將建立 Proxy，將要求轉送至 Apigee 模擬目標服務，並強制執行速率限制。

步驟 1：建立範本

範本是您部署的檔案。這個檔案會定義 Proxy 的基本路徑、路線和後端目標，並列出要納入的功能。

為 Proxy 建立目錄，然後建立名為 hello-proxy.yaml 的檔案：

gateway: apigee
schemaVersion: 1.0.0
name: hello-proxy
type: template
description: A simple proxy to the Apigee mock target, protected by a rate limit.
features:
- spike-arrest.yaml
endpoints:
- name: default
  basePath: /hello
  routes:
  - name: default
    target: default
targets:
- name: default
  url: https://mocktarget.apigee.net

這個範本定義了：

  • 以基本路徑 /hello 做為 端點。用戶端會在這個路徑呼叫 Proxy。
  • 將要求傳送至名為 default 的目標的路徑。
  • 指向後端網址的目標。
  • 功能 (spike-arrest.yaml)，您將在下一個步驟中建立。

步驟 2：建立功能

功能是可重複使用的設定單元，內含政策。範本無法直接包含政策，因此速率限制政策位於功能中。

在範本所在的目錄中，建立名為 spike-arrest.yaml 的檔案：

gateway: apigee
schemaVersion: 1.0.0
name: spike-arrest
displayName: Spike Arrest
type: feature
description: Protects the backend by smoothing traffic spikes.
categories:
- traffic
parameters:
- name: RATE
  displayName: RATE
  description: Maximum request rate, for example 30ps (per second) or 100pm (per minute).
  default: 30ps
  examples:
  - 30ps
  - 100pm
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: SA-SpikeArrest
policies:
- name: SA-SpikeArrest
  type: SpikeArrest
  content:
    SpikeArrest:
      metadata:
        name: SA-SpikeArrest
        enabled: "true"
        continueOnError: "false"
      DisplayName: SA-SpikeArrest
      Rate: "{RATE}"

這項功能：

  • 定義限制要求頻率的 SpikeArrest 政策。
  • 使用 defaultEndpoint.flows 將政策新增至要求 PreFlow，以便在每個要求上執行。
  • 宣告參數 RATE，當編譯 Proxy 時，系統會將預設值 (30ps) 替換為 {RATE}。

步驟 3：匯入 Proxy

匯入範本，建立 API Proxy 修訂版本。在含有檔案的目錄中執行下列指令：

gcloud apigee apis import hello-proxy \
    --from-template=hello-proxy.yaml \
    --organization=ORG

CLI 會將範本及其功能編譯為 API Proxy 套件、上傳，並列印新的 Proxy 修訂版本。匯入會建立修訂版本，但不會部署。

步驟 4：部署 Proxy

將修訂版本部署至環境：

gcloud apigee apis deploy \
    --api=hello-proxy \
    --environment=ENV \
    --organization=ORG

根據預設，這項指令會部署最新修訂版本。如要部署特定修訂版本，請將其編號做為第一個引數傳遞，例如 gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV。如果已在相同基本路徑部署其他 Proxy，請新增 --override 以取代該 Proxy，且不會發生停機情形。

步驟 5：呼叫 Proxy

如要透過網路呼叫已部署的 Proxy，您的環境必須附加至具有可路由主機名稱的環境群組。如果您剛建立機構，請先確認已完成設定，再呼叫 Proxy；詳情請參閱「關於環境和環境群組」。

找出包含環境的環境群組主機名稱：

  1. 在 Google Cloud 控制台中，依序前往「Apigee」「管理」「環境」。
  2. 選取「環境群組」分頁標籤。
  3. 找出包含環境的環境群組，然後從「主機名稱」欄複製值。

使用範本中的基本路徑，在該主機名稱呼叫 Proxy：

curl https://HOSTNAME/hello

將 HOSTNAME 替換為您複製的主機名稱。成功的回應來自模擬目標服務。

第 2 部分：為 Gemini 建立 AI 閘道

本節將建構更完整的 Proxy：AI 閘道，可將要求轉送至 Vertex AI 上的 Gemini 模型、強制執行速率限制，並要求提供 API 金鑰。這項範例會使用一個範本、三項功能和一個服務帳戶。

與第 1 部分中的簡單 Proxy 不同，這個 Proxy 會呼叫 Google Cloud 服務 (Vertex AI)。gemini-target 功能會使用 auth: GoogleAccessToken，因此 Apigee 會將 Google OAuth 權杖附加至對 Vertex AI 的每個要求。該權杖是為您建立的服務帳戶核發，並在部署 Proxy 時提供，因此這部分會新增建立該服務帳戶的步驟 (步驟 3)。

步驟 1：建立範本

建立名為 ai-gateway.yaml 的檔案：

gateway: apigee
schemaVersion: 1.0.0
name: ai-gateway
type: template
description: AI gateway that fronts a Gemini model with throttling and API key enforcement.
features:
- spike-arrest.yaml
- verify-api-key.yaml
- gemini-target.yaml
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

步驟 2：建立功能

在同一個目錄中，建立三個功能檔案。

重複使用第 1 部分的 spike-arrest.yaml 功能。

建立 verify-api-key.yaml，在 x-api-key 標頭中要求 API 金鑰：

gateway: apigee
schemaVersion: 1.0.0
name: verify-api-key
displayName: Verify API Key
type: feature
description: Requires a valid API key in the x-api-key request header.
categories:
- security
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: VA-VerifyAPIKey
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

建立 gemini-target.yaml，以透過 Google 存取權杖驗證，然後將要求傳送至 Gemini 模型：

gateway: apigee
schemaVersion: 1.0.0
name: gemini-target
displayName: Gemini Target
type: feature
description: Routes requests to a Gemini model on Vertex AI, authenticated with a Google access token.
categories:
- llm
targets:
- name: gemini
  url: https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent
  auth: GoogleAccessToken
  scopes:
  - https://www.googleapis.com/auth/cloud-platform

將 PROJECT_ID 替換為您的 Google Cloud 雲端專案 ID，並將 REGION 替換為您使用的 Vertex AI 區域 (例如 us-central1)。這項功能會使用 auth: GoogleAccessToken，因此 Apigee 會將 Google 存取權杖附加至對 Vertex AI 的每個要求。

模型並非在所有地區都適用，網址會因您使用的地區而異。上述網址是區域表單，適用於從特定區域 (例如 us-central1 中的 gemini-2.5-flash) 放送的模型。其他模型只會透過全域端點提供，該端點使用不同的主機和 locations/global：

  url: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL:generateContent

如要查看模型支援的服務地區，請參閱「Vertex AI 生成式 AI 服務地區」。

步驟 3：為 Proxy 建立服務帳戶

由於 gemini-target 功能使用 auth: GoogleAccessToken，部署的 Proxy 會以服務帳戶身分呼叫 Vertex AI。建立該服務帳戶，授予 Vertex AI 存取權，並允許 Apigee 服務代理程式使用該帳戶。在步驟 5 中部署 Proxy 時，您會提供這個服務帳戶。詳情請參閱「使用 Google 驗證」。

  1. 在與 Apigee 機構相同的 Google Cloud 專案中，建立使用者管理的服務帳戶。(系統不接受 Compute Engine 預設服務帳戶)。如要瞭解其他建立方式，請參閱「建立及管理服務帳戶」。
    gcloud iam service-accounts create SA_NAME \
    --project=PROJECT_ID \
    --display-name="Apigee AI gateway"

    這會建立服務帳戶 SA_NAME@PROJECT_ID.iam.gserviceaccount.com。

  2. 授予服務帳戶存取權，允許呼叫後端。如要以 Vertex AI 為目標，請授予 Vertex AI 使用者角色 (roles/aiplatform.user)： 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

    如果專案的 IAM 政策已包含條件式角色繫結，請將 --condition=None 新增至這個指令。

  3. 將服務帳戶的服務帳戶權杖建立者角色 (roles/iam.serviceAccountTokenCreator) 授予 Apigee 服務代理，允許該代理為服務帳戶產生權杖： 
    gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --project=PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    如要找出 PROJECT_NUMBER，請執行 gcloud projects describe PROJECT_ID --format='value(projectNumber)'。

步驟 4：匯入 Proxy

匯入範本，建立 API Proxy 修訂版本：

gcloud apigee apis import ai-gateway \
    --from-template=ai-gateway.yaml \
    --organization=ORG

請記下指令輸出內容中的修訂版本號碼，您會在步驟 5 中用到。如要只列印修訂版本號碼，請在匯入指令中加入 --format="value(revision)"。

步驟 5：使用服務帳戶部署 Proxy

部署 AI 閘道與第 1 部分中的簡單 Proxy 有兩項差異：

  • 您必須提供在步驟 3 建立的服務帳戶。如果部署時缺少其中一個，部署作業就會失敗，並顯示 MISSING_SERVICE_ACCOUNT 錯誤。
  • 您必須部署至中繼或全方位環境。 這個 Proxy 使用可擴充的政策，但「Base」環境不支援這類政策，因此部署至該環境會失敗，並顯示「Extensible proxy can not be deployed to a base environment」(可擴充的 Proxy 無法部署至 Base 環境) 錯誤訊息。請參閱「Apigee 環境類型」。

Apigee 使用者介面：部署 Proxy，並在系統提示輸入服務帳戶時，輸入 SA_NAME@PROJECT_ID.iam.gserviceaccount.com。如需相關步驟，請參閱「部署 API Proxy」。

Deployment API：呼叫 deployments API，並將服務帳戶做為 serviceAccount 查詢 參數傳遞。將 REVISION 替換為步驟 4 中的修訂版本號碼：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com"

部署要求會立即傳回，部署作業則為非同步。輪詢修訂版本的部署狀態，直到狀態變成 READY 為止，系統會回報 PROGRESSING：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments"

編譯 Proxy 時，spike-arrest 和 verify-api-key 功能會將政策新增至要求 PreFlow (先是速率限制，然後是 API 金鑰檢查)，而 gemini-target 功能則會新增 Vertex AI 後端。部署完成後，Proxy 會以服務帳戶的身分向 Vertex AI 驗證。

步驟 6：取得 API 金鑰

verify-api-key 功能會拒絕任何未攜帶有效 API 金鑰的要求，因此您必須先取得金鑰，才能呼叫 Proxy。API 金鑰是與含有這個 Proxy 的 API 產品相關聯的開發人員應用程式憑證。完成下列工作 (詳情請參閱「發布總覽」)：

  1. 建立 API 產品，其中包含 ai-gateway Proxy 和您部署 Proxy 的環境。
  2. 註冊應用程式開發人員。
  3. 註冊與該 API 產品相關聯的開發人員應用程式。

註冊應用程式後，系統就會產生金鑰。如要擷取這項資訊，請參閱「查看 API 金鑰和密鑰」。

步驟 7：呼叫 Proxy

如要找出環境群組的主機名稱，請按照第 1 部分的步驟 5操作，然後在基本路徑 /v1/gemini 中呼叫 Proxy。在 x-api-key 標頭中傳遞 API 金鑰，並傳送 Gemini generateContent 要求主體：

curl -X POST https://HOSTNAME/v1/gemini \
    -H "x-api-key: API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'

將 HOSTNAME 替換為環境群組主機名稱，並將 API_KEY 替換為步驟 6 中的金鑰。成功的回覆是模型的 JSON 輸出內容。如果省略金鑰，VerifyAPIKey 政策會傳回授權失敗訊息，確認 verify-api-key 功能已生效。如要瞭解其他傳遞金鑰的方式，請參閱「提交含有有效 API 金鑰的要求」。

後續步驟