Stratégie DataCapture

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Icône DataCapture

Aperçu

La règle DataCapture capture des données (telles que la charge utile, les en-têtes HTTP et les paramètres de chemin d'accès ou de requête) à partir d'un proxy d'API afin de les utiliser dans Analytics. Vous pouvez utiliser les données capturées dans les rapports Analytics personnalisés, et pour mettre en œuvre des règles Sense, ainsi que des règles de monétisation et de surveillance.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

.

Ressource de collecteur de données

Pour utiliser la stratégie DataCapture, vous devez d'abord créer une ressource de collecteur de données. Pour connaître les étapes à suivre pour créer une ressource de collecteur de données à l'aide de l'interface utilisateur ou de l'API Apigee, consultez la page Créer un collecteur de données.

<DataCapture>

L'élément <DataCapture> définit une stratégie DataCapture.

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

Voici un exemple de stratégie DataCapture :

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

Le principal élément de la stratégie DataCapture est l'élément <Capture>, qui spécifie le moyen de capturer les données. Il est associé à deux éléments enfants obligatoires :

Dans cet exemple simple, les données sont extraites d'une variable nommée my_data_variable, qui a été créée ailleurs dans le proxy. La variable est spécifiée par l'attribut ref.

L'élément <Collect> offre également plusieurs autres moyens de capturer des données à partir de différentes sources via ses éléments enfants. Pour plus d'exemples sur la capture de données avec la règle DataCapture, consultez la section Exemples.

La syntaxe de l'élément DataCapture est la suivante.

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

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut Par défaut Obligatoire ? Description
name ND Obligatoire

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
continueOnError faux Facultatif Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi :
enabled true Facultatif Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async   faux Obsolète Cet attribut est obsolète.

Le tableau suivant fournit une description détaillée des éléments enfants de <DataCapture>.

Élément enfant Requis Description
<Capture> Requis Capture les données d'une variable spécifiée.

Exemples

Les exemples suivants illustrent différentes manières d'utiliser la stratégie DataCapture.

Collecter des données pour une variable intégrée

L'exemple de code ci-dessous montre comment capturer des données pour une variable intégrée, message.content, qui contient le contenu de la requête, de la réponse ou du message d'erreur. Pour en savoir plus sur les variables intégrées, consultez la page Variables de flux.

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

Dans le code ci-dessus, l'attribut ref de l'élément </Collect> spécifie la variable à capturer, dans cet exemple, nommée "message.content".

L'exemple capture les données avec un élément <Capture>, qui contient également un élément <DataCollector> spécifiant le nom de la ressource de collecteur de données.

Capturer des données de manière intégrée

L'exemple suivant montre comment capturer des données à l'aide de <JSONPayload>, un élément enfant de l'élément <Collect>.

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

Dans le code ci-dessus :

  • L'élément <JSONPayload> spécifie le message au format JSON à partir duquel la valeur de la variable est extraite.
  • L'élément <JSONPath> spécifie le chemin JSON utilisé pour extraire la valeur du message, qui dans ce cas est $.results[0].currency.

À titre d'illustration, supposons que la valeur extraite au moment de la réception du message est 1120. Ensuite, l'entrée résultante envoyée à Analytics serait

{
    "dc_data_collector": "1120"
}

<Capture>

L'élément <Capture> indique le moyen de capturer les données.

<Capture />

Le tableau suivant fournit une description détaillée des éléments enfants de <Capture>.

Élément enfant Requis ? Description
<DataCollector> Obligatoire Spécifie la ressource de collecteur de données.
<Collect> Obligatoire Spécifie le moyen de capturer des données.

<DataCollector>

L'élément <DataCollector> spécifie la ressource de collecteur de données.

<DataCollector>dc_data_collector</DataCollector>
 Le tableau suivant décrit les attributs de l'élément <DataCollector>
Attribut Description Par défaut nécessaire Type
champ d'application

Spécifiez cet attribut et définissez la valeur sur monetization si vous souhaitez capturer les variables de monétisation. Pour en savoir plus sur les variables de monétisation que vous pouvez capturer, consultez la section Capturer les données de monétisation.

 Non disponible Facultatif String

Le corps de l'élément <DataCollector> contient le nom de la ressource de collecteur de données.

<Collect>

L'élément <Collect> indique les moyens de capturer des données.

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

Le tableau suivant décrit les attributs de l'élément <Collect>

Attribut Description Par défaut nécessaire Type
ref

Variable pour laquelle vous collectez des données.

 ND Facultatif : Si ref est omis, vous devez spécifier exactement l'un des éléments suivants : QueryParam, Header, FormParam, URIPath, JSONPayload ou XMLPayload. String
par défaut Spécifie la valeur envoyée à Analytics si la valeur de la variable n'est pas renseignée au moment de l'exécution. Par exemple, si vous définissez default="0", la valeur envoyée à Analytics serait de 0. Si vous ne spécifiez pas la valeur de default, et que la valeur de la variable n'est pas renseignée au moment de l'exécution, la valeur envoyée à Analytics est null pour une variable numérique ou "Not set" pour une variable de chaîne. Requis String

Les données peuvent être capturées à partir d'une variable existante à l'aide de l'attribut ref ou par des éléments enfants <Collect>.

Éléments enfants de <Collect>

Le tableau suivant fournit une description détaillée des éléments enfants de <Collect> :

Élément enfant Requis ? Description
<Source> Facultatif Spécifie la variable à analyser.
<URIPath> Facultatif Extrait une valeur du champ proxy.pathsuffix d'un message source de la requête.
<QueryParam> Facultatif Extrait une valeur à partir du paramètre de requête spécifié d'un message source de requête.
<Header> Facultatif Extrait une valeur de l'en-tête HTTP spécifié du message de requête ou de réponse spécifié.
<FormParam> Facultatif Extrait une valeur du paramètre de formulaire spécifié du message de requête ou de réponse spécifié.
<JSONPayload> Facultatif Spécifie le message au format JSON dont la valeur de la variable sera extraite.
<XMLPayload> Facultatif Spécifie le message au format XML dont la valeur de la variable sera extraite.

<source>

Spécifie la variable à analyser. La valeur <Source> est définie sur message par défaut. La valeur message est sensible au contexte. Dans un flux de requête, message renvoie le message de requête. Dans un flux de réponse, message renvoie le message de réponse.

Cette règle sert souvent à extraire des informations d'un message de requête ou de réponse, mais vous pouvez l'utiliser pour extraire des informations de n'importe quelle variable. Par exemple, vous pouvez l'utiliser pour extraire des informations d'une entité créée par la règle AccessEntity, des données renvoyées par la règle ServiceCallout, ou extraire des informations d'un objet XML ou JSON.

Si <Source> ne peut être résolu ou est associé à un type qui n'est pas un message, la règle ne produira aucune réponse.

Valeur par défaut ND
Requis ? Facultatif
Type Chaîne
Élément parent <Collect>
Éléments enfants Non disponible

Attributs

Attribut Description Par défaut nécessaire Type
clearPayload

Définissez cet attribut sur true si vous souhaitez effacer la charge utile spécifiée dans <Source> après avoir extrait les données de celle-ci.

N'utilisez l'option <clearPayload> que si le message de type "source" n'est pas requis après l'exécution de la règle ExtractVariables. La définir sur true libère la mémoire utilisée par le message.

faux

 Facultatif Booléen 
<Source clearPayload="true|false">request</Source>

<URIPath>

Extrait une valeur du champ proxy.pathsuffix d'un message source request. Le chemin appliqué au modèle est proxy.pathsuffix, qui n'inclut pas le chemin de base du proxy d'API. Si le message source est de type response, l'élément n'a aucun effet.

Valeur par défaut ND
Requis ? Facultatif
Type Complexe
Élément parent <Collect>
Éléments enfants <Pattern>

Attributs

Attribut Description Par défaut nécessaire Type
ignoreCase Spécifie si la casse doit être ignorée lors de la mise en correspondance du modèle.

faux

 Facultatif Booléen 
<Collect>
    <URIPath>
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
    </URIPath>
</Collect>

Vous pouvez utiliser plusieurs éléments <Pattern> :

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

<QueryParam>

Extrait une valeur à partir du paramètre de requête spécifié d'un message source de request. Si le message source est de type response, l'élément n'a aucun effet.

Valeur par défaut ND
Requis ? Facultatif
Type Complexe
Élément parent <Collect>
Éléments enfants <Pattern>

Attributs

Attribut Description Par défaut nécessaire Type
nom Spécifie le nom du paramètre de requête. Si plusieurs paramètres de requête portent le même nom, utilisez le référencement indexé où la première instance du paramètre de requête n'a pas d'index, la deuxième correspond à l'index 2, la troisième à l'index 3, etc.

ND

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

Si plusieurs paramètres de requête portent le même nom, utilisez des index pour les référencer :

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

Remarque : Vous devez spécifier une seule variable nommée {$}. Il peut exister plusieurs éléments Pattern uniques, mais le premier schéma correspondant sera résolu pour une requête donnée.

<Header>

Extrait une valeur de l'en-tête HTTP spécifié du message request ou response spécifié. Si plusieurs en-têtes portent le même nom, leurs valeurs sont stockées dans un tableau.

Valeur par défaut ND
Requis ? Facultatif
Type Complexe
Élément parent <Collect>
Éléments enfants <Pattern>

Attributs

Attribut Description Par défaut nécessaire Type
nom Spécifie le nom de l'en-tête à partir duquel extraire la valeur. Si plusieurs en-têtes portent le même nom, utilisez le référencement indexé où la première instance de l'en-tête n'a pas d'index, la deuxième correspond à l'index 2, la troisième à l'index 3, etc. Utilisez .values pour obtenir tous les en-têtes du tableau.

ND

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

Si plusieurs en-têtes portent le même nom, utilisez des index pour référencer des en-têtes spécifiques du tableau :

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

La commande suivante permet d'obtenir la liste tous les en-têtes du tableau :

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

<FormParam>

Extrait une valeur du paramètre de formulaire spécifié du message request ou response spécifié. Les paramètres de formulaire ne peuvent être extraits que lorsque l'en-tête Content-Type du message spécifié est application/x-www-form-urlencoded.

Valeur par défaut ND
Requis ? Facultatif
Type Complexe
Élément parent <Collect>
Éléments enfants <Pattern>

Attributs

Attribut Description Par défaut nécessaire Type
nom Nom du paramètre de formulaire à partir duquel extraire la valeur.

ND

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

<JSONPayload>

Spécifie le message au format JSON dont la valeur de la variable sera extraite. L'extraction JSON n'est effectuée que lorsque l'en-tête Content-Type du message est application/json.

Valeur par défaut ND
Requis ? Facultatif
Type Complexe
Élément parent <Collect>
Éléments enfants <JSONPath> 
<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

<JSONPath>

Élément enfant requis de l'élément <JSONPayload>. Spécifie le chemin JSON utilisé pour extraire une valeur d'un message au format JSON.

Valeur par défaut ND
Obligatoire ? Obligatoire
Type Chaîne
Élément parent <JSONPayload>
Éléments enfants Non disponible 
<JSONPath>$.rss.channel.title</JSONPath>

<XMLPayload>

Spécifie le message au format XML dont la valeur de la variable sera extraite. Les charges utiles XML ne sont extraites que lorsque l'en-tête Content-Type du message est text/xml, application/xml ou application/*+xml.

Valeur par défaut ND
Requis ? Facultatif
Type Complexe
Élément parent <Collect>
Éléments enfants <Namespaces>
<XPath>

Le tableau suivant fournit une description détaillée des éléments enfants de <XMLPayload>.

Élément enfant Requis ? Description
<Namespaces> Facultatif Spécifie zéro ou plusieurs espaces de noms à utiliser dans l'évaluation XPath.
<XPath> Requis Spécifie le chemin XPath défini pour 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>

Spécifie l'ensemble des espaces de noms pouvant être utilisés dans l'expression XPath. Exemple :

<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 vous n'utilisez pas d'espaces de noms dans vos expressions XPath, vous pouvez omettre ou commenter l'élément <Namespaces>, comme illustré par l'exemple suivant :

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

<Namespace>

Spécifie un espace de noms et un préfixe correspondant à utiliser dans l'expression XPath. Exemple :

Valeur par défaut ND
Requis ? Facultatif
Type Chaîne
Élément parent <Namespaces>
Éléments enfants Non disponible

Attributs

Attribut Description Par défaut nécessaire Type
prefix

Préfixe que vous utilisez pour faire référence à l'espace de noms dans l'expression xpath. Il ne doit pas nécessairement être identique à celui utilisé dans le document XML d'origine.

Non disponible

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

Élément enfant requis de l'élément XMLPayload. Spécifie le chemin XPath défini pour la variable. Seules les expressions XPath 1.0 sont acceptées.

Valeur par défaut ND
Obligatoire ? Obligatoire
Type Chaîne
Élément parent <XMLPayload>
Éléments enfants Non disponible 
   <XPath>/test/example</XPath>

Remarque : Si vous utilisez des espaces de noms dans vos expressions XPath, vous devez déclarer ces espaces de noms dans la section <XMLPayload><Namespaces> de la stratégie.

<ThrowExceptionOnLimit>

L'élément <ThrowExceptionOnLimit> spécifie ce qui se passe lorsque les limites de capture du nombre de variables ou de la taille maximale d'une variable sont atteintes. Consultez la section Appliquer des limites de capture.

<ThrowExceptionOnLimit> peut être défini sur l'une des valeurs suivantes :

  • false : les données des variables sont envoyées à Analytics.
  • true : un message d'erreur est renvoyé et les données ne sont pas envoyées à Analytics.

Informations de référence sur les erreurs

Erreurs d'exécution

Le tableau ci-dessous décrit les erreurs d'exécution pouvant survenir lors de l'exécution de la stratégie.

Code d'erreur Cause
DataCollectorTypeMismatch

La valeur à capturer ne correspond pas au type DataCollector.
ExtractionFailure Échec de l'extraction des données.
UnresolvedVariable La variable n'existe pas.
VariableCountLimitExceeded Le nombre de variables capturées dépasse la limite du nombre de variables de 100 variables
VariableValueLimitExceeded La taille d'une valeur capturée dépasse la limite variable de 400 octets.
MsgContentParsingFailed Échec de l'analyse du contenu des messages au format XML ou JSON.
InvalidMsgContentType Le type de contenu du message ne correspond pas au type de contenu attendu du message dans la clause de capture des stratégies.
NonMsgVariable La valeur de l'élément <Source> ne fait pas référence à une variable de message.
JSONPathQueryFailed Échec de la résolution de la requête JSONPath pour afficher une valeur.
PrivateVariableAccess Échec de la tentative d'accès à une variable privée.
XPathEvaluationFailed Échec de la résolution de XPath en une valeur.

Les erreurs d'exécution sont renvoyées de deux manières :

  • Réponse d'erreur au client (continueOnError=false)

    Lorsque l'attribut continueOnError de la stratégie est défini sur false, les erreurs qui se produisent pendant l'exécution de la stratégie annulent le traitement du message et renvoient un message d'erreur descriptif. La stratégie tente de capturer toutes les erreurs pertinentes dans la stratégie de capture de données avant de renvoyer le message.

  • Champ d'analyse des erreurs DataCapture

    Le champ dataCapturePolicyErrors contient la liste de toutes les erreurs survenues. Voici un exemple de ce type de données dans la carte des données d'analyse :

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

Ce champ est soumis à la limite de taille d'une variable de 400 octets.

Erreurs de déploiement

Code d'erreur Cause
DeploymentAssertionError Le DataCollector référencé dans la stratégie est introuvable dans l'organisation lors du déploiement.
JsonPathCompilationFailed Échec de la compilation avec la valeur JSONPath spécifiée.
XPathCompilationFailed Si le préfixe ou la valeur utilisée dans l'élément XPath ne fait partie d'aucun des espaces de noms déclarés dans la règle, le déploiement du proxy d'API échoue.
PatternCompilationFailed Échec de compilation du schéma.

Rechercher des erreurs DataCapture dans l'outil Debug

La variable dataCapturePolicyErrors est disponible dans l'outil Debug. Il s'agit d'un outil supplémentaire qui vous permet d'identifier les erreurs sans accéder à Analytics. Par exemple, vous pouvez repérer une erreur qui se produit si vous mettez à niveau votre version de l'environnement d'exécution hybride et cassez par inadvertance les données d'analyse dans un proxy déjà déployé.

Appliquer des limites de capture

Apigee applique les limites suivantes aux variables des données capturées :

  • Le nombre de variables autorisées est de 100.
  • La taille maximale de chaque variable (valeurs de liste incluses) est de 400 octets.

Lors de l'exécution de la stratégie de capture de données, avant qu'une valeur ne soit ajoutée au mappage de capture des données dans le contexte du message, procédez comme suit :

  • Si la limite du nombre de variables a été atteinte, la nouvelle variable est supprimée.
  • Si la limite de la taille des variables a été atteinte, la valeur est supprimée pour respecter les limites souhaitées.

Dans les deux cas :

  • Un message de débogage est consigné dans le journal du processeur de messages.
  • Un message d'erreur limit reached est ajouté à dataCapturePolicyErrors, qui est disponible dans Analytics et Debug. Remarque : Un seul message d'erreur est ajouté lorsque vous atteignez le nombre maximal de variables autorisées.
  • Si <ThrowExceptionOnLimit> est défini sur true, les données ne sont pas envoyées à Analytics et une erreur est renvoyée au client.

Articles associés