Apigee 확장 프로그램 프로세서 시작하기

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

이 페이지에서는 Service Extensions 지원 부하 분산기를 사용하여 API 트래픽에 API 정책을 적용할 수 있도록 Apigee 확장 프로그램 프로세서를 구성하는 방법을 설명합니다.

API 관리를 위해 Apigee 확장 프로그램 프로세서를 사용하는 데 따른 권장 사용 사례와 이점에 대해 자세히 알아보려면 Apigee 확장 프로그램 프로세서 개요를 참조하세요.

Apigee 확장 프로그램 프로세서는 Cloud Load Balancing을 사용하여 애플리케이션 부하 분산기의 데이터 처리 경로에서 Apigee 확장 프로그램 프로세서로 콜아웃을 보낼 수 있는 트래픽 확장 프로그램(Service Extension의 유형)입니다. 부하 분산기와 트래픽 확장 프로그램이 구성되면 API 트래픽이 부하 분산기에 의해 처리됩니다. Apigee 확장 프로그램 프로세서의 정책은 트래픽 확장 프로그램 콜아웃을 사용하여 API 트래픽에 적용됩니다.

다음 섹션에서는 Apigee 확장 프로그램 프로세서의 주요 요소를 구성하는 데 필요한 단계를 안내합니다.

백엔드 서비스의 부하 분산기 구성

Apigee 확장 프로그램 프로세서 구성

트래픽 확장 프로그램 구성

확장 프로그램 프로세서로 정책 사용

시작하기 전에

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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Enable the APIs

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

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 콘솔의 인스턴스 페이지로 이동하여 인스턴스를 선택하고 세부정보를 봅니다.
인스턴스로 이동

구독 또는 사용한 만큼만 지불 Apigee 조직에서 확장 프로그램 프로세서를 사용할 수 있습니다. 구독 또는 사용한 만큼만 지불 Apigee 조직을 사용 중인지 확실하지 않은 경우 Apigee 조직 관리자에게 문의하세요. 유료 Apigee 인스턴스 프로비저닝에 대한 자세한 내용은 시작하기 전에를 참조하세요.
사용할 Apigee 인스턴스에서 VPC 및 서브넷이 사용 설정되어 있는지 확인합니다. Google Cloud 콘솔에서 VPC 네트워크 페이지로 이동합니다.
VPC 네트워크로 이동

필요한 역할

Apigee 확장 프로그램 프로세서를 설치하는 데 필요한 권한을 얻으려면 관리자에게 조직에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

서비스 계정 생성 및 관리: 서비스 계정 관리자(roles/iam.serviceAccountAdmin)
서비스 확장 프로그램 생성 및 관리: 서비스 확장 프로그램 관리자(roles/networkservices.serviceExtensionsAdmin)
네트워크 엔드포인트 그룹(NEG) 생성 및 관리: Compute 인스턴스 관리자(roles/compute.instanceAdmin)
네트워킹 리소스 만들기 및 관리: Compute 네트워크 관리자(roles/compute.networkAdmin)
백엔드 서비스 생성 및 관리: Compute 부하 분산기 관리자(roles/compute.loadBalancerAdmin)
Apigee 리소스 생성 및 관리: Apigee 조직 관리자(roles/apigee.admin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

환경 변수 설정하기

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은 Apigee 확장 프로그램 프로세서에 사용할 Google Cloud 프로젝트의 VPC 네트워크 이름입니다.
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) 만들기
백엔드 서비스 만들기
URL 맵 만들기
대상 프록시 만들기
전역 전달 규칙 만들기

전역 외부 애플리케이션 부하 분산기 만들기

부하 분산기를 만들려면 다음 안내를 따르세요.

