Norme di DataCapture

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Icona DataCapture

Panoramica

Le norme DataCapture acquisiscono dati (come payload, intestazioni HTTP e parametri di percorso o query) da un proxy API per l'utilizzo in Analytics. Puoi utilizzare i dati acquisiti nei report personalizzati di Analytics, nonché per implementare regole di monetizzazione e monitoraggio.

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Risorsa raccoglitore dati

Per utilizzare le norme DataCapture, devi prima creare una risorsa data collector. Per i passaggi per creare una risorsa di raccolta dati utilizzando l'interfaccia utente Apigee e l'API Apigee, vedi Creazione di un raccoglitore di dati.

<DataCapture>

L'elemento <DataCapture> definisce un criterio DataCapture.

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

Ecco un esempio di norma relativa a DataCapture:

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

L'elemento principale della norma DataCapture è l'elemento <Capture>, che specifica i mezzi di acquisizione dei dati. Ha due elementi secondari obbligatori:

In questo semplice esempio, i dati vengono estratti da una variabile denominata my_data_variable, creata altrove nel proxy. La variabile è specificata dall'attributo ref.

L'elemento <Collect> fornisce anche diversi altri modi per acquisire dati da varie origini tramite i relativi elementi secondari. Consulta la sezione Esempi per altri esempi di acquisizione di dati con le norme DataCapture.

L'elemento DataCapture ha la seguente sintassi.

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

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo Predefinito Obbligatorio? Descrizione
name N/D Obbligatorio

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError falso Facoltativo Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:
enabled true Facoltativo Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async   falso Ritirato Questo attributo è stato ritirato.

La tabella seguente fornisce una descrizione generale degli elementi secondari di <DataCapture>.

Elemento secondario Obbligatorio Descrizione
<Capture> Obbligatorio Acquisisce i dati per una variabile specificata.

Esempi

I seguenti esempi illustrano vari modi per utilizzare il criterio DataCapture.

Acquisizione dei dati per una variabile integrata

L'esempio di codice riportato di seguito mostra come acquisire i dati per una variabile integrata, message.content, che contiene il contenuto della richiesta, della risposta o del messaggio di errore. Per ulteriori informazioni sulle variabili integrate, consulta la sezione Variabili di flusso.

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

Nel codice riportato sopra, l'attributo ref dell'elemento </Collect> specifica la variabile da acquisire, che in questo esempio si chiama "message.content".

Il campione acquisisce i dati con un elemento <Capture>, che contiene anche un elemento <DataCollector> che specifica il nome della risorsa di raccolta dati.

Acquisizione dei dati in linea

L'esempio successivo mostra come acquisire i dati incorporati utilizzando <JSONPayload>, un elemento secondario dell'elemento <Collect>.

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

Nel codice riportato sopra:

  • L'elemento <JSONPayload> specifica il messaggio in formato JSON da cui viene estratto il valore della variabile.
  • L'elemento <JSONPath> specifica il percorso JSON utilizzato per estrarre il valore dal messaggio, che in questo caso è $.results[0].currency.

Ad esempio, supponiamo che il valore estratto al momento della ricezione del messaggio sia 1120. Quindi, la voce risultante inviata ad Analytics sarebbe

{
    "dc_data_collector": "1120"
}

<Capture>

L'elemento <Capture> specifica i mezzi di acquisizione dei dati.

<Capture />

La tabella seguente fornisce una descrizione generale degli elementi secondari di <Capture>.

Elemento secondario Obbligatorio? Descrizione
<DataCollector> Obbligatorio Specifica la risorsa del raccoglitore dati.
<Collect> Obbligatorio Specifica i mezzi per acquisire i dati.

<DataCollector>

L'elemento <DataCollector> specifica la risorsa di raccolta dei dati.

<DataCollector>dc_data_collector</DataCollector>
 La tabella seguente descrive gli attributi dell'elemento <DataCollector>.
Attributo Descrizione Predefinito Obbligatorio? Tipo
ambito

Specifica questo attributo e imposta il valore su monetization se vuoi acquisire le variabili di monetizzazione. Per ulteriori informazioni sulle variabili di monetizzazione che puoi acquisire, consulta Acquisizione dei dati di monetizzazione.

 N/D Facoltativo Stringa

