ServiceCallout 정책

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

Apigee Edge 문서 보기

정책 아이콘

대상

ServiceCallout 정책을 사용하면 API 프록시 흐름에서 다른 서비스를 호출할 수 있습니다. 외부 서비스(예: 외부 RESTful 서비스 엔드포인트) 또는 내부 서비스(예: 동일한 조직 및 환경의 API 프록시)에 콜아웃을 만들 수 있습니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

  • 외부 사용 사례에서는 프록시 외부의 타사 API에 대한 콜아웃을 만듭니다. 타사 API의 응답은 파싱되어 API의 응답 메시지에 삽입되고 앱 최종 사용자를 위한 데이터를 보강하고 매시업합니다. 요청 흐름에서 ServiceCallout 정책을 사용하여 요청을 보낸 다음 응답의 정보를 API 프록시의 TargetEndpoint로 전달할 수도 있습니다.
  • 또 다른 사용 사례에서는 호출을 보내는 동일한 조직 및 환경에 있는 프록시를 호출합니다. 예를 들어 하나 이상의 다른 프록시가 소비하는 개별 하위 수준 기능을 사용하는 프록시가 있는 경우 이 방법이 유용할 수 있습니다. 예를 들어 백엔드 데이터 저장소와 함께 생성/읽기/업데이트/삭제 작업을 노출하는 프록시는 클라이언트에 데이터를 노출하는 다른 여러 프록시의 대상 프록시가 될 수 있습니다.

이 정책은 HTTP 및 HTTPS를 통한 요청을 지원합니다.

샘플

내부 프록시 로컬 호출

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

이 예시에서는 data-manager라는 로컬 API 프록시(즉, 동일한 조직 및 환경에 있는 프록시)에 대한 콜아웃을 만들어 이름이 default인 프록시 엔드포인트를 지정합니다.

변수로서의 URL

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

이 예시에서는 URL에 있는 변수를 사용하여 타겟의 URL을 동적으로 채웁니다. URL의 프로토콜 부분인 http://은 변수로 지정할 수 없습니다. 또한 URL의 도메인 부분과 그 외 부분에 별도의 변수를 사용해야 합니다.

Google Geocoding / 요청 정의

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

요청 객체를 생성하기 위해 AssignMessage 정책과 같은 정책을 사용하는 대신 ServiceCallout 정책에서 직접 정의할 수 있습니다. 이 예시에서 ServiceCallout 정책은 외부 서비스에 전달된 세 가지 쿼리 매개변수의 값을 설정합니다. ServiceCallout 정책에서 페이로드, 인코딩 유형(예: application/xml, 헤더, 양식 매개변수 등)을 지정하는 전체 요청 메시지를 만들 수 있습니다.

다음은 ServiceCallout 정책에 도달하기 전에 요청이 형성되는 또 다른 예시입니다.

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

요청 메시지의 내용은 GeocodingRequest라는 변수(예: AssignMessage 정책에 의해 채워질 수 있는 변수)에서 추출됩니다. 응답 메시지는 GeocodingResponse라는 변수에 할당되며 이 변수는 ExtractVariables 정책이나 자바스크립트 또는 자바로 작성된 커스텀 코드로 파싱될 수 있습니다. 정책은 Google Geocoding API의 응답을 30초 동안 기다린 후에 타임아웃됩니다.

대상 서버 호출

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

이 정책은 LoadBalancer 속성을 사용하여 대상 서버를 호출하고 서버 간 부하 분산을 수행합니다. 이 예시에서는 httpbin 및 yahoo라는 대상 서버 두 개에 부하가 분산됩니다. 프록시에 대상 서버를 설정하고 부하 분산을 구성하는 방법에 대한 자세한 내용은 백엔드 서버 간 부하 분산을 참조하세요.

ServiceCallout 정책 정보

API 프록시에서 ServiceCallout 정책을 사용할 수 있는 사례는 다양합니다. 예를 들어 외부 서비스에 호출을 수행하여 Geolocation 데이터, 고객 리뷰, 파트너의 소매 카탈로그 항목 등을 전달하기 위해 API 프록시를 구성할 수 있습니다.

