DataCapture 정책

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

Apigee Edge 문서를 보세요.

DataCapture 아이콘

개요

DataCapture 정책은 분석에 사용할 API 프록시에서 데이터(예: 페이로드, HTTP 헤더, 경로 또는 쿼리 매개변수)를 캡처합니다. 커스텀 애널리틱스 보고서에서 캡처된 데이터를 사용할 수 있을 뿐만 아니라 Sense, 수익 창출 및 Monitoring 규칙을 구현할 수 있습니다.

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

데이터 수집기 리소스

DataCapture 정책을 사용하려면 먼저 데이터 수집기 리소스를 만들어야 합니다. Apigee UI 및 Apigee API 중 하나를 사용하여 데이터 수집기 리소스를 만드는 단계는 데이터 수집기 만들기를 참조하세요.

<DataCapture>

<DataCapture> 요소는 DataCapture 정책을 정의합니다.

<DataCapture async="true" continueOnError="true" enabled="true" name="DC">

DataCapture 정책 예시는 다음과 같습니다.

<DataCapture name="DC-1">
    <Capture>
        <DataCollector>dc_data_collector</DataCollector>
        <Collect ref="my_data_variable" />
    </Capture>
</DataCapture>

DataCapture 정책의 기본 요소는 <Capture> 요소이며 이 요소에서 데이터 캡처 방법을 지정합니다. 여기에는 두 가지 필수 하위 요소가 있습니다.

이 간단한 예시에서는 데이터가 프록시의 다른 곳에서 생성된 my_data_variable이라는 변수에서 추출됩니다. 변수는 ref 속성에서 지정됩니다.

또한 <Collect> 요소는 하위 요소를 통해 다양한 소스의 데이터를 캡처하는 여러 가지 방법을 제공합니다. DataCapture 정책으로 데이터를 캡처하는 더 많은 예시를 보려면 예시를 참조하세요.

DataCapture 요소에는 다음 구문이 있습니다.

<DataCapture name="capturepayment" continueOnError="false" enabled="true"> 
  <DisplayName>Data-Capture-Policy-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

  <!-- Existing Variable -->
  <Capture>
    <Collect ref="existing-variable" default="0"></Collect>
    <DataCollector>dc_1</DataCollector>
  </Capture>

  <!-- JSONPayload -->
  <Capture>
    <DataCollector>dc_2</DataCollector>
    <Collect default="0">
      <Source>request</Source>
      <JSONPayload>
        <JSONPath>result.var</JSONPath>
      </JSONPayload>
    </Collect>
  </Capture>

  <!-- URIPath -->
  <Capture>
    <DataCollector>dc_3</DataCollector>
    <Collect default="0">
      <URIPath>
        <!-- All patterns must specify a single variable to extract named $ -->
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
        <Pattern ignoreCase="false">/foo/bar/{$}</Pattern>
      </URIPath>
    </Collect>
  </Capture>
</DataCapture>

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

속성 기본 필수 여부 설명
name 해당 없음 필수

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

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.
continueOnError false 선택 정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조:
enabled true 선택 정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
async   false 지원 중단됨 이 속성은 지원이 중단되었습니다.

다음 표에서는 <DataCapture> 하위 요소를 간략하게 설명합니다.

하위 요소 필수 설명
<Capture> 필수 지정된 변수의 데이터를 캡처합니다.

예시

다음 예시에서는 DataCapture 정책을 사용하는 다양한 방법을 보여줍니다.

기본 제공 변수의 데이터 캡처

다음 코드 샘플에서는 요청, 응답 또는 오류 메시지의 콘텐츠가 포함된 기본 제공 변수 message.content의 데이터를 캡처하는 방법을 보여줍니다. 기본 제공 변수에 대한 자세한 내용은 흐름 변수를 참조하세요.

<DataCapture name="DC-FullMessage">
    <Capture>
        <DataCollector>dc_data_collector</DataCollector>
        <Collect ref="message.content" />
    </Capture>
</DataCapture>

위 코드에서 </Collect> 요소의 ref 속성은 캡처할 변수를 지정합니다. 이 예시에서는 이름이 "message.content"입니다.

이 샘플에서는 데이터 수집기 리소스 이름을 지정하는 <DataCollector> 요소도 포함된 <Capture> 요소를 사용하여 데이터를 캡처합니다.

데이터 인라인 캡처

다음 예시에서는 <Collect> 요소의 하위 요소인 <JSONPayload>를 사용하여 데이터 인라인을 캡처하는 방법을 보여줍니다.