Il corpo dell'elemento <DataCollector> contiene il nome della risorsa del raccoglitore di dati.

<Collect>

L'elemento <Collect> specifica i mezzi per acquisire i dati.

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

La tabella seguente descrive gli attributi dell'elemento <Collect>.

Attributo Descrizione Predefinito Obbligatorio? Tipo
ref

La variabile per cui stai acquisendo i dati.

 N/D (Facoltativo) Se ref viene omesso, deve essere specificato esattamente uno dei seguenti valori: QueryParam, Header, FormParam, URIPath, JSONPayload o XMLPayload. Stringa
predefinita Specifica il valore inviato ad Analytics se il valore della variabile non viene compilato in fase di runtime. Ad esempio, se imposti default="0", il valore inviato ad Analytics sarà 0. Se non specifichi il valore di default e il valore della variabile non viene compilato in fase di runtime, il valore inviato ad Analytics è null per una variabile numerica o "Not set" per una variabile stringa. Obbligatorio Stringa

I dati possono essere acquisiti da una variabile esistente utilizzando l'attributo ref o tramite gli elementi secondari <Collect>.

Elementi secondari di <Collect>

La tabella seguente fornisce una descrizione generale degli elementi secondari di <Collect>:

Elemento secondario Obbligatorio? Descrizione
<Source> Facoltativo Specifica la variabile da analizzare.
<URIPath> Facoltativo Estrae un valore da proxy.pathsuffix di un messaggio di origine richiesta.
<QueryParam> Facoltativo Estrae un valore dal parametro di query specificato di un messaggio di origine della richiesta.
<Header> Facoltativo Estrae un valore dall'intestazione HTTP specificata del messaggio di richiesta o risposta specificato.
<FormParam> Facoltativo Estrae un valore dal parametro del modulo specificato del messaggio di richiesta o risposta specificato.
<JSONPayload> Facoltativo Specifica il messaggio in formato JSON da cui verrà estratto il valore della variabile.
<XMLPayload> Facoltativo Specifica il messaggio in formato XML da cui verrà estratto il valore della variabile.

<Source>

Specifica una variabile che assegna un nome al messaggio da analizzare. Il valore di <Source> è impostato per impostazione predefinita su message. Il valore message è sensibile al contesto. In un flusso di richieste, message viene risolto nel messaggio di richiesta. In un flusso di risposta, message viene risolto nel messaggio di risposta.

Se la variabile specificata in <Source> non può essere risolta o viene risolta in un tipo non di messaggio, la norma non risponderà.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <Collect>
Elementi secondari N/D 
<Source >request</Source>

<URIPath>

Estrae un valore dal proxy.pathsuffix di un messaggio di origine request. Il percorso applicato al pattern è proxy.pathsuffix, che non include il percorso di base per il proxy API. Se il messaggio di origine viene risolto in un tipo di messaggio response, l'elemento non fa nulla.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Complesso
Elemento principale <Collect>
Elementi secondari <Pattern>

Attributi

Attributo Descrizione Predefinito Obbligatorio? Tipo
ignoreCase Specifica di ignorare maiuscole e minuscole durante la corrispondenza del pattern.

falso

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

Puoi utilizzare più elementi <Pattern>:

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

<QueryParam>

Estrae un valore dal parametro di query specificato di un messaggio di origine request. Se il messaggio di origine viene risolto in un tipo di messaggio response, l'elemento non fa nulla.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Complesso
Elemento principale <Collect>
Elementi secondari <Pattern>

Attributi

Attributo Descrizione Predefinito Obbligatorio? Tipo
nome Specifica il nome del parametro di ricerca. Se più parametri di ricerca hanno lo stesso nome, utilizza i riferimenti indicizzati, in cui la prima istanza del parametro di query non ha indice, la seconda ha indice 2, la terza ha indice 3 e così via.

N/D

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

Se più parametri di ricerca hanno lo stesso nome, utilizza gli indici per fare riferimento ai parametri:

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

Nota:devi specificare una sola variabile denominata {$}. Potrebbero esserci più elementi Pattern unici, ma il primo pattern corrispondente verrà risolto per una determinata richiesta.

<Header>

Estrae un valore dall'intestazione HTTP specificata del messaggio request o response specificato. Se più intestazioni hanno lo stesso nome, i relativi valori vengono memorizzati in un array.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Complesso
Elemento principale <Collect>
Elementi secondari <Pattern>