콜아웃은 일반적으로 두 가지 정책 즉, AssignMessage 및 ExtractVariables와 함께 사용됩니다.

  • 요청: AssignMessage는 원격 서비스로 전송된 요청 메시지를 채웁니다.

  • 응답: ExtractVariables는 응답을 파싱하고 특정 콘텐츠를 추출합니다.

일반적인 ServiceCallout 정책 구성에는 다음이 포함됩니다.

  1. AssignMessage 정책: 요청 메시지를 만들고, HTTP 헤더 및 쿼리 매개변수를 채우고, HTTP 동사 설정 등을 수행합니다.

  2. ServiceCallout 정책: AssignMessage 정책으로 생성된 메시지를 참조하여 외부 호출의 대상 URL을 정의하고, 대상 서비스가 반환하는 응답 객체의 이름을 정의합니다.

    성능 향상을 위해 ServiceCallout 응답도 캐시할 수 있습니다(참조: ServiceCallout 정책의 결과를 캐시에 저장하려면 어떻게 해야 하나요? 나중에 캐시에서 데이터를 가져올 수 있나요?).

  3. ExtractVariables 정책: 일반적으로 ServiceCallout으로 생성된 메시지를 파싱하는 JSONPath 또는 XPath 표현식을 정의합니다. 그런 다음 정책은 ServiceCallout 응답에서 파싱된 값이 포함된 변수를 설정합니다.

커스텀 오류 처리

요소 참조

이 정책에 구성할 수 있는 요소와 속성은 다음과 같습니다.

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleAccessToken>
            <Scopes>
              <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
            </Scopes>
            <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds>
          </GoogleAccessToken>
        </Authentication>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleIDToken>
            <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience>
            <IncludeEmail ref="{variable}">true</IncludeEmail>
          </GoogleIDToken>
        </Authentication>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

<ServiceCallout> 속성

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.

속성 설명 기본값 Presence
name

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

 해당 사항 없음 필수
continueOnError

정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조:

 false 선택사항
enabled

정책을 시행하려면 true로 설정합니다.

정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

 true 선택사항
async

이 속성은 지원이 중단되었습니다.

 false 지원 중단됨

<DisplayName> 요소

name 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

<DisplayName>Policy Display Name</DisplayName>
기본값

해당 사항 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
Presence 선택사항
유형 문자열

<Request> 요소

API 프록시에서 다른 서비스로 전송되는 요청 메시지가 포함된 변수를 지정합니다. 이 변수는 흐름의 이전 정책에 의해 생성되거나 ServiceCallout 정책에서 인라인으로 만들 수 있습니다.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

<Remove>, <Copy>, <Add>, <Set> 태그의 구문은 AssignMessage 정책과 동일합니다.

요청 메시지를 확인할 수 없거나 잘못된 요청 메시지 유형인 경우 정책이 오류를 반환합니다.

가장 간단한 예시에서는 API 프록시의 흐름 초반부에 채워진 요청 메시지가 포함된 변수를 전달합니다.

<Request clearPayload="true" variable="myRequest"/>

또는 ServiceCallout 정책 자체에서 외부 서비스로 전송된 요청 메시지를 채울 수 있습니다.

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
기본값 Request(요청) 요소 또는 관련 속성을 생략하면 Apigee는 다음의 기본값을 할당합니다.

<Request clearPayload="true" variable="servicecallout.request"/>

이 기본값이 무엇을 의미하는지 살펴보겠습니다. 먼저 clearPayload=true는 ServiceCallout 정책이 실행될 때마다 새 요청 객체가 생성된다는 것을 의미합니다. 즉, 요청과 요청 URI 경로가 재사용되지 않습니다. 둘째, 기본 변수 이름 servicecallout.request는 이름을 제공하지 않는 경우 요청에 할당되는 예약된 이름입니다.

데이터 마스킹을 사용하는 경우 이 기본 이름을 알고 있어야 합니다. 변수 이름을 생략하면 servicecallout.request를 마스크 구성에 추가해야 합니다. 예를 들어 디버그 세션에 표시되지 않도록 승인 헤더를 마스크하길 원할 경우 기본 이름을 캡처하도록 마스킹 구성에 다음을 추가합니다.

