本頁面由 Cloud Translation API 翻譯而成。

開始使用 Apigee Extension Processor

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

查看 Apigee Edge 說明文件。

本頁說明如何設定 Apigee 擴充功能處理器，透過啟用 Service Extensions 的負載平衡器，對 API 流量強制執行 API 政策。

如要進一步瞭解建議用途，以及使用 Apigee Extension Processor 進行 API 管理的好處，請參閱 Apigee Extension Processor 總覽。

Apigee Extension Processor 是一種流量擴充功能 (Service Extension 的類型)，可讓您使用 Cloud Load Balancing，從應用程式負載平衡器的資料處理路徑將呼叫傳送至 Apigee Extension Processor。設定負載平衡器和流量擴充功能後，API 流量就會由負載平衡器處理。Apigee 擴充功能處理器中的政策會套用至使用流量擴充功能呼叫的 API 流量。

以下各節將逐步說明如何設定 Apigee 擴充功能處理器的重要元素：

為後端服務設定負載平衡器。
設定 Apigee 擴充功能處理器。
設定流量擴充功能。
使用 Extension Processor 搭配政策。

事前準備

開始設定 Apigee 擴充功能處理器前，請先完成下列工作：

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, and Network Services APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, and Network Services APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

安裝 Google Cloud CLI。

安裝 Google Cloud CLI 後，請執行 gcloud components update 指令，取得最新版 gcloud 元件。
如果尚未這麼做，請使用 1-15-0-apigee-2 以上版本佈建 Apigee 執行個體。
在 Google Cloud 控制台的 Apigee UI 中，前往「執行個體詳細資料」頁面，即可查看執行個體版本。前往 Google Cloud 控制台的「Instances」(執行個體) 頁面，選取執行個體並查看詳細資料：
前往「Instances」(執行個體)

您可以在訂閱或Pay-as-you-go Apigee 組織中使用擴充功能處理器。如果不確定自己使用的是訂閱型還是即付即用型 Apigee 機構，請與 Apigee 機構管理員聯絡。如要進一步瞭解如何佈建付費 Apigee 執行個體，請參閱「事前準備」一文。
確認您要在使用的 Apigee 執行個體中啟用 VPC 和子網路。前往 Google Cloud 控制台的「VPC Networks」(虛擬私有雲網路) 頁面：
前往「VPC Networks」(虛擬私有雲網路) 頁面

必要的角色

如要取得安裝 Apigee 擴充功能處理器所需的權限，請要求管理員授予您下列 IAM 角色：

建立及管理服務帳戶：機構的服務帳戶管理員 (roles/iam.serviceAccountAdmin)
建立及管理服務擴充功能： Service Extensions 管理員 (roles/networkservices.serviceExtensionsAdmin) (機構)
建立及管理網路端點群組 (NEG)： Compute 執行個體管理員 (roles/compute.instanceAdmin) (適用於機構)
建立及管理網路資源：機構的 Compute 網路管理員 (roles/compute.networkAdmin)
建立及管理後端服務：機構的 Compute 負載平衡器管理員 (roles/compute.loadBalancerAdmin)
建立及管理 Apigee 資源：機構的 Apigee 機構管理員 (roles/apigee.admin)
建立及管理流量擴充功能：機構的 Apigee APIM 服務擴充功能管理員 (roles/apigee.apimServiceExtensionAdmin)
查看流量擴充功能：組織的「Apigee APIM 服務擴充功能檢視者」 (roles/apigee.apimServiceExtensionViewer)
管理長時間執行的作業： Apigee APIM 服務擴充功能服務代理 (roles/apigee.apimServiceExtensionServiceAgent) 在 Google Cloud 專案中，服務代理的

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

設定環境變數

在包含 Apigee 執行個體的 Google Cloud 專案中，使用下列指令設定環境變數：

export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET

其中：

PROJECT_ID 是 Apigee 執行個體所屬專案的 ID。
REGION 是 Apigee 執行個體的 Google Cloud 區域。
INSTANCE 是 Apigee 執行個體的名稱。
VPC_NETWORK_NAME 是 Google Cloud 專案中虛擬私有雲網路的名稱，您要用於 Apigee 擴充功能處理器。
SUBNET 是您要用於 Apigee 擴充功能處理器的 Google Cloud 專案中子網路的名稱。

