확장 콜아웃 정책

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동
정보

확장 프로그램을 API 프록시에 통합하려면 Extension콜아웃 정책을 사용하세요.

확장 프로그램은 Apigee Edge 외부의 특정 리소스에 대한 액세스 권한을 제공합니다. 리소스는 Cloud Storage 또는 Cloud Speech-to-Text와 같은 Google Cloud Platform 서비스일 수 있습니다. 그러나 리소스는 HTTP 또는 HTTPS를 통해 액세스할 수 있는 외부 리소스라면 무엇이든 될 수 있습니다.

확장 프로그램에 관한 개요는 확장 프로그램이란 무엇인가요?를 참고하세요. 입문 가이드는 튜토리얼: 확장 프로그램 추가 및 사용을 참조하세요.

확장 프로그램 콜아웃 정책에서 확장 프로그램에 액세스하려면 먼저 Apigee Edge 조직에 이미 설치된 확장 프로그램 패키지의 확장 프로그램을 추가, 구성, 배포해야 합니다.

샘플

다음은 Cloud Logging 확장 프로그램과 함께 사용할 정책 예입니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

Cloud Logging 확장 프로그램 사용에 관한 전체 가이드는 튜토리얼: 확장 프로그램 사용을 참조하세요.

사용 가능한 모든 확장 프로그램의 예는 확장 프로그램 참조 개요를 참고하세요.

확장 콜아웃 정책 정보

구성된 확장 프로그램을 사용하여 API 프록시 내에서 외부 리소스에 액세스하려면 ExtensionCall 정책을 사용합니다.

이 정책을 사용하기 전에 다음 항목이 필요합니다.

  • 이 정책에서 액세스할 외부 리소스에 대한 몇 가지 세부정보입니다. 이러한 세부정보는 리소스에 따라 다릅니다. 예를 들어 정책이 Cloud Firestore 데이터베이스에 액세스하는 경우 만들거나 액세스하려는 컬렉션 및 문서 이름을 알아야 합니다. 일반적으로 이 정책의 요청 및 응답 처리를 구성할 때 리소스별 정보를 사용합니다.
  • API 프록시가 배포될 환경에 추가, 구성, 배포된 확장 프로그램 즉, 이 정책을 사용하여 특정 Google Cloud 서비스에 액세스하려면 해당 서비스에 대해 배포된 확장 프로그램이 사용자 환경에 있어야 합니다. 구성 세부정보에는 일반적으로 프로젝트 ID 또는 계정 이름과 같이 리소스에 대한 액세스 범위를 좁히는 데 필요한 정보가 포함됩니다.

PostClientFlow에서 ExtensionCall 정책 사용

API 프록시의 PostClientFlow에서 ExtensionCall 정책을 호출할 수 있습니다. PostClientFlow는 응답이 요청하는 클라이언트로 전송된 후 실행되므로 모든 측정항목을 로깅에 사용할 수 있습니다. PostClientFlow 사용에 대한 자세한 내용은 API 프록시 구성 참조를 확인하세요.

확장 콜아웃 정책을 사용하여 PostClientFlow에서 Google Cloud Logging 확장 프로그램을 호출하려면 조직에서 features.allowExtensionsInPostClientFlow 플래그가 true로 설정되어 있는지 확인합니다.

  • 퍼블릭 클라우드용 Apigee Edge 고객인 경우 features.allowExtensionsInPostClientFlow 플래그가 기본적으로 true로 설정됩니다.

  • 프라이빗 클라우드용 Apigee Edge 고객인 경우 조직 속성 업데이트 API를 사용하여 features.allowExtensionsInPostClientFlow 플래그를 true로 설정합니다.

PostClientFlow에서의 MessageLogging 정책 호출에 대한 모든 제한사항은 ExtensionCall 정책에도 적용됩니다. 자세한 내용은 사용법 메모를 참고하세요.

요소 참조

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

<Connector callout> 속성

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

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

속성 설명 기본 계정 현재 상태
name

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

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

N/A 필수
continueOnError

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

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

false 선택사항
enabled

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

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

true 선택사항
async

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

false 지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>
기본 계정

N/A

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.

현재 상태 선택사항
유형 문자열

<Action> 요소

정책에서 호출해야 하는 확장 프로그램 노출 작업입니다.

<Action>action-exposed-by-extension</Action>
기본 계정 없음
상태 필수
유형 문자열

각 확장 프로그램은 확장 프로그램이 나타내는 리소스의 기능에 대한 액세스를 제공하는 자체 작업 집합을 노출합니다. 작업은 이 정책을 사용해 호출하는 함수로 생각할 수 있으며 <Input> 요소의 콘텐츠를 사용하여 함수의 인수를 지정합니다. 작업의 응답은 <Output> 요소를 사용하여 지정하는 변수에 저장됩니다.

확장 프로그램의 함수 목록은 이 정책에서 호출하는 확장 프로그램의 참조를 확인하세요.

<Connector> 요소

사용하도록 구성된 확장 프로그램의 이름입니다. 환경에 배포하기 위해 확장 프로그램을 구성했을 때 확장 프로그램에 지정된 환경 범위 이름입니다.

<Connector>name-of-configured-extension</Connector>

기본 계정 없음
상태 필수
유형 문자열

확장 프로그램에 동일한 확장 프로그램 패키지를 기반으로 배포된 다른 확장 프로그램과 다를 수 있는 구성 값이 있습니다. 이러한 구성 값은 동일한 패키지에서 구성된 확장 프로그램 간의 런타임 기능에서 중요한 차이를 나타낼 수 있으므로 호출할 올바른 확장 프로그램을 지정해야 합니다.