servicecallout.request.header.Authorization.
Presence 선택사항
유형 해당 사항 없음

속성

속성 설명 기본값 Presence
변수

요청 메시지를 포함할 변수의 이름입니다.

 servicecallout.request 선택사항
clearPayload

true인 경우 요청 메시지에서 사용되는 메모리를 확보하기 위해 HTTP 대상으로 요청이 전송된 후 요청 메시지가 포함된 변수가 삭제됩니다.

ServiceCallout이 실행된 후 요청 메시지가 필요한 경우에만 clearPayload 옵션을 false로 설정합니다.

 true 선택사항

<Request>/<IgnoreUnresolvedVariables> 요소

true로 설정하면 정책은 요청에서 해결되지 않은 변수 오류를 무시합니다.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
기본값 false
Presence 선택사항
유형 부울

<Response> 요소

API 프록시 로직이 추가 처리를 위해 원격 호출의 응답이 필요한 경우 이 요소를 포함합니다.

이 요소가 있는 경우 외부 서비스에서 수신한 응답 메시지를 포함할 변수의 이름을 지정합니다. 대상의 응답은 정책에서 전체 응답을 성공적으로 읽는 경우에만 변수에 할당됩니다. 어떠한 이유로든 원격 호출이 실패하면 정책에서 오류를 반환합니다.

이 요소를 생략하면 API 프록시가 응답을 기다리지 않으며, API 프록시 흐름 실행은 모든 후속 흐름 단계를 통해 계속 진행됩니다. 또한 명확히 하자면 Response 요소가 없으면 대상의 응답을 후속 단계에 따라 처리할 수 없으며, 프록시 흐름에서 원격 호출의 실패를 감지할 방법이 없습니다. ServiceCallout을 사용할 때 Response 요소를 생략하는 것의 일반적인 용도는 외부 시스템에 로깅하기 위함입니다.

 <Response>calloutResponse</Response>
기본값 NA
Presence 선택사항
유형 문자열

<Timeout> 요소

ServiceCallout 정책이 대상의 응답을 대기하는 시간(밀리초)입니다. 런타임 시 이 값을 동적으로 설정할 수 없습니다. ServiceCallout이 제한 시간에 도달하면 오류 처리에 설명된 대로 HTTP 500이 반환되고, 정책이 실패하며, API 프록시는 오류 상태가 됩니다.

<Timeout>30000</Timeout>
기본값 55,000밀리초(55초), Apigee의 HTTP 제한 시간 기본 설정
Presence 선택사항
유형 정수

<HTTPTargetConnection> 요소

URL, TLS/SSL, HTTP 속성과 같은 전송 세부정보를 제공합니다. <TargetEndpoint> 구성 참조를 확인하세요.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>
기본값 해당 사항 없음
Presence 필수
유형 해당 사항 없음

<HTTPTargetConnection>/<Authentication> 요소

Google OAuth 2.0 또는 Google에서 발급한 OpenID Connect 토큰을 생성하여 특정 Cloud Functions 및 Cloud Run과 같은 Google Cloud 제품에서 실행되는 Google 서비스와 커스텀 서비스에 인증된 호출을 수행합니다. 이 요소를 사용하려면 Google 인증 사용에 설명된 설정과 배포 단계가 필요합니다. 올바르게 설정하면 정책에서 인증 토큰을 자동으로 만들어 서비스 요청에 추가합니다.

하위 요소 GoogleAccessToken 및 GoogleIDToken을 사용하면 Google OAuth 또는 OpenID Connect 토큰을 생성하도록 정책을 구성할 수 있습니다. 호출하려는 서비스 유형에 따라 이러한 하위 요소 중 하나를 선택해야 합니다.

ServiceCallout 정책은 HTTP 기반 서비스 호출만 지원합니다.

기본값 해당 사항 없음
필수 여부 선택사항.
유형 복합 유형
상위 요소 <HTTPTargetConnection>
하위 요소 <HeaderName>
<GoogleAccessToken>
<GoogleIDToken>

Authentication 요소는 다음 문법을 사용합니다.

구문

