Política de DataCapture

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Ícono de DataCapture

Descripción general

La política de DataCapture captura datos (como la carga útil, los encabezados HTTP y los parámetros de ruta o búsqueda) de un proxy de API para usarlos en Analytics. Puedes usar los datos capturados en los informes personalizados de Analytics, además de implementar las reglas de Sense, Monetización y Monitoring.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

.

Recurso de recopilador de datos

Para usar la política DataCapture, primero debes crear un recurso de recopilador de datos. Para obtener información sobre cómo crear un recurso de recopilador de datos con la IU de Apigee y la API de Apigee, consulta Crea un recopilador de datos.

<DataCapture>

El elemento <DataCapture> define una política DataCapture.

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

Este un ejemplo de una política DataCapture.

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

El elemento principal de la política DataCapture es el elemento <Capture>, que especifica los medios de captura de los datos. Tiene dos elementos secundarios obligatorios:

En este ejemplo simple, los datos se extraen de una variable llamada my_data_variable, que se creó en otra parte del proxy. El atributo ref especifica la variable.

El elemento <Collect> también proporciona otras formas de capturar datos de varias fuentes a través de sus elementos secundarios. Consulta Ejemplos para obtener más ejemplos de captura de datos con la política DataCapture.

El elemento DataCapture tiene la siguiente sintaxis.

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

Este elemento tiene los siguientes atributos que son comunes a todas las políticas:

Atributo Predeterminada (obligatorio) Descripción
name N/A Obligatorio

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

continueOnError falso Opcional Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta:
enabled true Opcional Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async   falso Obsoleta Este atributo dejó de estar disponible.

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <DataCapture>.

Elemento secundario Obligatorio Descripción
<Capture> Obligatorio Captura los datos para una variable especificada.

Ejemplos

En los siguientes ejemplos, se ilustran varias formas de usar la política DataCapture.

Captura datos de una variable integrada

En la siguiente muestra de código, se ilustra cómo capturar datos para una variable integrada, message.content, que incluye el contenido de la solicitud, la respuesta o el mensaje de error. Consulta Variables de flujo para obtener más información sobre las variables integradas.

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

En el código anterior, el atributo ref del elemento </Collect> especifica la variable que se capturará, que en este ejemplo se llama "message.content".

La muestra captura los datos con un elemento <Capture>, que también contiene un elemento <DataCollector> que especifica el nombre del recurso de recopilador de datos.

Captura datos intercalada

En el siguiente ejemplo, se muestra cómo capturar datos intercalados con <JSONPayload>, un elemento secundario del elemento <Collect>.

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

En el código anterior:

  • El elemento <JSONPayload> especifica el mensaje con formato JSON del que se extrae el valor de la variable.
  • El elemento <JSONPath> especifica la ruta de acceso JSON que se usa para extraer el valor del mensaje, que en este caso es $.results[0].currency.

A modo de ilustración, supongamos que el valor extraído en el momento en que se recibió el mensaje es 1120. La entrada resultante que se envíe a Analytics sería

{
    "dc_data_collector": "1120"
}

<Capture>

El elemento <Capture> especifica los medios para capturar los datos.

<Capture />

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <Capture>.

Elemento secundario ¿Es obligatorio? Descripción
<DataCollector> Obligatorio Especifica el recurso de recopilador de datos.
<Collect> Obligatorio Especifica los medios para capturar datos.

<DataCollector>

El elemento <DataCollector> especifica el recurso de recopilador de datos.

<DataCollector>dc_data_collector</DataCollector>
En la siguiente tabla, se describen los atributos del elemento <DataCollector>.
Atributo Descripción Predeterminada ¿Es obligatorio? Tipo
permiso

Especifica este atributo y establece el valor en monetization si deseas capturar las variables de monetización. Para obtener más información sobre las variables de monetización que puedes capturar, consulta Captura datos de monetización.

No disponible Opcional String

El cuerpo del elemento <DataCollector> contiene el nombre del recurso de recopilador de datos.

<Collect>

El elemento <Collect> especifica los medios para capturar datos.

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

En la siguiente tabla, se describen los atributos del elemento <Collect>.

Atributo Descripción Predeterminada ¿Es obligatorio? Tipo
ref

La variable para la que se capturan datos.