如要確認環境變數是否設定正確，請執行下列指令並檢查輸出內容：

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET

設定驗證權杖

如要設定驗證權杖，請執行下列指令：

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

為後端服務設定負載平衡器

以下各節說明如何為後端服務設定全域外部應用程式負載平衡器，並以 httpbin.org 為例：

建立全域外部應用程式負載平衡器。
建立網路端點群組 (NEG)。
建立後端服務。
建立網址對應。
建立目標 Proxy。
建立通用轉送規則。

建立全域外部應用程式負載平衡器

如要建立負載平衡器：

將 gcloud 設定為使用目前的專案：
```
gcloud config set project PROJECT_ID
```
其中 PROJECT_ID 是 Apigee 執行個體所屬專案的 ID。
建立全域靜態 IP 位址：
```
gcloud compute addresses create IP_ADDRESS --ip-version=IPV4 --global
```
其中 IP_ADDRESS 是您要建立的 IP 位址名稱。名稱必須符合規則運算式 (?:a-z?)。
取得 IP 位址並儲存為環境變數：
```
IP=$(gcloud compute addresses describe IP_ADDRESS --format="get(address)" --global)
```
其中 IP_ADDRESS 是您在上一個步驟中建立的 IP 位址名稱。
為 nip.io 建立 TLS 憑證，這項第三方服務會提供 IP 位址的萬用字元 DNS 記錄：
```
gcloud compute ssl-certificates create SSL_CERT_NAME \
  --domains="nip.io"
```
其中 SSL_CERT_NAME 是要建立的憑證名稱。

建立網路端點群組 (NEG)

為負載平衡器建立網路端點群組 (NEG)：

建立 NEG：

gcloud compute network-endpoint-groups create NEG_NAME \
  --network-endpoint-type=INTERNET_FQDN_PORT \
  --default-port=443 \
  --global

其中 NEG_NAME 是要建立的 NEG 名稱。

將 httpbin.org 的端點新增至 NEG：

gcloud compute network-endpoint-groups update NEG_NAME \
  --add-endpoint=fqdn=httpbin.org,port=443 \
  --global

其中 NEG_NAME 是您在上一個步驟中建立的 NEG 名稱。

建立後端服務

如要建立負載平衡器公開的後端服務，請執行下列操作：

建立後端服務：

gcloud compute backend-services create BACKEND_SERVICE_NAME \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --protocol=HTTPS \
  --global

將 BACKEND_SERVICE_NAME 替換為要建立的後端服務名稱。

將 NEG 新增至後端：

gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
  --network-endpoint-group=NEG_NAME \
  --global-network-endpoint-group \
  --global

其中：

BACKEND_SERVICE_NAME 是您在上一個步驟中建立的後端服務名稱。
NEG_NAME 是您在先前步驟中建立的 NEG 名稱。

建立網址對應

如要在負載平衡器和後端服務之間建立網址對應，請使用下列指令：

gcloud compute url-maps create URL_MAP_NAME \
  --default-service BACKEND_SERVICE_NAME \
  --global

其中：

URL_MAP_NAME 是您要建立的網址對應名稱。
BACKEND_SERVICE_NAME 是您在先前步驟中建立的後端服務名稱。

建立目標 Proxy

如要建立目標 Proxy，供負載平衡器處理服務擴充功能流量，請使用下列指令：

gcloud compute target-https-proxies create TARGET_PROXY_NAME \
  --global \
  --ssl-certificates SSL_CERT_NAME \
  --global-ssl-certificates \
  --url-map URL_MAP_NAME \
  --global-url-map

其中：

TARGET_PROXY_NAME 是您要建立的目標 Proxy 名稱。
URL_MAP_NAME 是您在前一個步驟建立的網址對應表名稱。
SSL_CERT_NAME 是您在前一個步驟中為 nip.io 建立的 SSL 憑證名稱。

建立通用轉送規則