<DataCapture name="DC-Currency">
    <Capture>
        <DataCollector>dc_data_collector<DataCollector>
        <Collect>
            <JSONPayload>
                <JSONPath>$.results[0].currency</JSONPath>
            </JSONPayload>
        </Collect>
    </Capture>
</DataCapture>

위 코드에서 다음이 수행됩니다.

  • <JSONPayload> 요소는 변수 값이 추출되는 JSON 형식 메시지를 지정합니다.
  • <JSONPath> 요소는 메시지에서 값을 추출하는 데 사용되는 JSON 경로를 지정합니다. 이 경우에는 $.results[0].currency입니다.

예를 들어 메시지가 수신될 때 추출된 값이 1120이라고 가정해 보겠습니다. 그러면 애널리틱스에 전송되는 결과 항목은 다음과 같습니다.

{
    "dc_data_collector": "1120"
}

<Capture>

<Capture> 요소는 데이터 캡처 방법을 지정합니다.

<Capture />

다음 표에서는 <Capture> 하위 요소를 간략하게 설명합니다.

하위 요소 필수 여부 설명
<DataCollector> 필수 데이터 수집기 리소스를 지정합니다.
<Collect> 필수 데이터 캡처 방법을 지정합니다.

<DataCollector>

<DataCollector> 요소는 데이터 수집기 리소스를 지정합니다.

<DataCollector>dc_data_collector</DataCollector>
다음 표에서는 <DataCollector> 요소 속성을 설명합니다.
속성 설명 기본값 필수 여부 유형
범위

수익 창출 변수를 캡처하려면 이 속성을 지정하고 값을 monetization으로 설정합니다. 캡처할 수 있는 수익 창출 변수에 대한 자세한 내용은 수익 창출 데이터 캡처를 참조하세요.

 해당 없음 선택사항 문자열

<DataCollector> 요소 본문에는 데이터 수집기 리소스 이름이 포함됩니다.

<Collect>

<Collect> 요소는 데이터 캡처 방법을 지정합니다.

<Collect ref="existing-variable" default="0"/>

다음 표에서는 <Collect> 요소 속성을 설명합니다.

속성 설명 기본값 필수 여부 유형
참조

데이터를 캡처하는 변수입니다.

 해당 사항 없음 선택사항—ref를 생략하면 QueryParam, Header, FormParam, URIPath, JSONPayload 또는 XMLPayload 중 하나를 정확하게 지정해야 합니다. 문자열
기본값 런타임 시 변수 값이 채워지지 않으면 애널리틱스로 전송되는 값을 지정합니다. 예를 들어 default="0"을 설정하면 애널리틱스에 전송된 값은 0이 됩니다. default 값을 지정하지 않고 런타임 시 변수 값이 채워지지 않으면 애널리틱스로 전송된 값은 숫자 변수의 경우 null, 문자열 변수의 경우 "Not set"이 됩니다. 필수 문자열

ref 속성이나 하위 요소 <Collect>를 사용하여 기존 변수에서 데이터를 캡처할 수 있습니다.

<Collect> 하위 요소

다음 표에서는 <Collect> 하위 요소를 간략하게 설명합니다.

하위 요소 필수 여부 설명
<Source> 선택사항 파싱할 변수를 지정합니다.
<URIPath> 선택사항 요청 소스 메시지의 proxy.pathsuffix에서 값을 추출합니다.
<QueryParam> 선택사항 요청 소스 메시지의 지정된 쿼리 매개변수에서 값을 추출합니다.
<Header> 선택사항 지정된 요청 또는 응답 메시지의 지정된 HTTP 헤더에서 값을 추출합니다.
<FormParam> 선택사항 지정된 요청 또는 응답 메시지의 지정된 양식 매개변수에서 값을 추출합니다.
<JSONPayload> 선택사항 변수 값을 추출할 JSON 형식의 메시지를 지정합니다.
<XMLPayload> 선택사항 변수 값을 추출할 XML 형식의 메시지를 지정합니다.

<Source>

파싱할 변수를 지정합니다. <Source>의 기본값은 message입니다. message 값은 상황에 따라 다릅니다. 요청 흐름에서 message는 요청 메시지로 확인됩니다. 응답 흐름에서 message는 응답 메시지로 확인됩니다.

이 정책을 사용하여 요청 또는 응답 메시지에서 정보를 추출하는 경우가 많지만 모든 변수에서 정보를 추출하는 데 사용할 수 있습니다. 예를 들어 AccessEntity 정책에서 생성된 항목 및 서비스 콜아웃 정책에서 반환한 데이터에서 정보를 추출하거나 XML 또는 JSON 객체에서 정보를 추출하는 데 사용할 수 있습니다.