<ServiceCallout>
...
  <HTTPTargetConnection>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
        <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only
        if you want to limit the risk of leaked access tokens or improve performance. -->
        <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds>
      </GoogleAccessToken>

    --OR--
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </HTTPTargetConnection>
</ServiceCallout>

GoogleAccessToken 사용

다음 예시에서는 GoogleAccessToken 요소를 보여줍니다.

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

GoogleIDToken 사용

다음 예시에서는 GoogleIDToken 요소를 보여줍니다.

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>false</IncludeEmail>
  </GoogleIDToken>
</Authentication>

HeaderName 사용

다음 예시에서는 HeaderName 요소를 보여줍니다.

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

LifetimeInSeconds 사용

다음 예시에서는 HeaderName 요소를 보여줍니다.

  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
      <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>

속성

없음.

HeaderName 하위 요소

기본적으로 인증 구성이 있는 경우 Apigee는 Bearer 토큰을 생성하고 대상 시스템으로 전송되는 메시지의 Authorization 헤더에 삽입합니다. HeaderName 요소를 사용하면 해당 Bearer 토큰을 보유할 다른 헤더의 이름을 지정할 수 있습니다. 이 기능은 대상이 X-Serverless-Authorization 헤더를 사용하는 Cloud Run 서비스인 경우에 특히 유용합니다. Authorization 헤더가 있는 경우 수정되지 않은 상태로 유지되며 요청에도 전송됩니다.

기본값 해당 사항 없음
필수 여부 아니요
유형 문자열
상위 요소 <Authentication>
하위 요소 없음

HeaderName 요소는 다음 문법을 사용합니다.

구문

<ServiceCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

정적 문자열 사용

이 예시에서는 생성된 Bearer 토큰이 기본적으로 대상 시스템으로 전송되는 X-Serverless-Authorization이라는 헤더에 추가됩니다. Authorization 헤더가 있는 경우 수정되지 않은 상태로 유지되며 요청에도 전송됩니다.

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

변수 참조 사용

이 예시에서는 생성된 Bearer 토큰이 기본적으로 대상 시스템으로 전송되는 X-Serverless-Authorization이라는 헤더에 추가됩니다. my-variable에 값이 있으면 기본 문자열 대신 해당 값이 사용됩니다. Authorization 헤더가 있는 경우 수정되지 않은 상태로 유지되며 요청에도 전송됩니다.

<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

GoogleAccessToken 하위 요소

Google OAuth 2.0 토큰을 생성하여 Google 서비스에 인증된 호출을 수행합니다. Google OAuth 토큰은 Cloud Logging 및 Secret Manager와 같은 다양한 종류의 Google 서비스를 호출하는 데 사용될 수 있습니다.

기본값 해당 사항 없음
필수 여부 GoogleAccessToken 또는 GoogleIDToken 하위 요소가 있어야 합니다.
유형 문자열
상위 요소 <Authentication>
하위 요소 <Scopes>
<LifetimeInSeconds>

GoogleAccessToken 요소는 다음 구문을 사용합니다.

구문

<ServiceCallout>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
      <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing
      the default unless you want to limit the risk of leaked access tokens or improve performance. -->
      <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

예시 1

다음 예시에서는 GoogleAccessToken 요소를 보여줍니다.

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

예 2

다음 예시에서는 ServiceCallout 정책을 사용하여 보안 비밀을 검색하기 위해 secret manager에 연결하는 방법을 보여줍니다. 

<ServiceCallout name="ServiceCallout-sm">
  <Response>SecretManagerResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
  </HTTPTargetConnection>
</ServiceCallout>

예 3

다음 예시에서는 ServiceCallout 정책에서 Cloud Run에 대한 콜아웃을 수행하는 방법을 보여줍니다. 

<ServiceCallout name="ServiceCallout-CloudRun">
  <Response>CloudRunResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
      </GoogleIDToken>
    </Authentication>
    <URL>https://cloudrun-hostname.a.run.app/test</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Scopes 하위 요소

OAuth 2.0 액세스 토큰에 포함할 범위를 식별합니다. 자세한 내용은 Google API의 OAuth 2.0 범위를 참조하세요. 이 요소 아래에 <Scope> 하위 요소를 하나 이상 추가할 수 있습니다.