Attributi

Attributo Descrizione Predefinito Obbligatorio? Tipo
nome Specifica il nome dell'intestazione da cui estrai il valore. Se più intestazioni hanno lo stesso nome, utilizza i riferimenti indicizzati, in cui la prima istanza dell'intestazione non ha indice, la seconda ha indice 2, la terza ha indice 3 e così via. Utilizza .values per ottenere tutte le intestazioni nell'array.

N/D

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

Se più intestazioni hanno lo stesso nome, utilizza gli indici per fare riferimento alle singole intestazioni nell'array:

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

Oppure il seguente per elencare tutte le intestazioni dell'array:

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

<FormParam>

Estrae un valore dal parametro del modulo specificato del messaggio request o response specificato. I parametri del modulo possono essere estratti solo quando l'intestazione Content-Type del messaggio specificato è application/x-www-form-urlencoded.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Complesso
Elemento principale <Collect>
Elementi secondari <Pattern>

Attributi

Attributo Descrizione Predefinito Obbligatorio? Tipo
nome Il nome del parametro del modulo da cui estrai il valore.

N/D

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

<JSONPayload>

Specifica il messaggio in formato JSON da cui verrà estratto il valore della variabile. L'estrazione JSON viene eseguita solo quando l'intestazione Content-Type del messaggio è application/json.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Complesso
Elemento principale <Collect>
Elementi secondari <JSONPath> 
<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

<JSONPath>

Elemento secondario obbligatorio dell'elemento <JSONPayload>. Specifica il percorso JSON utilizzato per estrarre un valore da un messaggio in formato JSON.

Valore predefinito N/D
Obbligatorio? Obbligatorio
Tipo Stringa
Elemento principale <JSONPayload>
Elementi secondari N/D 
<JSONPath>$.rss.channel.title</JSONPath>

<XMLPayload>

Specifica il messaggio in formato XML da cui verrà estratto il valore della variabile. I payload XML vengono estratti solo quando l'intestazione Content-Type del messaggio è text/xml, application/xml, o application/*+xml.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Complesso
Elemento principale <Collect>
Elementi secondari <Namespaces>
<XPath>

La tabella seguente fornisce una descrizione generale degli elementi secondari di <XMLPayload>.

Elemento secondario Obbligatorio? Descrizione
<Namespaces> Facoltativo Specifica zero o più spazi dei nomi da utilizzare nella valutazione XPath.
<XPath> Obbligatorio Specifica l'XPath definito per la variabile. 
<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>

<Spazi dei nomi>

Specifica l'insieme di spazi dei nomi che possono essere utilizzati nell'espressione XPath. Un esempio.

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

Se non utilizzi spazi dei nomi nelle espressioni XPath, puoi omettere o commentare l'elemento <Namespaces>, come mostrato nell'esempio seguente:

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

<Namespace>

Specifica uno spazio dei nomi e un prefisso corrispondente da utilizzare all'interno dell'espressione XPath. Un esempio.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <Namespaces>
Elementi secondari N/D

Attributi

Attributo Descrizione Predefinito Obbligatorio? Tipo
prefix

Il prefisso che utilizzi per fare riferimento allo spazio dei nomi nell'espressione XPath. Non è necessario che questo prefisso sia lo stesso utilizzato nel documento XML originale.

N/D

 Obbligatorio Stringa 
<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 secondario obbligatorio dell'elemento XMLPayload. Specifica l'XPath definito per la variabile. Sono supportate solo le espressioni XPath 1.0.

Valore predefinito N/D
Obbligatorio? Obbligatorio
Tipo Stringa
Elemento principale <XMLPayload>
Elementi secondari N/D 
   <XPath>/test/example</XPath>

Nota:se utilizzi spazi dei nomi nelle espressioni XPath, devi dichiararli nella sezione <XMLPayload><Namespaces> delle norme.

<ThrowExceptionOnLimit>

L'elemento <ThrowExceptionOnLimit> specifica cosa succede quando vengono raggiunti i limiti di acquisizione relativi al numero di variabili o alla dimensione massima di una variabile. Vedi Applicazione dei limiti di acquisizione.