<Source>를 확인할 수 없거나 메시지가 아닌 유형으로 확인되면 정책이 응답하지 않습니다.

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

속성

속성 설명 기본값 필수 여부 유형
clearPayload

여기에서 데이터를 추출한 후 <Source>에 지정된 페이로드를 삭제하려면 true로 설정합니다.

ExtractVariables를 실행한 후 소스 메시지가 필요하지 않은 경우에만 <clearPayload> 옵션을 사용합니다. true로 설정하면 메시지에 사용되는 메모리를 확보할 수 있습니다.

false

 선택사항 불리언 
<Source clearPayload="true|false">request</Source>

<URIPath>

request 소스 메시지의 proxy.pathsuffix에서 값을 추출합니다. 패턴에 적용된 경로는 proxy.pathsuffix이며 여기에는 API 프록시의 기본 경로가 포함되지 않습니다. 소스 메시지가 response 메시지 유형으로 확인되면 요소에서 아무 작업도 수행하지 않습니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 복합
상위 요소 <Collect>
하위 요소 <Pattern>

속성

속성 설명 기본값 필수 여부 유형
ignoreCase 패턴이 일치할 경우 대소문자를 무시하도록 지정합니다.

false

 선택사항 불리언 
<Collect>
    <URIPath>
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
    </URIPath>
</Collect>

<Pattern> 요소 여러 개를 사용할 수 있습니다.

<URIPath>
   <Pattern ignoreCase="false">/foo/{$}</Pattern>
   <Pattern ignoreCase="false">/foo/bar/{$}</Pattern>
</URIPath>

<QueryParam>

request 소스 메시지의 지정된 쿼리 매개변수에서 값을 추출합니다. 소스 메시지가 response 메시지 유형으로 확인되면 요소에서 아무 작업도 수행하지 않습니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 복합
상위 요소 <Collect>
하위 요소 <Pattern>

속성

속성 설명 기본값 필수 여부 유형
이름 쿼리 매개변수의 이름을 지정합니다. 여러 쿼리 매개변수의 이름이 같으면 색인이 생성된 참조를 사용합니다. 여기서 쿼리 매개변수의 첫 번째 인스턴스에는 색인이 없고, 두 번째는 색인 2, 세 번째는 색인 3입니다.

해당 사항 없음

 필수 문자열 
<Collect>
    <QueryParam name="code">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

이름이 같은 쿼리 매개변수가 여러 개 있는 경우 색인을 사용하여 매개변수를 참조합니다.

<Collect>
    <QueryParam name="code.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

참고: {$}라는 단일 변수를 지정해야 합니다. 고유한 Pattern 요소가 여러 개 있을 수 있지만 특정 요청에 첫 번째로 일치하는 패턴이 확인됩니다.

<Header>

지정된 request 또는 response 메시지의 지정된 HTTP 헤더에서 값을 추출합니다. 여러 헤더의 이름이 같으면 해당 값이 배열에 저장됩니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 복합
상위 요소 <Collect>
하위 요소 <Pattern>

속성

속성 설명 기본값 필수 여부 유형
이름 값을 추출할 헤더의 이름을 지정합니다. 여러 헤더의 이름이 같으면 색인이 생성된 참조를 사용합니다. 여기서 헤더의 첫 번째 인스턴스에는 색인이 없고, 두 번째는 색인 2, 세 번째는 색인 3입니다. .values를 사용하여 배열의 모든 헤더를 가져옵니다.

해당 사항 없음

 필수 문자열 
<Collect>
    <Header name="my_header">
        <Pattern ignoreCase="false">Bearer {$}</Pattern>
    </Header>
</Collect>

이름이 같은 헤더가 여러 개 있는 경우 색인을 사용하여 배열의 개별 헤더를 참조합니다.

<Collect>
    <Header name="my_header.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

또는 다음을 수행하여 배열의 모든 헤더를 나열할 수 있습니다.

<Collect>
    <Header name="my_header.values">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

<FormParam>

지정된 request 또는 response 메시지의 지정된 양식 매개변수에서 값을 추출합니다. 지정된 메시지의 Content-Type 헤더가 application/x-www-form-urlencoded인 경우에만 양식 매개변수를 추출할 수 있습니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 복합
상위 요소 <Collect>
하위 요소 <Pattern>

