확장 콜아웃 정책

Apigee Edge 문서입니다.
Apigee X 문서로 이동 info

ExtensionCallout 정책을 사용하여 API 프록시에 확장 프로그램을 통합합니다.

확장 프로그램은 Apigee Edge 외부의 특정 리소스에 대한 액세스를 제공합니다. 리소스는 Cloud Storage 또는 Cloud Speech-to-Text와 같은 Google Cloud Platform 서비스일 수 있습니다. 하지만 리소스는 HTTP 또는 HTTPS를 통해 액세스할 수 있는 외부 리소스일 수 있습니다.

확장 프로그램 개요는 확장 프로그램이란 무엇인가요?를 참고하세요. 소개 튜토리얼은 튜토리얼: 확장 프로그램 추가 및 사용을 참고하세요.

ExtensionCallout 정책에서 확장 프로그램에 액세스하려면 먼저 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 확장 프로그램을 사용하는 전체 튜토리얼은 튜토리얼: 확장 프로그램 사용을 참고하세요.

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

ExtensionCallout 정책 정보

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

이 정책을 사용하려면 다음이 필요합니다.

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

PostClientFlow에서 ExtensionCallout 정책 사용

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

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

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

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

PostClientFlow에서 MessageLogging 정책을 호출하는 데 적용되는 모든 제한사항은 ExtensionCallout 정책에도 적용됩니다. 자세한 내용은 사용 참고사항을 참고하세요.

요소 참조

<?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>

<ConnectorCallout> 속성

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

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

<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>의 콘텐츠는 메시지 템플릿으로 처리됩니다. 즉 중괄호로 묶인 변수 이름이 런타임 시 참조된 변수의 값으로 대체됩니다.

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

<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 흐름 변수 값(with)

<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 -->

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

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

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

<Output> 속성

흐름 변수

없음

오류 코드

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

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

런타임 오류

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

배포 오류

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