기본값 해당 사항 없음
필수 여부 필수
유형 문자열
상위 요소 <GoogleAccessToken>
하위 요소 <Scope>

Scope 하위 요소

유효한 Google API 범위를 지정합니다. 자세한 내용은 Google API의 OAuth 2.0 범위를 참조하세요.

기본값 해당 사항 없음
필수 여부 값을 하나 이상 입력해야 합니다.
유형 문자열
상위 요소 <Scopes>
하위 요소 없음.

LifetimeInSeconds 하위 요소

액세스 토큰의 전체 기간을 초 단위로 지정합니다.

기본값 3600
필수 여부 선택사항
유형 정수
상위 요소 <GoogleAccessToken>
하위 요소 없음.

GoogleIDToken 하위 요소

Google에서 발생한 OpenID Connect 토큰을 생성하여 Google 서비스에 인증된 호출을 수행합니다.

기본값 해당 사항 없음
필수 여부 GoogleAccessToken 또는 GoogleIDToken 하위 요소가 있어야 합니다.
유형 문자열
상위 요소 <Authentication>
하위 요소 <Audience>
<IncludeEmail>

GoogleIDToken 요소는 다음 문법을 사용합니다.

구문

<ServiceCallout>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
    </GoogleIDToken>
  </Authentication>
</ServiceCallout>

예시 1

다음 예시에서는 GoogleIDToken 요소를 보여줍니다.

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>true</IncludeEmail>
  </GoogleIDToken>
</Authentication>

Audience 하위 요소

토큰에서 액세스 권한을 부여하는 계정이나 API와 같은 생성된 인증 토큰의 대상입니다.

Audience 값이 비어 있거나 ref 변수가 유효한 값으로 확인되지 않고 useTargetUrl이 true인 경우 대상의 URL(쿼리 매개변수 제외)이 잠재고객으로 사용됩니다. 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 클레임이 포함됩니다.

기본값 false
필수 여부 선택사항
유형 불리언
상위 요소 <GoogleIDToken>
하위 요소 없음.

<HTTPTargetConnection>/<URL> 요소

호출되는 서비스의 URL입니다.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

변수를 통해 URL의 일부를 동적으로 제공할 수 있습니다. 그러나 아래의 URL http://의 프로토콜 부분은 변수로 지정될 수 없습니다. 다음 예시에서는 변수를 사용하여 쿼리 매개변수의 값을 지정합니다.

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

또는 변수를 사용하여 URL 경로의 일부를 설정합니다.

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

변수를 사용하여 URL의 도메인과 포트를 지정하려면 도메인 및 포트에만 첫 번째 변수를 사용하고 URL의 다른 부분에 두 번째 변수를 사용합니다.

<URL>http://{request.dom_port}/{request.resourcePath}</URL>
기본값 해당 사항 없음
Presence 필수
유형 문자열

<HTTPTargetConnection>/<SSLInfo> 요소

백엔드 서비스에 대한 TLS/SSL 구성입니다. TLS/SSL 구성에 대한 도움말은 API 프록시 구성 참조에서 TLS 구성 옵션 및 'TLS/SSL TargetEndpoint 구성'을 참조하세요.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>
기본값 해당 사항 없음
Presence 선택사항
유형 해당 사항 없음

<HTTPTargetConnection>/<Properties> 요소

백엔드 서비스로의 HTTP 전송 속성입니다. 자세한 내용은 엔드포인트 속성 참조를 확인하세요.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>
기본값 해당 사항 없음
Presence 선택사항
유형 해당 사항 없음

<HTTPTargetConnection>/<LoadBalancer> 요소

하나 이상의 대상 서버를 호출하고 서버에서 부하 분산을 수행합니다. 샘플 섹션에서 호출 대상 서버 샘플을 참조하세요. 백엔드 서버 간 부하 분산도 참조하세요. ServiceCallout 정책과 경로 규칙을 사용하여 대상 서버를 호출하는 방법을 설명하는 대상 엔드포인트/서버 콜아웃도 참조하세요.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
기본값 해당 사항 없음
Presence 선택사항
유형 해당 사항 없음