Il valore di <ThrowExceptionOnLimit> può essere uno dei seguenti:

  • false: i dati per le variabili vengono inviati ad Analytics.
  • true: viene restituito un messaggio di errore e i dati non vengono inviati ad Analytics.

Riferimento agli errori

Errori di runtime

La tabella seguente descrive gli errori di runtime, che possono verificarsi durante l'esecuzione della policy.

Codice di errore Causa
DataCollectorTypeMismatch

Il valore da acquisire non corrisponde al tipo DataCollector.
ExtractionFailure L'estrazione dei dati non è riuscita.
UnresolvedVariable La variabile non esiste.
VariableCountLimitExceeded Il numero di variabili acquisite ha superato il limite di 100 variabili.
VariableValueLimitExceeded La dimensione di un valore acquisito ha superato il limite di 400 byte per singola variabile.
MsgContentParsingFailed Impossibile analizzare i contenuti del messaggio in formato XML o JSON.
InvalidMsgContentType Il tipo di contenuti del messaggio non corrisponde al tipo di contenuti del messaggio previsto nella clausola di acquisizione delle norme.
NonMsgVariable Il valore dell'elemento <Source> non fa riferimento a una variabile del messaggio.
JSONPathQueryFailed La query JSONPath non è riuscita a restituire un valore.
PrivateVariableAccess Tentativo di accesso a una variabile privata non riuscito.
XPathEvaluationFailed XPath non è stato risolto in un valore.

Gli errori di runtime vengono restituiti in due modi:

  • Risposta di errore al client (continueOnError=false)

    Quando l'attributo continueOnError del criterio è impostato su false, gli errori che si verificano durante l'esecuzione del criterio interrompono l'elaborazione del messaggio e restituiscono un messaggio di errore descrittivo. Il criterio tenterà di acquisire tutti gli errori pertinenti nel criterio di acquisizione dei dati prima di restituire il messaggio.

  • DataCapture campo di analisi degli errori

    Il campo dataCapturePolicyErrors contiene un elenco di tutti gli errori che si sono verificati. Di seguito è riportato un esempio di come apparirebbe nella mappa dei dati di analisi:

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

Questo campo è soggetto al limite di dimensione variabile di 400 byte.

Errori di deployment

Codice di errore Causa
DeploymentAssertionError DataCollector a cui viene fatto riferimento nelle norme non è stato trovato nell'organizzazione durante il deployment.
JsonPathCompilationFailed La compilazione con JSONPath specificato non è riuscita.
XPathCompilationFailed Se il prefisso o il valore utilizzato nell'elemento XPath non fa parte di nessuno degli spazi dei nomi dichiarati nel criterio, il deployment del proxy API non va a buon fine.
PatternCompilationFailed La compilazione del pattern non è riuscita.

Ricerca di DataCapture errori nello strumento di debug

La variabile dataCapturePolicyErrors è disponibile nello strumento di debug. Questo è uno strumento aggiuntivo che puoi utilizzare per rilevare gli errori senza accedere ad Analytics. Ad esempio, puoi rilevare un errore che si verifica se esegui l'upgrade della versione del runtime ibrido e interrompi inavvertitamente l'analisi in un proxy già sottoposto a deployment.

Applicazione dei limiti di acquisizione

Apigee applica i seguenti limiti alle variabili nei dati acquisiti:

  • Il numero di variabili consentite è 100.
  • La dimensione massima di ogni variabile (inclusi i valori dell'elenco) è 400 byte.

Quando l'esecuzione delle norme di acquisizione dei dati, prima che un valore venga aggiunto alla mappa di acquisizione dei dati nel contesto del messaggio:

  • Se è stato raggiunto il limite al numero di variabili, la nuova variabile verrà eliminata.
  • Se è stato raggiunto il limite di dimensione delle variabili, il valore verrà troncato per rientrare nei limiti desiderati.

In entrambi i casi:

  • Un messaggio di debug verrà registrato nel log del processore di messaggi.
  • Un messaggio di errore limit reached verrà aggiunto a dataCapturePolicyErrors, che sarà disponibile sia in Analytics che in Debug. Nota: Verrà aggiunto un solo messaggio di errore per il raggiungimento del numero massimo di variabili consentite.
  • Se <ThrowExceptionOnLimit> è true, i dati non vengono inviati ad Analytics e al client viene restituito un errore.

Argomenti correlati