如要為負載平衡器建立全域轉送規則，請使用下列指令：

gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --network-tier=PREMIUM \
  --address=IP_ADDRESS \
  --target-https-proxy=TARGET_PROXY_NAME \
  --ports=443 \
  --global

其中：

FORWARDING_RULE_NAME 是您要建立的轉送規則名稱。
IP_ADDRESS 是您在先前步驟中建立的 NEG 端點 IP 位址名稱。
TARGET_PROXY_NAME 是處理擴充功能流量的目標 Proxy 名稱。

設定 Apigee 擴充功能處理器

以下各節說明如何設定 Apigee 擴充功能處理器：

建立 Apigee 環境。
建立擴充功能處理器 Proxy。

建立 Apigee 環境

使用下列指令建立 Apigee 環境：

curl -i -X POST -H  "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments" -H "Content-Type:application/json" -d \
    '{
        "name": "ENV_NAME",
        "displayName": "ENV_NAME",
        "state": "ACTIVE",
        "deploymentType": "PROXY",
        "apiProxyType": "PROGRAMMABLE",
        "type": "COMPREHENSIVE",
        "properties":
        {"property": [
            {
            "name": "apigee-service-extension-enabled",
            "value": "true"
            }
          ]
        }
    }'

其中 ENV_NAME 是您要建立的環境名稱。名稱長度須介於 2 至 32 個字元，且只能使用小寫英文字母、數字或連字號。名稱開頭須為英文字母，結尾不得為連字號。名稱不得與貴機構中的任何其他環境名稱相同。

確認環境已建立：

curl -i -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments"

環境清單應包含您剛建立的環境。

將新建立的環境連結至 Apigee 執行個體：

curl -i -X POST -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances/$INSTANCE/attachments" -H "Content-Type:application/json" -d \
    '{
        "environment": "ENV_NAME"
        }'

其中 ENV_NAME 是您在上一個步驟中建立的環境名稱。

這項作業最多可能需要 10 分鐘。

建立 Apigee 環境群組：

curl -H "Authorization: Bearer $TOKEN" -X POST \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups" -H "Content-Type:application/json" -d \
    '{
        "name": "ENV_GROUP_NAME",
        "hostnames": ["ENV_GROUP_HOSTNAME"]
        }'

其中：

ENV_GROUP_NAME 是您要建立的環境群組名稱。
ENV_GROUP_HOSTNAME 是您要建立的環境群組主機名稱。主機名稱必須是完整網域名稱 (FQDN)。
注意：主機名稱不必可解析。

將新環境連結至新環境群組：

curl -H "Authorization: Bearer $TOKEN" -X POST\
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups/ENV_GROUP_NAME/attachments" -H "content-type:application/json" -d \
        '{
            "name": "ENV_GROUP_NAME",
            "environment": "ENV_NAME"
        }'

其中：

ENV_GROUP_NAME 是您要建立的環境群組名稱。
ENV_NAME 是您在先前步驟中建立的環境名稱。

建立擴充功能處理器 Proxy

擴充功能處理器 Proxy 是 Apigee API Proxy，用於對負載平衡器流量套用 API 管理政策。您可以建立無目標 Proxy，或啟用伺服器傳送事件 (SSE) 的 Proxy。如要進一步瞭解如何搭配使用 SSE 與 Apigee，請參閱「伺服器傳送事件」。

如要建立 Apigee API Proxy，以便搭配擴充功能處理器負載平衡器使用，請按照下列步驟操作：

沒有目標 Proxy

請按照「建立 API Proxy」一文中的步驟，建立具有下列規格的無目標 Proxy：

Proxy 範本：選取「No target」。
Proxy 名稱：輸入 Proxy 名稱。這個名稱會做為擴充功能處理器的 ID。
基本路徑：設定所需的基本路徑。系統不會使用該路徑。

Proxy 的 XML 規格應如下所示：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<APIProxy revision="1" name="extproc-sample">
    <DisplayName/>
    <Description/>
    <CreatedAt>1739581781912</CreatedAt>
    <LastModifiedAt>1739582447868</LastModifiedAt>
    <BasePaths>/</BasePaths>
    <Policies></Policies>
    <ProxyEndpoints>
        <ProxyEndpoint>default</ProxyEndpoint>
    </ProxyEndpoints>