<LocalTargetConnection> 요소

로컬 프록시(즉, 동일한 조직 및 환경의 프록시)를 서비스 콜아웃의 대상으로 지정합니다.

타겟을 추가로 지정하려면 <APIProxy> 또는 <ProxyEndpoint> 요소를 사용하거나 <Path> 요소를 사용합니다.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>
기본값 해당 사항 없음
Presence 필수
유형 해당 사항 없음

<LocalTargetConnection>/<APIProxy> 요소

로컬 호출의 타겟인 API 프록시의 이름입니다. 프록시는 호출을 수행하는 프록시와 동일한 조직 및 환경에 있어야 합니다.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<APIProxy> 요소와 함께 <ProxyEndpoint> 요소를 포함하여 호출의 대상이어야 하는 프록시 엔드포인트의 이름을 지정합니다.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>
기본값 해당 사항 없음
Presence 필수
유형 문자열

<LocalTargetConnection>/<ProxyEndpoint> 요소

호출 대상이어야 하는 프록시 엔드포인트의 이름입니다. 이는 <APIProxy> 요소로 지정된 API 프록시의 프록시 엔드포인트입니다.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
기본값 해당 사항 없음
Presence 선택사항
유형 해당 사항 없음

<LocalTargetConnection>/<Path> 요소

대상이 되는 엔드포인트의 경로입니다. 엔드포인트는 호출을 수행하는 프록시와 동일한 조직 및 환경의 프록시를 참조해야 합니다.

프록시 이름을 모르거나 의존할 수 없는 경우 <APIProxy>/<ProxyEndpoint> 쌍 대신 이를 사용하세요. 경로가 안정적인 대상일 수 있습니다.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>
기본값 해당 사항 없음
Presence 선택사항
유형 해당 사항 없음

스키마

흐름 변수

흐름 변수를 사용하면 HTTP 헤더, 메시지 콘텐츠 또는 흐름 컨텍스트를 기반으로 런타임 시 정책 및 흐름의 동적 동작을 사용 설정할 수 있습니다. ServiceCallout 정책이 실행된 후에 다음과 같은 사전 정의된 흐름 변수를 사용할 수 있습니다. 흐름 변수에 대한 자세한 내용은 흐름 변수 참조를 참조하세요.

ServiceCallouts에는 자체 요청과 응답이 있으며 변수를 통해 해당 데이터에 액세스할 수 있습니다. 기본 메시지는 request.* 및 response.* 변수 프리픽스를 사용하므로 myrequest.* 및 calloutResponse.* 프리픽스(ServiceCallout 구성의 기본값)를 사용하여 ServiceCallout 관련 메시지 데이터를 가져옵니다. 다음 표의 첫 번째 예시는 ServiceCallout에서 HTTP 헤더를 가져오는 방법을 보여줍니다.

변수 설명

다음은 ServiceCallout 요청과 응답 헤더를 가져오는 예시로 기본 요청 및 응답에서 헤더를 가져오는 방식과 유사합니다.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

여기서 calloutResponse는 Service Callout의 Response 변수 이름이고 myRequest는 Request 변수 이름입니다. 예를 들면 다음과 같습니다.

calloutResponse.header.Content-Length

ServiceCallout 응답의 Content-Length 헤더를 반환합니다.

범위: ServiceCallout 전달부터
유형: 문자열
권한: 읽기/쓰기

ServiceCallout 요청 또는 응답의 메시지 헤더입니다. 예를 들어 API 프록시 대상이 http://example.com이고 ServiceCallout 대상이 http://mocktarget.apigee.net인 경우 이러한 변수는 http://mocktarget.apigee.net에 대한 콜아웃의 헤더입니다.
servicecallout.requesturi

범위: ServiceCallout 요청부터
유형: 문자열
권한: 읽기/쓰기

ServiceCallout 정책의 TargetEndpoint URI입니다. URI는 프로토콜 및 도메인 사양이 없는 TargetEndpoint URL입니다.
servicecallout.{policy-name}.target.url

범위: ServiceCallout 요청부터
유형: 문자열
권한: 읽기/쓰기