현재 프로젝트를 사용하도록 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 주소의 이름입니다.
IP 주소에 와일드 카드 DNS 레코드를 제공하는 서드 파티 서비스인 nip.io의 TLS 인증서를 만듭니다.
```
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의 이름입니다.

URL 맵 만들기

부하 분산기와 백엔드 서비스 간에 URL 맵을 만들려면 다음 명령어를 사용하세요.

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

각 항목의 의미는 다음과 같습니다.

URL_MAP_NAME은 만들려는 URL 맵의 이름입니다.
BACKEND_SERVICE_NAME은 이전 단계에서 만든 백엔드 서비스의 이름입니다.

대상 프록시 만들기

부하 분산기의 대상 프록시를 만들려면 다음 명령어를 사용합니다.

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은 만들려는 대상 프록시의 이름입니다.
URL_MAP_NAME은 이전 단계에서 만든 URL 맵의 이름입니다.
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은 이전 단계에서 만든 대상 프록시의 이름입니다.

Apigee 확장 프로그램 프로세서 구성

다음 섹션에서는 Apigee 확장 프로그램 프로세서를 설정하는 데 필요한 단계를 설명합니다.

Apigee 환경 만들기
확장 프로그램 프로세서 프록시 만들기

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은 이전 단계에서 만든 환경의 이름입니다.

확장 프로그램 프로세서 프록시 만들기

확장 프로그램 프로세서 부하 분산기와 함께 사용할 Apigee 대상이 없는 API 프록시를 만들려면 다음 단계를 따르세요.

API 프록시 만들기의 단계에 따라 다음 사양으로 대상이 없는 프록시를 만듭니다.

프록시 템플릿: 대상 없음을 선택합니다.
프록시 이름: 프록시 이름을 입력합니다.
기본 경로: 원하는 기본 경로를 설정합니다. 경로는 사용되지 않습니다.

프록시의 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 프록시 배포의 단계에 따라 이전에 만든 환경에 프록시를 배포합니다.

트래픽 확장 프로그램 구성

이 섹션에서는 다음 단계를 사용하여 확장 프로그램 프로세서의 트래픽 서비스 확장 프로그램을 구성하는 방법을 설명합니다.

Apigee Private Service Connect 네트워크 엔드포인트 그룹 만들기
부하 분산기 서비스 확장 프로그램 만들기
부하 분산기로 요청 전송

Apigee Private Service Connect 네트워크 엔드포인트 그룹 만들기

이 섹션에서는 Apigee 인스턴스에 연결하는 데 사용되는 Apigee Private Service Connect(PSC) 네트워크 엔드포인트 그룹(NEG)을 만듭니다. PSC에 대해 자세히 알아보려면 Southbound 네트워킹 패턴을 참고하세요.

참고: Apigee PSC 서비스 연결을 가져오는 명령어에는 jq가 필요합니다. 이 JSON 처리 유틸리티가 개발 환경에 아직 설치되어 있지 않은 경우 다음 명령어를 사용하여 설치할 수 있습니다. $ sudo apt install jq.

Apigee PSC NEG를 만들려면 다음 단계를 따르세요.

Apigee PSC 서비스 연결을 가져옵니다.

PSC_ATTACHMENT=$(curl -s -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances" \
    | jq -r '.instances[] | select(.name = "'$INSTANCE'") | .serviceAttachment' \
    )

서비스 연결을 보려면 다음 단계를 따르세요.

echo $PSC_ATTACHMENT

다음과 비슷한 응답이 표시됩니다.

projects/apigee-psc-autopush/regions/us-west1/serviceAttachments/apigee-us-west1-1234567890-psc-service-attachment

Apigee 인스턴스와 동일한 리전에 PSC NEG를 만듭니다.

gcloud compute network-endpoint-groups create apigee-neg-$REGION \
  --network-endpoint-type=private-service-connect \
  --psc-target-service=$PSC_ATTACHMENT \
  --region=$REGION \
  --network=$VPC_NETWORK_NAME \
  --subnet=$SUBNET

다음과 비슷한 응답이 표시됩니다.

projects/ab123456cd78ef910g-tp/regions/asia-northeast1/serviceAttachments/apigee-asia-northeast1-abcd

PSC NEG를 가리키는 HTTP/2 백엔드 서비스가 아직 없는 경우 만듭니다.
```
gcloud compute backend-services create PSC_NEG_BACKEND_SERVICE \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --protocol=HTTP2 \
  --global