</APIProxy>

按照「部署 API Proxy」一文中的步驟，將 Proxy 部署至您先前建立的環境。

支援 SSE 的 Proxy

請按照「建立 API Proxy」一文中的步驟，建立具有下列規格的伺服器傳送事件 Proxy：

Proxy 範本：選取「No target」。
Proxy 名稱：輸入 Proxy 名稱。
基本路徑：設定所需的基本路徑。系統不會使用該路徑。

Proxy 的 XML 規格應如下所示：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<APIProxy revision="1" name="extproc-sample">
    <DisplayName/>
    <Description/>
    <CreatedAt>1739581781912</CreatedAt>
    <LastModifiedAt>1739582447868</LastModifiedAt>
    <BasePaths>/</BasePaths>
    <ProxyEndpoints>
        <ProxyEndpoint>default</ProxyEndpoint>
    </ProxyEndpoints>
</APIProxy>

在 Proxy 中設定 EventFlow：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<APIProxy revision="1" name="extproc-sample">
    <DisplayName/>
    <Description/>
    <CreatedAt>1739581781912</CreatedAt>
    <LastModifiedAt>1739582447868</LastModifiedAt>
    <BasePaths>/</BasePaths>
    <ProxyEndpoints>
        <ProxyEndpoint>default</ProxyEndpoint>
        <EventFlow name="EventFlow" content-type="text/event-stream">
          <Response/>
        </EventFlow>
        <HTTPProxyConnection>
          <Properties/>
          <URL>https://httpbin.org/sse</URL>
        </HTTPProxyConnection>
    </ProxyEndpoints>
</APIProxy>

按照「部署 API Proxy」一文中的步驟，將 Proxy 部署至您先前建立的環境。

設定流量擴充功能

本節說明如何使用下列步驟，為擴充功能處理器設定流量服務擴充功能：

使用擴充功能處理器佈建 API 建立流量擴充功能。
將要求傳送至負載平衡器。

使用 Extension Processor 佈建 API 建立流量擴充功能

在這個步驟中，請使用 Extension Processor 佈建 API，為 Extension Processor 建立流量服務擴充功能。

使用下列指令呼叫 Extension Processor 佈建 API，建立流量擴充功能：

curl -X POST -H  "Authorization: Bearer $TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions?apimServiceExtensionId=TRAFFIC_EXT_NAME \
    -H "Content-Type:application/json" -d \
    '{
      "extensionProcessor": "TARGET_PROXY_NAME"
      "lbForwardingRule": "LB_FORWARDING_RULE",
      "network" : "NETWORK",
      "networkConfigs": [
        {
          "region": "$REGION",
          "subnet": "project/my-project/regions/$REGION/subnetworks/$SUBNET"
        }
      ],
      "extensions": [
        {
          "name": "TARGET_PROXY_NAME",
          "matchCondition": "CEL_EXPRESSION",
          "failOpen": FAIL_OPEN,
          "hostname": "ENV_GROUP_HOSTNAME",
          "supportedEvents": [
            "REQUEST_HEADERS",
            "RESPONSE_HEADERS"
          ]
        }
      ]
    }'

其中：

TRAFFIC_EXT_NAME 是您要建立的流量擴充功能名稱。
LB_FORWARDING_RULE 是您在先前步驟中建立的轉送規則名稱。
NETWORK 是您在先前步驟中建立的網路名稱。
TARGET_PROXY_NAME 是處理擴充功能流量的 Proxy 名稱。
CEL_EXPRESSION 是您要用於流量擴展功能的一般運算語言 (CEL) 運算式。如要進一步瞭解 CEL 語法，請參閱 CEL 比對器語言參考資料。
FAIL_OPEN 是布林值，用於判斷流量擴充功能是開啟還是關閉。有效值為 true 或 false。
ENV_GROUP_HOSTNAME 是您在先前步驟中建立的環境群組主機名稱。

