Política de DataCapture

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

Consulta la documentación de Apigee Edge.

Información general

La política DataCapture captura datos (como la carga útil, los encabezados HTTP y los parámetros de ruta o de consulta) de un proxy de API para usarlos en Analytics. Puede usar los datos recogidos en informes de Analytics personalizados, así como para implementar reglas de monetización y monitorización.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Recurso de recopilador de datos

Para usar la política DataCapture, primero debe crear un recurso de recogida de datos. Para ver los pasos que debes seguir para crear un recurso de recopilador de datos mediante la interfaz de usuario de Apigee o la API de Apigee, consulta Crear un recopilador de datos.

<DataCapture>

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

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

A continuación, se muestra un ejemplo de política de 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 para recoger los datos. Tiene dos elementos secundarios obligatorios:

• El elemento <DataCollector>, que especifica un recurso REST de recolector de datos. En este caso, el recurso se llama dc_data_collector.
• El elemento <Collect>, que especifica los medios para recoger los datos.

En este ejemplo sencillo, los datos se extraen de una variable llamada my_data_variable, que se ha creado en otra parte del proxy. La variable se especifica mediante el atributo ref.

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

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:

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <DataCapture>.

Ejemplos

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

Capturar datos de una variable integrada

En el siguiente ejemplo de código se muestra cómo registrar datos de una variable integrada, message.content, que contiene 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 va a capturar, que en este ejemplo se llama "message.content".

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

Capturar datos insertados

En el siguiente ejemplo se muestra cómo registrar datos insertados mediante <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 en formato JSON del que se extrae el valor de la variable.
• El elemento <JSONPath> especifica la ruta JSON que se usa para extraer el valor del mensaje, que en este caso es $.results[0].currency.

Por ejemplo, supongamos que el valor extraído en el momento en que se recibió el mensaje es 1120. Entonces, la entrada resultante enviada 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 ofrece una descripción general de los elementos secundarios de <Capture>.

<DataCollector>

El elemento <DataCollector> especifica el recurso del recolector de datos.

<DataCollector>dc_data_collector</DataCollector>

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

<Collect>

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

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

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

Los datos se pueden obtener de una variable que ya exista mediante el atributo ref o mediante elementos secundarios <Collect>.

Elementos secundarios de <Collect>

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <Collect>:

<Source>

Especifica una variable que indica el nombre del mensaje que se va a analizar. El valor de <Source> es message de forma predeterminada. El valor de message depende del contexto. En un flujo de solicitudes, message se resuelve en el mensaje de solicitud. En un flujo de respuesta, message se resuelve en el mensaje de respuesta.

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

<Source >request</Source>

<URIPath>

Extrae un valor del proxy.pathsuffix de un mensaje de origen request. La ruta aplicada al patrón es proxy.pathsuffix, que no incluye la ruta base del proxy de API. Si el mensaje de origen se resuelve en un tipo de mensaje response, el elemento no hace nada.

Atributos

<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 consulta especificado de un mensaje de origen request. Si el mensaje de origen se resuelve en un tipo de mensaje response, el elemento no hace nada.

Atributos

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

Si varios parámetros de consulta tienen el mismo nombre, utilice índices para hacer referencia a los parámetros:

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

Nota: Debe especificar una sola variable llamada {$}. Puede haber varios elementos Pattern únicos, pero el primer patrón coincidente se resolverá para una solicitud concreta.

<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 una matriz.

Atributos

<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 concretos en la matriz:

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

O lo siguiente para enumerar todos los encabezados de la matriz:

<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 formulario solo se pueden extraer cuando el encabezado Content-Type del mensaje especificado es application/x-www-form-urlencoded.

Atributos

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

<JSONPayload>

Especifica el mensaje en formato JSON del que 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.

<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

<JSONPath>

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

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

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <XMLPayload>.

<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. Un 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 utilizas espacios de nombres en tus expresiones XPath, puedes omitir o comentar el elemento <Namespaces>, como se muestra en el siguiente ejemplo:

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

<Namespace>

Especifica un espacio de nombres y un prefijo correspondiente para usarlo en la expresión XPath. Un ejemplo.

Atributos

<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 el XPath definido para la variable. variable. Solo se admiten expresiones XPath 1.0.

   <XPath>/test/example</XPath>

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

<ThrowExceptionOnLimit>

El elemento <ThrowExceptionOnLimit> especifica qué ocurre cuando se alcanzan los límites de captura en el número de variables o el tamaño máximo de una variable. Consulta Aplicar 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 devuelve un mensaje de error y los datos no se envían a Analytics.

Referencia de errores

Errores de tiempo de ejecución

En la siguiente tabla se describen los errores de tiempo de ejecución, que pueden producirse cuando se ejecuta la política.

Los errores del tiempo de ejecución se devuelven de dos formas:

• Respuesta de error enviada al cliente (continueOnError=false)

  Si el atributo continueOnError de la política se define como false, los errores que se produzcan durante la ejecución de la política abortarán el procesamiento del mensaje y devolverán un mensaje de error descriptivo. La política intentará registrar todos los errores relevantes de la política de recogida de datos antes de devolver el mensaje.

• DataCapture errores en el campo de analíticas

  El campo dataCapturePolicyErrors contiene una lista de todos los errores que se han producido. A continuación se muestra un ejemplo de cómo aparecería en el mapa de datos de analíticas:

  # 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 variable de 400 bytes.

Errores de implementación

Buscar errores DataCapture en la herramienta de depuración

La variable dataCapturePolicyErrors está disponible en la herramienta Depuración. Es una herramienta adicional que puede usar para detectar errores sin tener que ir a Analytics. Por ejemplo, puedes detectar un error que se produce si actualizas tu versión del tiempo de ejecución híbrido y, sin darte cuenta, rompes las analíticas de un proxy que ya se ha implementado.

Aplicar límites de capturas

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

• Se permiten 100 variables.
• El tamaño máximo de cada variable (incluidos los valores de la lista) es de 400 bytes.

Cuando se ejecuta la política de captura de datos, antes de que se añada un valor al mapa de captura de datos en el contexto del mensaje:

• Si se ha alcanzado el límite de variables, se descartará la nueva.
• Si se ha alcanzado el límite de tamaño de las variables, el valor se recortará para ajustarse a los límites deseados.

En ambos casos:

• Se registrará un mensaje de depuración en el registro del procesador de mensajes.
• Se añadirá un mensaje de error limit reached a dataCapturePolicyErrors, que estará disponible tanto en Analytics como en Depuración. Nota: Solo se añadirá un mensaje de error por alcanzar el número máximo de variables permitidas.
• Si <ThrowExceptionOnLimit> es true, los datos no se envían a Analytics y, en su lugar, se devuelve un error al cliente.

Temas relacionados

• Política ExtractVariables