Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de Apigee Edge.
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:
- El elemento
<DataCollector>
, que especifica un recurso REST de recopilador de datos. En este caso, el recurso se llamadc_data_collector
. - El elemento
<Collect>
, que especifica los medios para capturar los datos.
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 De forma opcional, usa el elemento |
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>
<DataCollector>
.
Atributo | Descripción | Predeterminada | ¿Es obligatorio? | Tipo |
---|---|---|---|---|
permiso |
Especifica este atributo y establece el valor en |
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 Usa la opción |
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 |
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 comofalse
, 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
adataCapturePolicyErrors
, 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.