注意：流量擴展功能建立完成後，就無法變更 name、lbForwardingRule 和 network 欄位。

這項作業可能需要幾分鐘才能完成。

取得流量擴充功能詳細資料

如要確認流量服務擴充功能是否已順利建立，請使用下列指令：

curl -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME"

將 TRAFFIC_EXT_NAME 替換為您剛建立的流量擴充功能名稱。

回應內容如下所示：

{
  "name": "my-traffic-extension",
  "extensionProcessor": "my-extension-processor",
  "lbForwardingRule": "https://www.googleapis.com/compute/v1/projects/my-project/global/forwardingRules/my-forwarding-rule",
  "network": "projects/my-project/global/networks/my-network",
  "networkConfigs": [
    {
      "region": "us-west1",
      "subnet": "projects/my-project/regions/us-west1/subnetworks/my-subnet"
    }
  ],
  "extensions": [
    {
      "name": "organizations/my-org/apis/my-api-proxy",
      "matchCondition": "request.url.contains('1234567890')",
      "failOpen": true,
      "hostname": "my-hostname.apigee.net",
      "supportedEvents": [
        "REQUEST_HEADERS",
        "RESPONSE_HEADERS"
      ]
    }
  ]
}

更新流量擴充功能

您可以使用 updateMask 參數更新流量擴展功能。使用 updateMask 參數時，請提供以半形逗號分隔的清單，指定要更新的資源屬性。updateMask 支援的屬性如下：

networkConfigs：更新 region 和 subnet 欄位。
注意：這個欄位只能更新全域應用程式負載平衡器。如果是區域應用程式負載平衡器，則無法更新 networkConfigs，必須刪除並重新建立擴充功能，才能修改網路設定。
extensions：更新 name、matchCondition、failOpen、hostname 和 supportedEvents 欄位。
extensionProcessor：更新 extensionProcessor 欄位。

如要更新流量擴展功能，請使用 curl 指令搭配 PATCH 方法。如要更新多個屬性，請在 updateMask 查詢參數中加入以逗號分隔的字串 (例如 ?updateMask=extensions,extensionProcessor)。

例如：

更新 `networkConfigs` (全域負載平衡)

如要更新 networkConfigs 屬性，請使用下列指令：

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=networkConfigs \
  -H "Content-Type:application/json" -d \
  '{
    "networkConfigs": [
      {
        "region": "REGION",
        "subnet": "projects/$PROJECT/regions/REGION/subnetworks/SUBNET"
      }
    ]
  }'

其中：

TRAFFIC_EXT_NAME 是要更新的擴充功能處理器流量擴充功能名稱。
REGION 是更新後區域的地區。
SUBNET 是指網路的新子網路。

更新「`extensions`」

如要更新 extensions 屬性，請使用下列指令：

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensions \
  -H "Content-Type:application/json" -d \
  '{
    "extensions": [
      {
        "name": "TARGET_PROXY_NAME",
        "matchCondition": "NEW_CEL_EXPRESSION",
        "failOpen": NEW_FAIL_OPEN
        "hostname": "NEW_ENV_GROUP_HOSTNAME",
        "supportedEvents": [
          "REQUEST_HEADERS",
          "RESPONSE_HEADERS"
        ]
      }
    ]
  }'

其中：

TRAFFIC_EXT_NAME 是要更新的擴充功能處理器流量擴充功能名稱。
TARGET_PROXY_NAME 是處理擴充功能流量的 Proxy 名稱。
NEW_CEL_EXPRESSION 是更新的 CEL 運算式。
NEW_FAIL_OPEN 是失敗開啟的更新布林值。
NEW_ENV_GROUP_HOSTNAME 是環境群組的主機名稱。

更新「`extensionProcessor`」

如要更新 extensionProcessor 屬性，請使用下列指令：

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensionProcessor \
  -H "Content-Type:application/json" -d \
  '{
    "extensionProcessor": "NEW_TARGET_PROXY_NAME"
  }'

其中：

TRAFFIC_EXT_NAME 是要更新的擴充功能處理器流量擴充功能名稱。
NEW_TARGET_PROXY_NAME 是處理擴充功能流量的 Proxy 新名稱。

