이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
무엇을
ExternalCallout 정책을 사용하면 Apigee 정책으로 지원되지 않는 커스텀 동작을 구현하기 위해 gRPC 요청을 gRPC 서버로 전송할 수 있습니다. 서버 코드에서 프록시 흐름 내에서 흐름 변수에 쉽게 액세스하고 이를 수정할 수 있습니다.
Apigee는 API에서 ExternalCallout 정책을 통해 gRPC 서버와 통신합니다. Apigee는 API를 사용하여 흐름 변수를 gRPC 서버로 전송합니다. gRPC 서버 내에서 정책 XML 내에 지정하는 추가 변수는 물론 흐름 변수 참조 페이지에 나열된 흐름 변수를 읽고, 변수에 따라 수정할 수도 있습니다.
Apigee로 gRPC 서버를 구성하고 이 정책을 프록시에 포함하면 Apigee가 API 요청을 다음과 같이 처리합니다.
- Apigee는 흐름 변수를 포함하는 메시지를 gRPC 서버에 전송합니다.
- gRPC 서버 코드가 실행되고 코드에 정의된 대로 변수를 액세스하고 수정합니다. 그런 후 gRPC 서버는 모든 흐름 변수를 포함하는 응답을 다시 Apigee로 전송합니다.
- Apigee는 gRPC 서버에서 응답을 읽습니다. 변수가 추가되거나 수정 가능한 흐름 변수가 수정되면 Apigee에서 업데이트됩니다.
이 정책은 표준 정책이며 모든 환경 유형에 배포할 수 있습니다. 모든 사용자가 정책 및 환경 유형에 대해 알아야 할 필요는 없습니다. 정책 유형과 각 환경 유형에서의 가용성에 대한 자세한 내용은 정책 유형을 참조하세요.
gRPC 요청 전송에 대해 자세히 알아보려면 다음 링크를 참조하세요.
<ExternalCallout>
ExternalCallout 정책을 정의합니다.
<ExternalCallout async="true" continueOnError="true" enabled="true" name="EC">
이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.
속성 | 기본 | 필수 여부 | 설명 |
---|---|---|---|
name |
해당 없음 | 필수 |
정책의 내부 이름입니다. 원하는 경우 |
continueOnError |
false | 선택 | 정책이 실패할 경우 오류가 반환되도록 하려면 false 로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true 로 설정합니다. 참조:
|
enabled |
true | 선택 | 정책을 시행하려면 true 로 설정합니다. 정책을 중지하려면 false 로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다. |
async |
false | 지원 중단됨 | 이 속성은 지원이 중단되었습니다. |
다음 표에서는 <ExternalCallout>
의 하위 요소를 설명합니다.
하위 요소 | 필수 | 설명 |
---|---|---|
<TimeoutMs> |
필수 | gRPC 요청에 대한 요청 제한 시간(밀리초)입니다. |
<GrpcConnection> |
필수 | 요청을 전송할 gRPC 서버로 사용할 기존 TargetServer 의 이름을 지정합니다.
|
<Configurations> |
선택사항 | <Property> 및 <FlowVariable> 요소를 포함하여 ExternalCallout 정책의 여러 측면을 구성할 수 있습니다. |
예 1
ExternalCallout의 작업 예시는 GitHub의 External Callout 샘플에서 이용하세요.
다음 예시는 ExternalCallout 정책 구성을 보여줍니다.
<ExternalCallout enabled="true" continueOnError="false" name="ExternalCallout-1"> <DisplayName>External Callout 1</DisplayName> <TimeoutMs>5000</TimeoutMs> <GrpcConnection> <Server name="external-target-server"/> </GrpcConnection> <Configurations> <Property name="with.request.content">true</Property> <Property name="with.request.headers">false</Property> <Property name="with.response.content">true</Property> <Property name="with.response.headers">false</Property> <FlowVariable>example1.flow.variable</FlowVariable> <FlowVariable>example2.flow.variable</FlowVariable> </Configurations> <ExternalCallout>
이 예시에서는 다음 구성을 사용하여 external-target-server
라는
TargetServer로 표시된 외부 gRPC 서버로 요청을 전송합니다.
<Property>
: 요청 및 응답 콘텐츠를 포함하지만 gRPC 서버로 전송된 요청의 요청 및 응답 헤더를 포함하지 않습니다.<FlowVariable>
: gRPC 서버에 전송된 요청에서FlowVariable
요소로 지정된 추가적인 흐름 변수example1.flow.variable
및example2.flow.variable
을 포함합니다.
예 2
다음 예시에서는 Audience
요소의 useTargetUrl
속성이 true
로 설정됩니다. useTargetUrl
이 true
이면 gRPC 대상 서버의 호스트 이름이 대상으로 사용됩니다. 예를 들어 서버의 호스트가 my-grpc-server-java.a.run.app
이면 사용되는 대상은 https://my-grpc-server-java.a.run.app
입니다.
<ExternalCallout continueOnError="false" enabled="true" name="External-Callout-1"> <DisplayName>External-Callout-1</DisplayName> <GrpcConnection> <Server name="cloud_run_server_name"/> <Authentication> <GoogleIDToken> <Audience useTargetUrl="true"/> </GoogleIDToken> </Authentication> </GrpcConnection> <TimeoutMs>5000</TimeoutMs> <Configurations> <Property name="with.request.content">true</Property> <Property name="with.request.headers">true</Property> <Property name="with.response.content">true</Property> <Property name="with.response.headers">true</Property> <FlowVariable>example.flow.variable</FlowVariable> <FlowVariable>another.flow.variable</FlowVariable> </Configurations> </ExternalCallout>
하위 요소 참조
다음 섹션에서는 ExternalCallout
의 하위 요소를 설명합니다.
<TimeoutMs>
gRPC 요청에 대한 요청 제한 시간(밀리초)입니다. <TimeoutMs>
은 양수여야 합니다.
<GrpcConnection>
<GrpcConnection>
요소는 name
속성으로 지정된 기존 TargetServer
가 되도록 gRPC 서버를 설정합니다. TargetServer
리소스 참조 페이지를 참조하세요.
참고: TargetServer
의 프로토콜은 GRPC
여야 합니다.
다음 코드를 예로 들어 보겠습니다.
<GrpcConnection> <Server name="external-target-server"/> </GrpcConnection>
external-target-server
라는 기존 TargetServer
가 될 gRPC 서버를 지정합니다.
<Authentication>
요소(이 섹션의 뒷부분에서 설명)를 사용하여 Google에서 발급한 OpenID Connect 토큰을 생성하여 Cloud Run에서 호스팅되는 커스텀 서비스와 같은 gRPC 기반 서비스에 인증된 호출을 수행합니다.
다음 표에서는 <GrpcConnection>
의 하위 요소를 설명합니다.
하위 요소 | 필수 여부 | 설명 |
---|---|---|
<Server> 요소 |
필수 | gRPC 서버를 지정합니다. |
<Authentication> 요소 |
선택사항 | Google에서 발급한 OpenID Connect 토큰을 생성하여 Cloud Run과 같은 gRPC 기반 서비스에 인증된 호출을 수행합니다. |
<Server>
요소
gRPC 서버를 지정합니다.
다음 표에서는 <Server>
요소 속성을 설명합니다.
속성 | 설명 | 기본값 | 접속 상태 | 유형 |
---|---|---|---|---|
name |
요청을 전송할 gRPC 서버가 될 기존 |
해당 사항 없음 | 필수 | 문자열 |
<Authentication>
요소
Google에서 발급한 OpenID Connect 토큰을 생성하여 Cloud Run에서 호스팅되는 커스텀 서비스와 같은 gRPC 기반 서비스에 인증된 호출을 수행합니다. 이 요소를 사용하려면 Google 인증 사용에 설명된 설정과 배포 단계가 필요합니다. 올바르게 설정하면 정책에서 인증 토큰을 자동으로 만들어 서비스 요청에 추가합니다.
이 요소에는 필수 하위 요소 하나(GoogleIDToken
)가 있습니다.
기본값 | 해당 사항 없음 |
필수 여부 | 선택사항입니다. |
유형 | 복합 유형 |
상위 요소 | <GrpcConnection> |
하위 요소 |
<GoogleIDToken> |
Authentication
요소는 다음 구문을 사용합니다.
구문
<ExternalCallout> ... <GrpcConnection> <Server name="cloud_run_server_name"/> <Authentication> <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName> <GoogleIDToken> <Audience ref="variable-1">STRING</Audience> <IncludeEmail ref="variable-2">BOOLEAN</IncludeEmail> </GoogleIDToken> </Authentication> </GrpcConnection> </ExternalCallout>
예
다음 예시에서는 GoogleIDToken
요소를 보여줍니다.
<ExternalCallout continueOnError="false" enabled="true" name="External-Callout-1"> <DisplayName>External-Callout-1</DisplayName> <GrpcConnection> <Server name="cloud_run_server_name"/> <Authentication> <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication> </GrpcConnection> <TimeoutMs>5000</TimeoutMs> <Configurations> <Property name="with.request.content">true</Property> <Property name="with.request.headers">true</Property> <Property name="with.response.content">true</Property> <Property name="with.response.headers">true</Property> <FlowVariable>example.flow.variable</FlowVariable> <FlowVariable>another.flow.variable</FlowVariable> </Configurations> </ExternalCallout>
속성
없음
<HeaderName> 하위 요소
기본적으로 인증 구성이 있으면 Apigee는 Bearer 토큰을 생성하고 이를 대상 시스템으로 전송된 메시지의 Authorization
헤더에 삽입합니다.
HeaderName
요소를 사용하면 Bearer 토큰을 저장할 다른 헤더의 이름을 지정할 수 있습니다. 이 기능은 대상이 X-Serverless-Authorization
헤더를 사용하는 Cloud Run 서비스인 경우에 특히 유용합니다. Authorization
헤더가 있는 경우 수정되지 않은 상태로 유지되며 요청에도 전송됩니다.
기본값 | 해당 사항 없음 |
필수 여부 | 아니요 |
유형 | 문자열 |
상위 요소 | <Authentication> |
하위 요소 | 없음 |
HeaderName
요소는 다음 문법을 사용합니다.
구문
<ExternalCallout> ... <Authentication> <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName> <GoogleIDToken> ... </GoogleIDToken> </Authentication> ... </ExternalCallout>
정적 문자열 사용
이 예시에서는 생성된 Bearer 토큰이 기본적으로 대상 시스템으로 전송되는 X-Serverless-Authorization
이라는 헤더에 추가됩니다. Authorization
헤더가 있는 경우 수정되지 않은 상태로 유지되며 요청에도 전송됩니다.
<Authentication> <HeaderName>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication>
변수 참조 사용
이 예시에서는 생성된 Bearer 토큰이 기본적으로 대상 시스템으로 전송되는 X-Serverless-Authorization
이라는 헤더에 추가됩니다. my-variable
에 값이 있으면 기본 문자열 대신 해당 값이 사용됩니다. Authorization
헤더가 있는 경우 수정되지 않은 상태로 유지되며 요청에도 전송됩니다.
<Authentication> <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app</Audience> </GoogleIDToken> </Authentication>
<GoogleIDToken> 하위 요소
Google에서 발급한 OpenID Connect 토큰을 생성하여 Cloud Run에서 호스팅되는 커스텀 서비스와 같은 Google 서비스에 인증된 호출을 수행합니다.
기본값 | 해당 사항 없음 |
필수 여부 | 필수 |
유형 | 문자열 |
상위 요소 | <Authentication> |
하위 요소 | <Audience> <IncludeEmail> |
GoogleIDToken
요소는 다음 구문을 사용합니다.
구문
<ExternalCallout> ... <GrpcConnection> <Server name="cloud_run_server_name"/> <Authentication> <GoogleIDToken> <Audience ref="context-variable" useTargetUrl='BOOLEAN'>STRING</Audience> <IncludeEmail ref="context-variable">BOOLEAN</IncludeEmail> </GoogleIDToken> </Authentication> </GrpcConnection> </ExternalCallout>
예
다음 예시에서는 GoogleIDToken
요소를 보여줍니다.
<Authentication> <GoogleIDToken> <Audience>https://httpserver0-bar.run.app</Audience> <IncludeEmail>true</IncludeEmail> </GoogleIDToken> </Authentication>
<Audience> 하위 요소
토큰에서 액세스 권한을 부여하는 계정이나 API와 같은 생성된 인증 토큰의 대상입니다.
Audience
값이 비어 있으면 ref
가 비어 있거나 빈 값으로 확인되고, useTargetUrl
이 true
인 경우 'https://' + (gRPC 대상 서버의 호스트 이름)이 대상으로 사용됩니다.
예를 들어 서버의 호스트가 my-grpc-server-java.a.run.app
이면 사용되는 대상은 https://my-grpc-server-java.a.run.app
입니다.
useTargetUrl
의 기본값은 false
입니다.
<Audience>explicit-audience-value-here</Audience> or: <Audience ref='variable-name-here'/> or: <Audience ref='variable-name-here' useTargetUrl='true'/> or: <Audience useTargetUrl='true'/>
기본값 | 해당 사항 없음 |
필수 여부 | 필수 |
유형 | 문자열 |
상위 요소 | <GoogleIDToken> |
하위 요소 | 없음 |
<IncludeEmail> 하위 요소
true
로 설정하면 생성된 인증 토큰에 서비스 계정 email
및 email_verified
클레임이 포함됩니다.
기본값 | 거짓 |
필수 여부 | 선택사항 |
유형 | 불리언 |
상위 요소 | <GoogleIDToken> |
하위 요소 | 없음 |
<Configurations>
<Configurations>
요소를 사용하면 <Property>
및 <FlowVariable>
을 포함하여 ExternalCallout 정책의 여러 특성을 구성할 수 있습니다.
다음 표에서는 <Configurations>
의 하위 요소를 설명합니다.
하위 요소 | 필수 여부 | 설명 |
---|---|---|
<Property> |
필수 | 요청/응답 헤더 또는 콘텐츠가 서버로 전송되는지 여부를 지정합니다. 가능한 값은 |
<FlowVariable> |
필수 | 서버로 전송할 추가적인 흐름 변수를 지정합니다. |
<Property>
<Property>
요소는 요청/응답 헤더 또는 콘텐츠가 서버로 전송되는지 여부를 지정합니다. 가능한 값은 true
(항목이 전송됨) 또는 false
(항목이 전송되지 않음)입니다. 기본값은 false
입니다.
다음 표에서는 <Property>
요소 속성을 설명합니다.
속성 | 설명 | 기본값 | 접속 상태 | 유형 |
---|---|---|---|---|
name |
서버로 전송할 콘텐츠를 지정합니다.
|
해당 사항 없음 | 필수 | 문자열 |
<FlowVariable>
<FlowVariable>
요소는 서버로 전송할 추가적인 흐름 변수를 지정합니다. <FlowVariable>
값은 전체 변수 이름이 아닌 변수의 프리픽스입니다.
예를 들어 a.b.c
이면 a.b.c
라는 변수의 값이 서버에 전송됩니다. 마찬가지로 a.b.c.my-variable
라는 변수의 값이 서버로 전송됩니다. 하지만 a.x.another-variable
이라는 변수의 값은 a.b.c
프리픽스를 포함하지 않으므로 전송되지 않습니다. 예를 들면 다음과 같습니다.
<Configurations> <FlowVariable>a.b.c</FlowVariable> <FlowVariable>d.e.f</FlowVariable> </Configurations>
오류 참조
배포 오류
오류 이름 | 원인 |
---|---|
FAILED_PRECONDITION |
이 오류는 프록시가 <Authentication> 태그로 구성되었을 때 서비스 계정이 누락된 경우에 발생합니다.
예를 들면 다음과 같습니다. Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service account identity, but one was not provided with the request. |
PERMISSION_DENIED |
이 오류는 프록시가 <Authentication> 태그로 구성된 경우 서비스 계정에 권한 문제가 있으면 발생합니다. 가능한 원인은 다음과 같습니다.
|
런타임 오류
다음 표에서는 정책이 실행될 때 발생할 수 있는 런타임 오류를 설명합니다.
오류 코드 | HTTP 상태 | 원인 |
---|---|---|
GrpcTlsInitFailed |
500 |
이 오류는 gRPC 서버에서 TLS를 초기화할 때 키 저장소 또는 트러스트 저장소 문제와 같은 문제가 있을 때 발생합니다. |
steps.externalcallout.[error_code] |
500 |
|
steps.externalcallout.ExecutionError |
500 |
이 오류는 이 정책 실행 중 다른 예외 사항이 발생할 때 발생합니다. 기본 예외 사항은 오류 문자열로 노출됩니다. gRPC 서버에 대해 사용자 인증 정보 관련 문제가 있으면 오류가 다음과 같이 표시됩니다. { "fault": { "faultstring": "Encountered the following exception while sending the gRPC request or processing the response: [io.grpc.StatusRuntimeException: UNAVAILABLE: Credentials failed to obtain metadata].", "detail": { "errorcode": "steps.externalcallout.ExecutionError" } } } 추가 디버깅 포인터는 MP 로그에서 확인할 수 있습니다. |
googletoken.EmptyIDTokenAudience |
500 |
|
steps.externalcallout.ExecutionError
오류 문자열이 포함됩니다.
|
500 |
이 오류는 API 프록시가
|
PERMISSION DENIED 가 포함된 faultstring이 있는 steps.externalcallout.ExecutionError
예를 들어 faultstring은 Cloud Run의 경우 다음과 같이 표시됩니다.
|
500 |
이 오류는 API 프록시가
|
기타 오류
아래 표에서는 기타 오류에 대해 설명합니다. 자세한 내용은 원인을 참조하세요.
오류 코드 | 원인 |
---|---|
ReferencesExistToGrpcServer |
이 오류는 사용자가 gRPC 대상 서버를 삭제하려고 시도하지만 서버가 여전히 다른 정책에 사용되고 있을 때 발생합니다. |
오류
다음 표의 오류 변수는 기본적으로 모든 정책에 대해 설정되어 있습니다. 정책 오류 관련 변수를 참조하세요.
변수 | 위치 | 예시 |
---|---|---|
fault.name="fault_name" |
fault_name 은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. |
fault.name 은 'ExecutionError'와 일치합니다. |
externalcallout.[policy_name].failed |
policy_name 은 오류를 발생시킨 정책의 사용자 지정 이름입니다. |
externalcallout.ExternalCallout-1.failed = true |