```
PSC_NEG_BACKEND_SERVICE는 만들려는 백엔드 서비스의 이름입니다.

PSC NEG 백엔드 서비스를 추가합니다.

gcloud compute backend-services add-backend PSC_NEG_BACKEND_SERVICE \
  --network-endpoint-group=apigee-neg-$REGION \
  --network-endpoint-group-region=$REGION \
  --global

PSC_NEG_BACKEND_SERVICE는 이전 단계에서 만든 백엔드 서비스의 이름입니다.

백엔드 서비스에 로깅을 사용 설정합니다.
```
gcloud compute backend-services update PSC_NEG_BACKEND_SERVICE \
  --global \
  --enable-logging \
  --logging-sample-rate=1.0
```
PSC_NEG_BACKEND_SERVICE는 이전 단계에서 만든 백엔드 서비스의 이름입니다.

부하 분산기 서비스 확장 프로그램 만들기

부하 분산기 서비스 확장 프로그램을 만들 때 다음 표에 표시된 대로 확장 프로그램을 설명하는 다양한 필드의 값을 변경하여 확장 프로그램 프로세서 프록시의 동작을 맞춤설정할 수 있습니다.

본문 처리 지원되는 이벤트 메타데이터 전송 모드

요청 및 응답 본문 처리

본문 처리	지원되는 이벤트	메타데이터	전송 모드
요청 및 응답 본문 처리	`REQUEST_HEADERS` `REQUEST_BODY` `REQUEST_TRAILERS` `RESPONSE_HEADERS` `RESPONSE_BODY` `RESPONSE_TRAILERS`	`apigee-request-body: true` `apigee-response-body: true`	`requestBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED` `responseBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED`
요청 본문 처리만	`REQUEST_HEADERS` `REQUEST_BODY` `REQUEST_TRAILERS` `RESPONSE_HEADERS`	`apigee-request-body: true`	`requestBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED`
응답 본문 처리만	`REQUEST_HEADERS` `RESPONSE_HEADERS` `RESPONSE_BODY` `RESPONSE_TRAILERS`	`apigee-response-body: true`	`responseBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED`

REQUEST_HEADERS

REQUEST_BODY

REQUEST_TRAILERS

RESPONSE_HEADERS

RESPONSE_BODY

RESPONSE_TRAILERS

apigee-request-body: true

apigee-response-body: true

requestBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED

responseBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED

요청 본문 처리만

REQUEST_HEADERS

REQUEST_BODY

REQUEST_TRAILERS

RESPONSE_HEADERS

apigee-request-body: true

requestBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED

응답 본문 처리만

REQUEST_HEADERS

RESPONSE_HEADERS

RESPONSE_BODY

RESPONSE_TRAILERS

apigee-response-body: true

responseBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED

이 단계에서는 요청 및 응답 본문 처리를 지원하는 부하 분산기 서비스 확장 프로그램을 만듭니다.

curl -X POST "https://networkservices.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/global/lbTrafficExtensions?lbTrafficExtensionId=global-xlb-httpbin-apim-policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "global-xlb-httpbin-apim-policy",
    "forwardingRules": [
        "https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME"
    ],
    "extensionChains": [
        {
            "name": "httpbin-apigee-extension-chain",
            "matchCondition": {
                "celExpression": "true"
            },
            "extensions": [
                {
                    "name": "httpbin-apigee-extension",
                    "authority": "ENV_GROUP_HOSTNAME",
                    "service": "https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/backendServices/PSC_NEG_BACKEND_SERVICE",
                    "supportedEvents": [
                        "REQUEST_HEADERS",
                        "REQUEST_BODY",
                        "REQUEST_TRAILERS",
                        "RESPONSE_HEADERS",
                        "RESPONSE_BODY",
                        "RESPONSE_TRAILERS"
                    ],
                    "timeout": "1s",
                    "requestBodySendMode": "BODY_SEND_MODE_FULL_DUPLEX_STREAMED",
                    "responseBodySendMode": "BODY_SEND_MODE_FULL_DUPLEX_STREAMED"
                }
            ]
        }
    ],
    "loadBalancingScheme": "EXTERNAL_MANAGED",
    "metadata": {
        "apigee-extension-processor": "EXT_PROC_NAME",
        "apigee-request-body": "true",
        "apigee-response-body": "true"
    }
}'

각 항목의 의미는 다음과 같습니다.

EXT_PROC_NAME: 이 이름은 이전 단계에서 만든 API 프록시의 이름과 일치해야 합니다.
FORWARDING_RULE_NAME은 이전 단계에서 만든 전달 규칙의 이름입니다.
ENV_GROUP_HOSTNAME은 환경 그룹에 사용되는 도메인 이름입니다.
PSC_NEG_BACKEND_SERVICE는 이전 단계에서 만든 백엔드 서비스의 이름입니다.

이 작업을 완료하는 데 몇 분 정도 걸릴 수 있습니다.

서비스 확장 프로그램이 생성되었는지 확인하려면 다음 명령어를 사용하세요.

curl "https://networkservices.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/global/lbTrafficExtensions/httpbin-apigee-extension" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

응답은 다음과 비슷하게 표시되며 전달 규칙과 백엔드 서비스를 표시해야 합니다.

createTime: '2025-03-22T00:29:16.056719825Z'
extensionChains:
- extensions:
  - authority: extension-processor-test.hybrid.e2e.apigeeks.net
    name: httpbin-apigee-extension
    service: https://www.googleapis.com/compute/v1/projects/123456789012/global/backendServices/ep-test-psc-neg-bes
    supportedEvents:
    - REQUEST_HEADERS
    - REQUEST_BODY
    - REQUEST_TRAILERS
    - RESPONSE_HEADERS
    - RESPONSE_BODY
    - RESPONSE_TRAILERS
    timeout: 1s
  matchCondition:
    celExpression: 'true'
  name: httpbin-apigee-extension-chain
forwardingRules:
- https://www.googleapis.com/compute/v1/projects/123456789012/global/forwardingRules/ep-test-fw-rule
loadBalancingScheme: EXTERNAL_MANAGED
metadata:
  apigee-extension-processor: ep-test-proxy
  apigee-request-body: true
  apigee-response-body: true
name: projects/extension-processor-test/locations/global/lbTrafficExtensions/global-xlb-httpbin-apim-policy
updateTime: '2025-03-22T00:29:31.183275055Z'

부하 분산기로 요청 전송

부하 분산기 및 확장 프로그램 프로세서 설정을 테스트하려면 부하 분산기로 요청을 전송하세요.

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토큰을 삽입하는 데 사용됩니다. 이 시나리오는 Apigee 확장 프로그램 프로세서를 사용하여 Apigee 서비스에 대한 요청을 승인 및 인증하고 Vertex AI와 같은 백엔드 서비스에 필요한 Google 인증 토큰을 원활하게 삽입하는 API 제공업체에 유용합니다.

API 키 유효성 검사를 위한 VerifyAPIKey 정책 추가

다음 섹션에서는 확장 프로그램 프로세서를 사용하여 백엔드 서비스에 대한 호출의 API 키를 검증하기 위해 VerifyAPIKey 정책을 사용하는 방법을 설명합니다.

VerifyAPIKey 정책을 확장 프로그램 프로세서에 연결
API 제품 만들기
개발자 앱 및 앱 사용자 인증 정보 만들기
API 키를 사용하여 부하 분산기에 요청 전송

프록시에 VerifyAPIKey 정책 추가

확장 프로그램 프로세서 프록시에 VerifyAPIKey 정책을 연결하려면 다음 단계를 따르세요.

Cloud 콘솔의 Apigee UI에서 개발 탭으로 이동하여 이전 단계에서 만든 확장 프로그램 프로세서 프록시를 선택합니다.
정책 섹션에서 + 정책 추가를 클릭합니다.
정책 추가 창의 정책 목록에서 VerifyAPIKey를 선택합니다.
VerifyAPIKey 창의 정책 이름 및 표시 이름 섹션에 다음 값을 사용하여 필수 필드를 작성합니다.
- 정책 이름: 정책 이름을 입력합니다. 예를 들면 VA-verify-api-key입니다.
- 표시 이름: UI에 사용할 정책 이름을 입력합니다. 예를 들면 VA-verify-api-key입니다.

만들기를 클릭합니다.

확장 프로그램 프로세서 프록시에 포함된 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>

새 프록시 버전을 배포합니다.

API 제품 만들기

API 제품을 만들고 서비스의 API 작업 세트를 구성하려면 다음 단계를 따르세요.

API 제품 만들기의 단계에 따라 서비스의 API 제품을 만듭니다. 원하는 대로 API 제품의 제품 세부정보를 구성할 수 있습니다.
작업의 단계에 따라 다음 사양에 따라 API 제품에 API 작업 세트를 추가합니다.
- 소스: API 프록시를 선택하고 이전 단계에서 만든 프록시를 선택합니다.
- 작업: 다음 경로와 메서드를 구성합니다.
  - 경로: /get, 메서드: GET
  - 경로: /PROXY_NAME, 메서드: GET
    PROXY_NAME은 이전 단계에서 만든 프록시의 이름입니다.

개발자 앱 및 앱 사용자 인증 정보 만들기

새로 만든 API 제품의 개발자 앱과 앱 사용자 인증 정보를 만들려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 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 키입니다.

응답은 엔드포인트의 인증이 성공했음을 나타내야 합니다. 이는 확장 프로그램 프로세서가 API 키의 유효성을 검사했으며 이제 Apigee 프록시에서 요청을 처리할 수 있음을 나타냅니다.

Google 인증을 위한 AssignMessage 정책 추가

확장 프로그램 프로세서를 사용하여 Google 인증 서비스에 API 관리를 제공하려면 AssignMessage 정책을 사용하여 백엔드 서비스로 전송되는 요청에 Google 액세스 토큰 또는 Google ID 토큰을 삽입하면 됩니다.

다음 섹션에서는 AssignMessage 정책을 사용하여 확장 프로그램 프로세서를 통해 백엔드 서비스로 전송되는 요청에 Google 인증 토큰을 삽입하는 방법을 설명합니다.

AssignMessage 정책을 프록시에 연결
부하 분산기에 요청을 보내 토큰 삽입 테스트

AssignMessage 정책을 프록시에 연결

AssignMessage 정책을 프록시에 추가하려면 다음 안내를 따르세요.

Cloud 콘솔의 Apigee UI에서 개발 탭으로 이동하여 이전 단계에서 만든 프록시를 선택합니다.
정책 섹션에서 + 정책 추가를 클릭합니다.
정책 추가 창의 정책 목록에서 메시지 할당을 선택합니다.
AssignMessage 창의 정책 이름 및 표시 이름 섹션에 다음 값을 사용하여 필수 필드를 작성합니다.
- 정책 이름: 정책 이름을 입력합니다. 예를 들면 AM-auth입니다.
- 표시 이름: UI에 표시할 정책 이름을 입력합니다. 예를 들면 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 액세스 토큰을 생성하고 Google 백엔드 서비스에 대한 API 호출의 요청 헤더에 삽입하는 데 사용됩니다.

토큰 삽입을 테스트하기 위해 부하 분산기로 요청 전송

토큰 삽입이 작동하는지 확인하려면 부하 분산기에 요청을 전송합니다.

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 확장 프로그램 프로세서 시작하기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필요한 역할

환경 변수 설정하기

인증 토큰 구성

백엔드 서비스의 부하 분산기 구성

전역 외부 애플리케이션 부하 분산기 만들기

네트워크 엔드포인트 그룹(NEG) 만들기

백엔드 서비스 만들기

URL 맵 만들기

대상 프록시 만들기

전역 전달 규칙 만들기

Apigee 확장 프로그램 프로세서 구성

Apigee 환경 만들기

확장 프로그램 프로세서 프록시 만들기

트래픽 확장 프로그램 구성

Apigee Private Service Connect 네트워크 엔드포인트 그룹 만들기

부하 분산기 서비스 확장 프로그램 만들기

부하 분산기로 요청 전송

확장 프로그램 프로세서와 함께 정책 사용

API 키 유효성 검사를 위한 VerifyAPIKey 정책 추가

프록시에 VerifyAPIKey 정책 추가

API 제품 만들기

개발자 앱 및 앱 사용자 인증 정보 만들기

API 키를 사용하여 부하 분산기에 요청 전송

Google 인증을 위한 AssignMessage 정책 추가

AssignMessage 정책을 프록시에 연결

토큰 삽입을 테스트하기 위해 부하 분산기로 요청 전송

Apigee 확장 프로그램 프로세서 시작하기