更新多個屬性 (全球 LB)

如要同時更新 extensions 和 extensionProcessor 屬性，請使用下列指令：

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensions,extensionProcessor \
  -H "Content-Type:application/json" -d \
  '{
    "extensions": [
      {
        "name": "TARGET_PROXY_NAME",
        "matchCondition": "NEW_CEL_EXPRESSION",
        "failOpen": NEW_FAIL_OPEN,
        "hostname": "NEW_ENV_GROUP_HOSTNAME",
        "supportedEvents": [
          "REQUEST_HEADERS",
          "RESPONSE_HEADERS"
        ]
      }
    ],
    "extensionProcessor": "NEW_TARGET_PROXY_NAME"
  }'

其中：

TRAFFIC_EXT_NAME 是要更新的擴充功能處理器流量擴充功能名稱。
TARGET_PROXY_NAME 是處理擴充功能流量的 Proxy 名稱。
NEW_CEL_EXPRESSION 是更新的 CEL 運算式。
NEW_FAIL_OPEN 是失敗開啟的更新布林值。
NEW_ENV_GROUP_HOSTNAME 是環境群組的主機名稱。
NEW_TARGET_PROXY_NAME 是處理擴充功能流量的 Proxy 新名稱。

向負載平衡器傳送要求

如要測試負載平衡器和擴充功能處理器設定，請將要求傳送至負載平衡器：

curl "https://LB_DOMAIN_NAME/get"

其中 LB_DOMAIN_NAME 是您用於負載平衡器和 SSL 憑證的網域名稱。如果您使用 nip.io，網域名稱會類似於 IP_ADDRESS.nip.io。

回應內容如下所示：

{"status": 200,
  {
    "args": {},
    "headers": {
      ...
    },
    "origin": "173.93.50.108",
    "url": "https://httpbin.org/get"
  }
}

搭配擴充功能處理器使用政策

本節說明如何搭配擴充功能處理器使用政策。

在本範例中，請為擴充功能處理器設定 VerifyAPIKey 和 AssignMessage 政策。這些政策會驗證傳送至 Apigee 的要求中是否包含 API 金鑰，並將 Google權杖插入要求標頭，以便呼叫後端服務。如果 API 供應商使用 Apigee 擴充功能處理器，授權及驗證對 Apigee 服務的要求，並順暢地插入後端服務 (例如 Vertex AI) 所需的Google 驗證權杖，這個情境就非常實用。

新增 VerifyAPIKey 政策，驗證 API 金鑰

以下章節說明如何使用 VerifyAPIKey 政策，透過擴充功能處理器驗證對後端服務的呼叫 API 金鑰：

將 VerifyAPIKey 政策附加至擴充功能處理器。
建立 API 產品。
建立開發人員應用程式和應用程式憑證。
使用 API 金鑰傳送要求至負載平衡器。

將 VerifyAPIKey 政策附加至 Proxy

將 VerifyAPIKey 政策附加至擴充功能處理器 Proxy：

在 Google Cloud 控制台中，前往「Proxy 開發」>「API Proxy」頁面。

前往「API Proxies」(API Proxy)
選取您在「建立擴充功能處理器」一節中建立的擴充功能處理器 Proxy。
按一下「開發」分頁標籤。
在導覽窗格中，按一下「政策」部分中的。
在「建立政策」對話方塊中，從政策清單選取「VerifyAPIKey」。
在「VerifyAPIKey」窗格中，使用下列值填寫「Name」和「Display name」區段中的必填欄位：
- 名稱：輸入政策名稱。例如：VA-verify-api-key。
- 顯示名稱：輸入要在使用者介面中使用的政策名稱。例如：VA-verify-api-key。

按一下「建立」。

Extension Processor Proxy 中包含的 VerifyAPIKey 政策 XML 規格應如下所示：

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <VerifyAPIKey continueOnError="false" enabled="true" name="VA-verify-api-key">
    <DisplayName>VA-verify-api-key</DisplayName>
    <Properties/>
    <APIKey ref="request.queryparam.x-api-key"/>
  </VerifyAPIKey>