No disponible Si se omite ref, se debe especificar exactamente uno de los siguientes valores: QueryParam, Header, FormParam, URIPath, JSONPayload o XMLPayload (opcional). String
default Especifica el valor que se envía a Analytics si el valor de la variable no se propaga en el entorno de ejecución. Por ejemplo, si estableces default="0", el valor enviado a Analytics sería 0. Si no especificas el valor de default y el valor de la variable no se propaga en el entorno de ejecución, el valor enviado a Analytics es null para una variable numérica o "Not set" para una variable de string. Obligatorio String

Los datos se pueden capturar de una variable existente con el atributo ref o por elementos secundarios <Collect>.

Elementos secundarios de <Collect>

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <Collect>:

Elemento secundario ¿Es obligatorio? Descripción
<Source> Opcional Especifica la variable que se analizará.
<URIPath> Opcional Extrae un valor del proxy.pathsuffix de un mensaje fuente de solicitud.
<QueryParam> Opcional Extrae un valor del parámetro de búsqueda especificado de un mensaje fuente de solicitud.
<Header> Opcional Extrae un valor del encabezado HTTP especificado del mensaje de solicitud o respuesta especificado.
<FormParam> Opcional Extrae un valor del parámetro del formulario especificado de la solicitud o el mensaje de respuesta especificados.
<JSONPayload> Opcional Especifica el mensaje con formato JSON del cual se extraerá el valor de la variable.
<XMLPayload> Opcional Especifica el mensaje con formato XML del que se extraerá el valor de la variable.

<Source>

Especifica la variable que se analizará. El valor predeterminado de <Source> es message. El valor message es sensible al contexto. En un flujo de solicitud, message se resuelve en el mensaje de solicitud. En un flujo de respuesta, message se resuelve en el mensaje de respuesta.

Si bien con frecuencia usas esta política para extraer información de una solicitud o mensaje de respuesta, puedes usarla con el fin de extraer información de cualquier variable. Por ejemplo, puedes usarla para extraer información de una entidad creada por la política AccessEntity, a partir de los datos que muestra la política ServiceCallout, o bien extraer información de un objeto XML o JSON.

Si no se puede resolver <Source> o se resuelve como un tipo que no es de mensaje, la política no responderá.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo String
Elemento principal <Collect>
Elementos secundarios No disponible

Atributos

Atributo Descripción Predeterminada ¿Es obligatorio? Tipo
clearPayload

Configúralo como true si quieres borrar la carga útil especificada en <Source> después de extraer datos.

Usa la opción <clearPayload> solo si el mensaje de origen no es necesario después de que se ejecute ExtractVariables. Si se configura como verdadero, se libera la memoria que usa el mensaje.

falso

Opcional Booleano
<Source clearPayload="true|false">request</Source>

<URIPath>

Extrae un valor del proxy.pathsuffix de un mensaje fuente request. La ruta que se aplica al patrón es el proxy.pathsuffix, que no incluye la ruta base para el proxy de API. Si el mensaje fuente se resuelve en un tipo de mensaje de response, el elemento no realiza ninguna acción.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Complejo
Elemento principal <Collect>
Elementos secundarios <Pattern>

Atributos

Atributo Descripción Predeterminada ¿Es obligatorio? Tipo
ignoreCase Especifica para ignorar mayúsculas y minúsculas cuando coincida el patrón.

falso

Opcional Booleano
<Collect>
    <URIPath>
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
    </URIPath>
</Collect>

Puedes usar varios elementos <Pattern>:

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

<QueryParam>

Extrae un valor del parámetro de búsqueda especificado de un mensaje fuente request. Si el mensaje fuente se resuelve en un tipo de mensaje de response, el elemento no realiza ninguna acción.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Complejo
Elemento principal <Collect>
Elementos secundarios <Pattern>

Atributos

Atributo Descripción Predeterminada ¿Es obligatorio? Tipo
name Especifica el nombre del parámetro de búsqueda. Si varios parámetros de búsqueda tienen el mismo nombre, usa la referencia indexada, en la que la primera instancia del parámetro de búsqueda no tiene índice, la segunda está en el índice 2, la tercera en el índice 3, etcétera.

N/A

Obligatorio String
<Collect>
    <QueryParam name="code">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

Si varios parámetros de búsqueda tienen el mismo nombre, usa índices para hacer referencia a los parámetros:

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