속성

속성 설명 기본값 필수 여부 유형
이름 값을 추출할 양식 매개변수의 이름입니다.

해당 사항 없음

 선택사항 문자열 
<Collect>
    <FormParam name="greeting">
        <Pattern>hello {$}</Pattern>
    </FormParam>
</Collect>

<JSONPayload>

변수 값을 추출할 JSON 형식의 메시지를 지정합니다. JSON 추출은 메시지의 Content-Type 헤더가 application/json인 경우에만 수행됩니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 복합
상위 요소 <Collect>
하위 요소 <JSONPath> 
<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

<JSONPath>

<JSONPayload> 요소의 필수 하위 요소입니다. JSON 형식 메시지에서 값을 추출하는 데 사용되는 JSON 경로를 지정합니다.

기본값 해당 사항 없음
필수 여부 필수
유형 문자열
상위 요소 <JSONPayload>
하위 요소 해당 사항 없음 
<JSONPath>$.rss.channel.title</JSONPath>

<XMLPayload>

변수 값을 추출할 XML 형식의 메시지를 지정합니다. XML 페이로드는 메시지의 Content-Type 헤더가 text/xml, application/xml, application/*+xml인 경우에만 추출됩니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 복합
상위 요소 <Collect>
하위 요소 <Namespaces>
<XPath>

다음 표에서는 <XMLPayload> 하위 요소를 간략하게 설명합니다.

하위 요소 필수 여부 설명
<Namespaces> 선택사항 XPath 평가에 사용할 0개 이상의 네임스페이스를 지정합니다.
<XPath> 필수 변수에 정의된 XPath를 지정합니다. 
<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="soap">http://schemas.xmlsoap.org/soap/envelope/</Namespace>
            <Namespace prefix="ns1">http://ns1.example.com/operations</Namespace>
        </Namespaces>
        <!-- get the local name of the SOAP operation -->
        <XPath>local-name(/soap:Envelope/soap:Body/ns1:*[1])</XPath>
    </XMLPayload>
</Collect>

<Namespaces>

XPath 표현식에 사용할 수 있는 네임스페이스의 집합을 지정합니다. 예시는 다음과 같습니다.

<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="maps">http://maps.example.com</Namespace>
            <Namespace prefix="places">http://places.example.com</Namespace>
        </Namespaces>
        <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint/places:name</XPath>
    </XMLPayload>
</Collect>

XPath 표현식에서 네임스페이스를 사용하지 않는 경우 다음 예시와 같이 <Namespaces> 요소를 생략하거나 주석 처리할 수 있습니다.

<Collect>
    <XMLPayload>
        <!-- <Namespaces/> -->
        <XPath>/Directions/route/leg/name</XPath>
    </XMLPayload>
</Collect>

<Namespace>

XPath 표현식 내에서 사용할 하나의 네임스페이스와 해당 프리픽스를 지정합니다. 예시는 다음과 같습니다.

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

속성

속성 설명 기본값 필수 여부 유형
prefix

xpath 표현식에서 네임스페이스를 참조하는 데 사용하는 프리픽스입니다. 이것은 원본 XML 문서에 사용된 것과 같은 프리픽스일 필요는 없습니다.

해당 사항 없음

 필수 문자열 
<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="maps">http://maps.example.com</Namespace>
        </Namespaces>
        <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint</XPath>
    </XMLPayload>
</Collect>

<XPath>

XMLPayload 요소의 필수 하위 요소입니다. 변수에 정의된 XPath를 지정합니다. XPath 1.0 표현식만 지원됩니다.

기본값 해당 사항 없음
필수 여부 필수
유형 문자열
상위 요소 <XMLPayload>
하위 요소 해당 사항 없음 
   <XPath>/test/example</XPath>

참고: XPath 표현식에서 네임스페이스를 사용하는 경우 정책의 <XMLPayload><Namespaces> 섹션에서 네임스페이스를 선언해야 합니다.

<ThrowExceptionOnLimit>

<ThrowExceptionOnLimit> 요소는 변수 수에 대한 캡처 한도 또는 최대 변수 크기에 도달하면 어떻게 되는지 구체적으로 지정합니다. 캡처 한도 적용을 참조하세요.

<ThrowExceptionOnLimit> 값은 다음 중 하나입니다.

  • false: 변수의 데이터가 애널리틱스로 전송됩니다.
  • true: 오류 메시지가 반환되고 데이터가 애널리틱스로 전송되지 않습니다.

오류 참조

런타임 오류

다음 표에서는 정책이 실행될 때 발생할 수 있는 런타임 오류를 설명합니다.

오류 코드 원인
DataCollectorTypeMismatch

캡처할 값이 DataCollector 유형과 일치하지 않습니다.
ExtractionFailure 데이터 추출이 실패했습니다.
UnresolvedVariable 변수가 없습니다.
VariableCountLimitExceeded 캡처된 변수 개수가 변수 개수 한도인 100개를 초과했습니다.
VariableValueLimitExceeded 캡처된 값의 크기가 단일 변수 한도인 400바이트를 초과했습니다.
MsgContentParsingFailed 메시지 콘텐츠를 XML 또는 JSON으로 파싱할 수 없습니다.
InvalidMsgContentType 메시지 콘텐츠 유형이 정책 캡처 절의 예상 메시지 콘텐츠 유형과 일치하지 않습니다.
NonMsgVariable <Source> 요소 값이 메시지 변수를 참조하지 않았습니다.
JSONPathQueryFailed JSONPath 쿼리를 값으로 확인할 수 없습니다.
PrivateVariableAccess 비공개 변수에 액세스를 시도하지 못했습니다.
XPathEvaluationFailed XPath를 값으로 확인할 수 없습니다.

런타임 오류는 두 가지 방식으로 반환됩니다.

  • 클라이언트로 다시 응답 오류(continueOnError=false)

    정책의 continueOnError 속성이 false로 설정된 경우 정책 실행 중에 오류가 발생하면 메시지 처리가 중단되고 설명이 있는 오류 메시지가 반환됩니다. 정책은 메시지를 반환하기 전에 데이터 캡처 정책에서 관련된 모든 오류를 캡처하려고 합니다.

  • DataCapture 오류 분석 필드

    dataCapturePolicyErrors 필드에는 발생한 모든 오류의 목록이 포함됩니다. 다음 예시에서는 분석 데이터 맵에 어떻게 표시되는지 보여줍니다.

    # Example payload
[
     {
         errorType: TypeMismatch,
         policyName: MyDataCapturePolicy-1,
         dataCollector: purchaseValue
     },
     {
         errorType: MaxValueSizeLimitReached,
         policyName: MyDataCapturePolicy-1,
         dataCollector: purchasedItems
     },
]

이 필드에는 400바이트 변수 크기 제한이 적용됩니다.

배포 오류

오류 코드 원인
DeploymentAssertionError 배포 중에 정책에서 참조된 DataCollector를 조직에서 찾을 수 없습니다.
JsonPathCompilationFailed 지정된 JSONPath로 컴파일할 수 없습니다.
XPathCompilationFailed XPath 요소에 사용된 프리픽스 또는 값이 정책에 선언된 네임스페이스의 일부가 아닌 경우 API 프록시 배포가 실패합니다.
PatternCompilationFailed 패턴 컴파일이 실패했습니다.

디버그 도구에서 DataCapture 오류 찾기

디버그 도구에서 dataCapturePolicyErrors 변수를 사용할 수 있습니다. 이 도구는 애널리틱스로 이동하지 않고도 오류를 포착할 수 있는 추가 도구입니다. 예를 들어 하이브리드 런타임 버전을 업그레이드하고 실수로 이미 배포된 프록시에서 분석을 중단하는 경우에 발생하는 오류를 포착할 수 있습니다.

캡처 한도 적용

Apigee는 캡처된 데이터의 변수에 다음 한도를 적용합니다.

  • 허용되는 변수의 수는 100개입니다.
  • 각 변수의 최대 크기(목록 값 포함)는 400바이트입니다.

데이터 캡처 정책을 실행할 때 값이 메시지 컨텍스트의 데이터 캡처 맵에 추가되기 전에 다음을 수행하세요.

  • 변수 수 한도에 도달하면 새 변수가 삭제됩니다.
  • 변수 크기 한도에 도달하면 값이 원하는 한도에 맞게 잘립니다.

두 경우 모두에 해당하는 사항:

  • 디버그 메시지가 메시지 프로세서 로그에 로깅됩니다.
  • limit reached 오류 메시지가 dataCapturePolicyErrors에 추가되며, 애널리틱스와 디버그 모두에서 사용할 수 있습니다. 참고: 최대 허용 변수 수에 도달하도록 하나의 오류 메시지만 추가됩니다.
  • <ThrowExceptionOnLimit>이 true이면 데이터가 애널리틱스로 전송되지 않고 대신 오류가 클라이언트에 반환됩니다.

관련 주제