部署新的 Proxy 修訂版本。

建立 API 產品

如要建立 API 產品並設定服務的 API 作業集，請按照下列步驟操作：

按照「建立 API 產品」一文中的步驟，為服務建立 API 產品。您可以視需要設定 API 產品的產品詳細資料。
按照「作業」中的步驟，根據下列規格將 API 作業集新增至 API 產品：
- 來源：
  在 Google Cloud 控制台中，前往「發布」>「API 產品」頁面。
  
  前往「API 產品」頁面
  選取您在先前步驟中建立的 API 產品。
- 作業：按一下「編輯」，然後設定下列路徑和方法：
  - 路徑：/get，方法：GET
  - 路徑：/TARGET_PROXY_NAME，方法：GET
    TARGET_PROXY_NAME 是處理擴充功能流量的 Proxy 名稱。

建立開發人員應用程式和應用程式憑證

如要為新建立的 API 產品建立開發人員應用程式和應用程式憑證，請按照下列步驟操作：

前往 Google Cloud 控制台的「Apigee API management」(Apigee API 管理) 頁面：
Apigee API 管理平台
建立開發人員：
1. 選取「發行」>「開發人員」。
2. 在「開發人員」頁面中，按一下「+ 建立」。
3. 在「新增開發人員」頁面中，使用任意值填寫必填欄位。
4. 按一下「新增」。
建立應用程式：
1. 選取「發布」>「應用程式」。
2. 在「應用程式」頁面，按一下「+ 建立」
3. 在「建立應用程式」頁面中，使用下列值填寫「應用程式詳細資料」區段中的必填欄位：
  - 應用程式名稱：輸入應用程式名稱，例如 ext-proc-app
  - 開發人員：選取您在上一個步驟中建立的開發人員，或從清單中選取其他開發人員。
4. 在「應用程式憑證」部分中，按一下「+ 新增憑證」。
5. 在「憑證」部分，從「到期」清單方塊中選取「永不」。
6. 在「產品」部分中，按一下「+ 新增產品」，顯示「新增產品」窗格。
7. 選取您在上一步建立的 API 產品。
8. 按一下 [確定]。
9. 按一下「新增」，關閉「新增產品」窗格。
10. 點選「建立」。
在「應用程式詳細資料」頁面的「憑證」部分，按一下即可顯示「金鑰」的值。
複製 Key 值。您會在後續步驟中使用這組金鑰，對服務發出 API 呼叫。
在「應用程式詳細資料」頁面的「憑證」部分，按一下即可顯示「應用程式密鑰」的值。

使用 API 金鑰將要求傳送至負載平衡器

如要測試 API 金鑰驗證，請使用 API 金鑰將要求傳送至負載平衡器：

curl "https://LB_DOMAIN_NAME/get"

其中 LB_DOMAIN_NAME 是您用於負載平衡器和 SSL 憑證的網域名稱。

如果沒有 API 金鑰，回應就會失敗。

使用要求中的 API 金鑰，將另一個要求傳送至負載平衡器：

curl "https://LB_DOMAIN_NAME/get?key=API_KEY"

其中：

LB_DOMAIN_NAME 是您用於負載平衡器和 SSL 憑證的網域名稱。
API_KEY 是在稍早步驟中顯示的開發人員應用程式憑證 API 金鑰。

這項回應表示端點授權成功。這表示 Extension Processor 已驗證 API 金鑰，Apigee Proxy 現在可以處理要求。

新增 Google 驗證的 AssignMessage 政策

如要使用 Extension Processor 為 Google 驗證服務提供 API 管理功能，可以透過 AssignMessage 政策，將 Google 存取權杖或 Google ID 權杖插入傳送至後端服務的要求。

以下各節說明如何使用 AssignMessage 政策，透過擴充功能處理器將驗證權杖插入傳送至後端服務的要求： Google

將 AssignMessage 政策附加至 Proxy。
將要求傳送至負載平衡器，測試權杖插入作業。

將 AssignMessage 政策附加至 Proxy

如要在 Proxy 中新增 AssignMessage 政策，請按照下列步驟操作：