Nota: Debes especificar una sola variable llamada {$}. Puede haber múltiples elementos Pattern únicos, pero el primer patrón coincidente se resolverá para una solicitud en particular.

<Header>

Extrae un valor del encabezado HTTP especificado del mensaje request o response especificado. Si varios encabezados tienen el mismo nombre, sus valores se almacenan en un arreglo.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Complejo
Elemento principal <Collect>
Elementos secundarios <Pattern>

Atributos

Atributo Descripción Predeterminada ¿Es obligatorio? Tipo
name Especifica el nombre del encabezado del que se extrae el valor. Si varios encabezados tienen el mismo nombre, usa la referencia indexada, en la que la primera instancia del encabezado no tiene índice, la segunda está en el índice 2, la tercera en el índice 3, etcétera. Usa .values para obtener todos los encabezados del arreglo.

N/A

Obligatorio String
<Collect>
    <Header name="my_header">
        <Pattern ignoreCase="false">Bearer {$}</Pattern>
    </Header>
</Collect>

Si varios encabezados tienen el mismo nombre, usa índices para hacer referencia a encabezados individuales en el arreglo:

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

O haz lo siguiente para enumerar todos los encabezados del arreglo:

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

<FormParam>

Extrae un valor del parámetro de formulario especificado del mensaje request o response especificado. Los parámetros de forma solo se pueden extraer cuando el encabezado Content-Type del mensaje especificado es application/x-www-form-urlencoded.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Complejo
Elemento principal <Collect>
Elementos secundarios <Pattern>

Atributos

Atributo Descripción Predeterminada ¿Es obligatorio? Tipo
name El nombre del parámetro del formulario desde el que se extrae el valor.

No disponible

Opcional String
<Collect>
    <FormParam name="greeting">
        <Pattern>hello {$}</Pattern>
    </FormParam>
</Collect>

<JSONPayload>

Especifica el mensaje con formato JSON a partir del cual se extraerá el valor de la variable. La extracción de JSON solo se realiza cuando el encabezado Content-Type del mensaje es application/json.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Complejo
Elemento principal <Collect>
Elementos secundarios <JSONPath>
<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

<JSONPath>

Elemento secundario obligatorio del elemento <JSONPayload>. Especifica la ruta JSON que se usó para extraer un valor de un mensaje con formato JSON.

Valor predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo String
Elemento principal <JSONPayload>
Elementos secundarios No disponible
<JSONPath>$.rss.channel.title</JSONPath>

<XMLPayload>