<Input> 요소

확장 프로그램에 전송할 요청 본문이 포함된 JSON입니다.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

기본 계정 없음
상태 확장 프로그램에 따라 선택사항 또는 필수 항목입니다.
유형 문자열

이는 기본적으로 <Action> 요소를 사용하여 지정하는 작업의 인수입니다. <Input> 요소의 값은 호출하는 확장 프로그램과 작업에 따라 다릅니다. 각 작업의 속성에 관한 자세한 내용은 확장 프로그램 패키지 문서를 참고하세요.

많은 <Input> 요소 값이 <![CDATA[]]> 섹션으로 묶여 있지 않아도 올바르게 작동하지만 JSON 규칙에서는 XML로 파싱되지 않는 값을 허용합니다. 런타임 파싱 오류를 방지하기 위해 JSON을 CDATA 섹션으로 포함하는 것이 좋습니다.

<Input> 요소의 값은 호출할 확장 프로그램 작업으로 전송할 값을 해당 속성이 지정하는 올바른 형식의 JSON입니다. 예를 들어 Google Cloud Logging 확장 프로그램 확장 프로그램의 log 작업은 쓸 로그 (logName), 항목과 함께 포함할 메타데이터 (metadata), 로그 메시지 (data)를 지정하는 값을 사용합니다. 다음은 예시입니다.

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

<Input> JSON에서 흐름 변수 사용

<Input>의 콘텐츠는 메시지 템플릿으로 취급됩니다. 즉, 중괄호로 묶인 변수 이름은 런타임 시 참조된 변수의 값으로 대체됩니다.

예를 들어 client.ip 흐름 변수를 사용하여 API 프록시를 호출하는 클라이언트의 IP 주소를 가져오도록 위의 <Input> 블록을 다시 작성할 수 있습니다.

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

런타임 시 JSON의 속성 값을 따옴표로 묶으려면 JSON 코드에 따옴표를 사용해야 합니다. 이는 런타임 시 확인할 JSON 속성 값으로 흐름 변수를 지정하는 경우에도 마찬가지입니다.

다음 <Input> 예에는 흐름 변수 참조 두 개가 포함되어 있습니다.

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

런타임 시 JSON 속성 값은 다음과 같이 확인됩니다.

  • logName 속성 값 -- 문자열 리터럴 example-log입니다.
  • metadata 속성 값: 따옴표가 없는 my.log.entry.metadata 흐름 변수 값입니다. 이는 변수 값 자체가 객체를 나타내는 JSON인 경우에 유용할 수 있습니다.
  • message 속성 값: 따옴표가 있는 client.ip 흐름 변수 값입니다.

<Output> 요소

확장 프로그램 작업의 응답을 저장하는 변수 이름입니다.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

또는

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

기본 계정 없음
상태 확장 프로그램에 따라 선택사항 또는 필수 항목입니다.
유형 파싱된 객체 또는 문자열이며, parsed 속성 설정에 따릅니다.

응답이 수신되면 여기에서 지정한 변수에 응답 값이 배치되며, 다른 API 프록시 코드에서 응답 값에 액세스할 수 있습니다.

확장 프로그램 응답 객체는 JSON 형식입니다. 정책에서 JSON을 처리하는 방식에는 두 가지 옵션이 있습니다.

  • 파싱됨 (기본값): 정책이 JSON 객체를 파싱하고 JSON 데이터로 변수를 자동으로 생성합니다. 예를 들어 JSON에 "messageId" : 12345;가 포함되어 있고 출력 변수의 이름을 extensionOutput로 지정하면 다른 정책에서 {extensionOutput.messageId} 변수를 사용하여 이 메시지 ID에 액세스할 수 있습니다.
  • 파싱되지 않음: 출력 변수에 확장 프로그램의 파싱되지 않은 원시 JSON 응답이 포함됩니다. (원하는 경우 자바스크립트 정책을 사용하여 별도의 단계에서 응답 값을 파싱할 수 있습니다.)

<출력> 속성

속성 설명 기본 계정 상태
파싱됨 확장 프로그램에서 반환된 JSON 객체를 파싱하여 JSON 객체의 데이터에 다른 정책의 변수로 액세스할 수 있도록 합니다. true 선택사항

흐름 변수

없음

오류 코드

Apigee Edge 정책에서 반환되는 오류는 정책 오류 참조에 설명된 일관된 형식을 따릅니다.

이 섹션에서는 이 정책이 오류를 트리거할 때 설정되는 오류 메시지 및 흐름 변수에 대해 설명합니다. 이 정보는 프록시에 대한 오류 규칙을 개발하고 있는지 확인하는 데 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항오류 처리를 참조하세요.

런타임 오류

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

오류 이름 HTTP 상태 원인
ExecutionFailed 500 확장 프로그램에서 오류로 응답합니다.

배포 오류

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

오류 이름 발생 상황 수정
InvalidConnectorInstance <Connector> 요소가 비어 있습니다.
ConnectorInstanceDoesNotExists <Connector> 요소에 지정된 확장 프로그램이 환경에 존재하지 않습니다.
InvalidAction Extension 콜아웃 정책의 <Action> 요소가 없거나 빈 값으로 설정되었습니다.
AllowExtensionsInPostClientFlow PostClient Flow에는 Extension콜 정책을 포함할 수 없습니다.