在 Google Cloud 控制台中，前往「Proxy 開發」>「API Proxy」頁面。

前往「API Proxies」(API Proxy)
選取您在「建立擴充功能處理器」一節中建立的擴充功能處理器 Proxy。
按一下「開發」分頁標籤。
在導覽窗格中，按一下「政策」部分中的。
在「建立政策」對話方塊中，從政策清單選取「AssignMessage」。
在「Assign Message」窗格中，使用下列值填妥「Name」和「Display name」區段中的必填欄位：
- 名稱：輸入政策名稱。例如：AM-auth。
- 顯示名稱：輸入要在使用者介面中顯示的政策名稱。例如：AM-auth。
點選「建立」。

在 <Set> 元素下方，新增下列子項元素：

<Set>
    <Authentication>
    <HeaderName>Authorization</HeaderName>
    <GoogleAccessToken>
        <Scopes>
        <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
    </GoogleAccessToken>
    </Authentication>
</Set>

按一下 [儲存]。
使用 Google 服務帳戶部署新修訂版本。

服務帳戶會產生 Google 存取權杖，並將權杖插入 API 呼叫的要求標頭，傳送至 Google 後端服務。

向負載平衡器傳送要求，測試權杖插入作業

如要確認權杖插入作業正常運作，請將要求傳送至負載平衡器：

curl "https://LB_DOMAIN_NAME/get"

其中 LB_DOMAIN_NAME 是您用於負載平衡器和 SSL 憑證的網域名稱。

回應內容如下所示：

{
  ...
  "headers": {
    "Accept": "*/*",
    "Authorization": "Bearer ya29.c.c0ASRK0Gbw03y9cfvxL11DxaRYBQUU18SmUP4Vu63OckHI5cX7wJ4DmGMG2vbDDS69HXJHqMj-lak4tcqOsJGmE65crn2gNuJLanXidwM8",
    "First": "1.0",
    "Host": "apigee-ext-proc-test.apigee.net",
    "Second": "1.0",
    "Sum": "2",
    "User-Agent": "curl/8.7.1",
    "X-Api-Key": "McYcHGR3PTSGLXExvKADwQ1JJeCjgPDUvAakCl0rJKCFaX0Y",
    "X-Cloud-Trace-Context": "0fd3dadc2a3c328fa968d5f5f1434c29/18300783092696918345"
  },
  ...
}

回應會顯示驗證權杖已成功注入要求標頭。 Google

成功套用 AssignMessage 政策後，系統會進一步修改範例情境中用戶端對 Apigee 的成功要求 (內含 API 金鑰)，在要求標頭中加入 Google 驗證權杖，這是 Google驗證後端服務的要求。

開始使用 Apigee Extension Processor 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

設定環境變數

設定驗證權杖

為後端服務設定負載平衡器

建立全域外部應用程式負載平衡器

建立網路端點群組 (NEG)

建立後端服務

建立網址對應

建立目標 Proxy

建立通用轉送規則

設定 Apigee 擴充功能處理器

建立 Apigee 環境

建立擴充功能處理器 Proxy

沒有目標 Proxy

支援 SSE 的 Proxy

設定流量擴充功能

使用 Extension Processor 佈建 API 建立流量擴充功能

取得流量擴充功能詳細資料

更新流量擴充功能

更新 networkConfigs (全域負載平衡)

更新「extensions」

更新「extensionProcessor」

更新多個屬性 (全球 LB)

向負載平衡器傳送要求

搭配擴充功能處理器使用政策

新增 VerifyAPIKey 政策，驗證 API 金鑰

將 VerifyAPIKey 政策附加至 Proxy

建立 API 產品

建立開發人員應用程式和應用程式憑證

使用 API 金鑰將要求傳送至負載平衡器

新增 Google 驗證的 AssignMessage 政策

將 AssignMessage 政策附加至 Proxy

向負載平衡器傳送要求，測試權杖插入作業

開始使用 Apigee Extension Processor

更新 `networkConfigs` (全域負載平衡)

更新「`extensions`」

更新「`extensionProcessor`」