Especifica el mensaje con formato XML del que se extraerá el valor de la variable. Las cargas útiles XML se extraen solo cuando el encabezado Content-Type del mensaje es text/xml, application/xml o application/*+xml.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Complejo
Elemento principal <Collect>
Elementos secundarios <Namespaces>
<XPath>

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <XMLPayload>.

Elemento secundario ¿Es obligatorio? Descripción
<Namespaces> Opcional Especifica cero o más espacios de nombres que se usarán en la evaluación de XPath.
<XPath> Obligatorio Especifica XPath definida para la variable.
<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>

Especifica el conjunto de espacios de nombres que se pueden usar en la expresión XPath. Ejemplo.

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

Si no usas espacios de nombres en tus expresiones de XPath, puedes omitir o comentar el elemento <Namespaces>, como se muestra a continuación:

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

<Namespace>

Especifica un espacio de nombres y un prefijo correspondiente para usar dentro de la expresión XPath. Ejemplo.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo String
Elemento principal <Namespaces>
Elementos secundarios No disponible

Atributos

Atributo Descripción Predeterminada ¿Es obligatorio? Tipo
prefix

El prefijo que usas para hacer referencia al espacio de nombres en la expresión xpath. No es necesario que sea el mismo prefijo que se usa en el documento XML original.

No disponible

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

Elemento secundario obligatorio del elemento XMLPayload. Especifica la XPath definida para la variable. Solo se admiten expresiones de XPath 1.0.

Valor predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo String
Elemento principal <XMLPayload>
Elementos secundarios No disponible
   <XPath>/test/example</XPath>

Nota: Si usas espacios de nombres en tus expresiones de XPath, debes declarar los espacios de nombres en la sección <XMLPayload><Namespaces> de la política.

<ThrowExceptionOnLimit>

El elemento <ThrowExceptionOnLimit> especifica lo que sucede cuando se alcanza el límite de captura en la cantidad de variables o en el tamaño máximo de una variable. Consulta Aplica límites de captura.

El valor de <ThrowExceptionOnLimit> puede ser uno de los siguientes:

  • false: Los datos de las variables se envían a Analytics.
  • true: Se muestra un mensaje de error y los datos no se envían a Analytics.

Referencia de errores

Errores de entorno de ejecución

En la siguiente tabla, se describen los errores en el entorno de ejecución que pueden ocurrir cuando se ejecuta la política.

Código de falla Causa
DataCollectorTypeMismatch

El valor que se debe capturar no coincide con el tipo DataCollector.

ExtractionFailure No se pudieron extraer los datos.
UnresolvedVariable La variable no existe.
VariableCountLimitExceeded La cantidad de variables capturadas superó el límite de recuento de variables de 100.
VariableValueLimitExceeded El tamaño de un valor capturado supera el límite de la variable única de 400 bytes.
MsgContentParsingFailed No se pudo analizar el contenido del mensaje en formato XML o JSON.
InvalidMsgContentType El tipo de contenido del mensaje no coincide con el tipo de contenido del mensaje esperado en la cláusula de captura de políticas.
NonMsgVariable El valor del elemento <Source> no hace referencia a una variable de mensaje.
JSONPathQueryFailed La consulta JSONPath no pudo resolver un valor.
PrivateVariableAccess Falló el acceso a una variable privada.
XPathEvaluationFailed XPath no pudo resolver un valor.

Los errores en el entorno de ejecución se muestran de dos maneras:

  • Respuesta de error al cliente (continueOnError=false)

    Cuando el atributo continueOnError de la política se configura como false, los errores que se produzcan durante la ejecución de la política anularán el procesamiento del mensaje y mostrarán un mensaje de error descriptivo. La política intentará capturar todos los errores relevantes en la política de captura de datos antes de mostrar el mensaje.

  • Campo de estadísticas de errores de DataCapture

    El campo dataCapturePolicyErrors contiene una lista de todos los errores que se produjeron. A continuación, se muestra un ejemplo de cómo aparece esto en el mapa de datos de estadísticas:

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

Este campo está sujeto al límite de tamaño de la variable 400 bytes.

Errores en la implementación

Código de falla Causa
DeploymentAssertionError El DataCollector al que se hace referencia en la política no se pudo encontrar en la organización durante la implementación.
JsonPathCompilationFailed No se pudo compilar con el JSONPath especificado.
XPathCompilationFailed Si el prefijo o el valor usado en el elemento XPath no forma parte de los espacios de nombres declarados en la política, la implementación del proxy de API falla.
PatternCompilationFailed No se pudo compilar el patrón.

Encuentra errores DataCapture en la herramienta de depuración

La variable dataCapturePolicyErrors está disponible en la herramienta de depuración. Esta herramienta adicional que puede usar para detectar errores sin ir a Analytics. Por ejemplo, puedes detectar un error que ocurre si actualizas tu versión del entorno de ejecución híbrido y accidentalmente rompes las estadísticas en un proxy ya implementado.

Aplica límites de captura

Apigee aplica los siguientes límites a las variables en los datos capturados:

  • La cantidad de variables permitidas es 100.
  • El tamaño máximo de cada variable (incluidos los valores de lista) es de 400 bytes.

Cuando se ejecuta la política de captura de datos, antes de agregar un valor al mapa de captura de datos en el contexto del mensaje, sucede lo siguiente:

  • Si se alcanza el límite en la cantidad de variables, se descarta la variable nueva.
  • Si se alcanza el límite del tamaño de las variables, el valor se recortará para que se ajuste a los límites deseados.

En ambos casos:

  • Se registrará un mensaje de depuración en el registro de Message Processor.
  • Se agregará un mensaje de error limit reached a dataCapturePolicyErrors, que estará disponible en Analytics y en la depuración. Nota: Solo se agregará un mensaje de error para alcanzar la cantidad máxima de variables permitidas.
  • Si <ThrowExceptionOnLimit> es true, los datos no se envían a Analytics y, en su lugar, se muestra un error al cliente.

Temas relacionados