확장 콜아웃 정책

<ph type="x-smartling-placeholder"></ph> 현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서. 정보

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

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

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

Extension콜아웃 정책에서 확장 프로그램에 액세스하려면 먼저 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 프록시 내에서 외부 리소스에 액세스하려면 ExtensionCallback 정책을 사용합니다.

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

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

PostClientFlow에서 확장 콜아웃 정책 사용

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

ExtensionCallback 정책을 사용하여 Google Cloud Logging 확장 프로그램을 호출하려는 경우 PostClientFlow에서 연결하려면 features.allowExtensionsInPostClientFlow 플래그가 조직에서 true(으)로 설정되어 있습니다.

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

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

PostClientFlow에서 MessageLogging 정책을 호출할 때의 모든 제한사항 확장 콜아웃 정책에도 적용됩니다 자세한 내용은 사용법 참고사항을 참조하세요.

요소 참조

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

&lt;ConnectorCallout&gt; 속성

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

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

&lt;Action&gt; 요소

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

<Action>action-exposed-by-extension</Action>

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

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

<커넥터> 요소

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

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

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

&lt;Input&gt; 요소

확장 프로그램으로 전송할 요청 본문이 포함된 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> 예에는 2개의 흐름 변수 참조가 포함되어 있습니다.

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

&lt;Output&gt; 요소

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

<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 정책을 사용하여 별도의 단계에서 응답 값을 파싱할 수도 있습니다.

&lt;Output&gt; 특성

흐름 변수

없음

오류 코드

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

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

런타임 오류

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

배포 오류

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