ServiceCallout의 대상 URL입니다.

calloutResponse.content

여기서 calloutResponse는 ServiceCallout 구성에서의 <Response> 변수 이름입니다.

범위: ServiceCallout 응답부터
유형: 문자열
권한: 읽기/쓰기

ServiceCallout의 응답 본문입니다.
servicecallout.{policy-name}.expectedcn

범위: ServiceCallout 요청부터
유형: 문자열
권한: 읽기/쓰기

ServiceCallout 정책에서 참조하는 TargetEndpoint의 일반적인 예상 이름입니다. 이는 TargetEndpoint가 TLS/SSL 엔드포인트를 참조하는 경우에만 의미가 있습니다.
servicecallout.{policy-name}.failed

범위: ServiceCallout 응답부터
유형: 부울
권한: 읽기/쓰기

정책의 성공, 참, 실패, 거짓 여부를 나타내는 부울입니다.

오류

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드 HTTP 상태 원인 수정
steps.servicecallout.ExecutionFailed 500

이 오류는 다음과 같은 때에 발생할 수 있습니다.

  • 정책이 잘못된 형식이나 유효하지 않은 입력을 처리하도록 요청받았을 때.
  • 백엔드 대상 서비스가 오류 상태를 반환할 때(기본적으로 4xx 또는 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 정책에 지정된 Request 변수가 Message 유형이 아닙니다. 예를 들어 문자열이거나 기타 메시지 외 유형인 경우 이 오류가 표시됩니다.
steps.servicecallout.RequestVariableNotRequestMessageType 500 정책에 지정된 Request 변수가 RequestMessage 유형이 아닙니다. 예를 들어 응답 유형인 경우 이 오류가 표시됩니다.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken>은 사용 설정되지만 useTargetUrl은 false로 설정되며 오류가 발생할 때 직접 또는 참조를 통해 <Audience>에 값이 제공되지 않습니다.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 이 오류는 API 프록시가 <Authentication> 요소로 구성된 경우에 발생할 수 있습니다. 원인은 다음과 같습니다.
  • 서비스 계정이 프록시로 배포되었습니다.
    • 프로젝트에 없음
    • 중지됨
    • (Apigee Hybrid만 해당) apigee-runtime 서비스 계정에 대한 roles/iam.serviceAccountTokenCreator 역할이 부여되지 않았습니다.
  • IAMCredentials API가 apigee-runtime 서비스 계정의 소스 프로젝트에서 중지됩니다.
  • <GoogleAccessToken> 요소가 사용되고 잘못된 범위가 하나 이상 제공됩니다. 예를 들어 오타나 빈 범위가 있는지 확인합니다.

    • Apigee Hybrid의 경우 문제 디버깅에 도움이 될 수 있는 보다 자세한 오류 메시지를 찾으려면 런타임 컨테이너 로그에서 GoogleTokenGenerationFailure를 찾습니다.

    배포 오류

    이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

    오류 이름 원인 수정
    URLMissing <HTTPTargetConnection> 내의 <URL> 요소가 없거나 비어 있습니다.
    ConnectionInfoMissing 이 오류는 정책에 <HTTPTargetConnection> 또는 <LocalTargetConnection> 요소가 없는 경우 발생합니다.
    InvalidTimeoutValue 이 오류는 <Timeout> 값이 음수이거나 0이면 발생합니다.
    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> 태그로 구성된 경우 서비스 계정에 권한 문제가 있으면 발생합니다. 가능한 원인은 다음과 같습니다.
    • 서비스 계정이 없습니다.
    • Apigee 조직과 동일한 Google Cloud 프로젝트에서 서비스 계정이 생성되지 않았습니다.
    • 배포자에게 서비스 계정에 대한 iam.serviceAccounts.actAs 권한이 없습니다. 자세한 내용은 서비스 계정 권한 정보를 참고하세요.

    오류 변수

    이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

    변수 장소 예
    fault.name="fault_name" fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. servicecallout.SC-GetUserData.failed = true

    오류 응답 예시

    {
   "fault":{
      "detail":{
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]:
            request variable data_str value is not of type Message"
   }
}

    오류 규칙 예시

    <FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

    관련 주제