Norme di DataCapture

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Icona DataCapture

Panoramica

Il criterio DataCapture acquisisce i dati (ad es. il payload, le intestazioni HTTP e i parametri path o query) da un proxy API per utilizzarli in Analytics. Puoi utilizzare i dati acquisiti nei report personalizzati di Analytics, nonché per implementare le regole di monetizzazione e monitoraggio.

Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

Risorsa del raccoglitore dei dati

Per utilizzare il criterio DataCapture, devi prima creare una risorsa Raccogli dati. Per la procedura per creare una risorsa del raccoglitore di dati utilizzando l'interfaccia utente di Apigee o l'API Apigee, consulta Creare 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 criteri DataCapture:

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

L'elemento principale del criterio DataCapture è l'elemento <Capture>, che specifica i mezzi per acquisire i dati. Ha due elementi secondari obbligatori:

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

L'elemento <Collect> offre anche diversi altri modi per acquisire i dati da varie fonti tramite i suoi elementi secondari. Consulta la sezione Esempi per altri esempi di acquisizione dei dati con il criterio 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

Gli esempi riportati di seguito illustrano vari modi per utilizzare il criterio DataCapture.

Acquisizione dei dati per una variabile integrata

L'esempio di codice riportato di seguito illustra come acquisire i dati per una variabile interna, message.content, che contiene i contenuti della richiesta, della risposta o del messaggio di errore. Per ulteriori informazioni sulle variabili integrate, consulta la sezione Voci 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 è denominata "message.content".

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

Acquisizione dei dati in linea

L'esempio seguente mostra come acquisire i dati in linea 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. La voce risultante inviata ad Analytics sarà

{
    "dc_data_collector": "1120"
}

<Acquisisci>

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 del raccoglitore 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 Acquisire i dati di monetizzazione.

 N/D Facoltativo Stringa

Il corpo dell'elemento <DataCollector> contiene il nome della risorsa del collector 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
predefinito Specifica il valore inviato ad Analytics se il valore della variabile non viene compilato in fase di esecuzione. 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 inserito in fase di esecuzione, 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 dagli 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 dal campo proxy.pathsuffix di un messaggio dell'origine richiesta.
<QueryParam> Facoltativo Estrae un valore dal parametro di query specificato di un messaggio di origine 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 indichi il nome del messaggio da analizzare. Il valore di <Source> è message per impostazione predefinita. Il valore message è sensibile al contesto. In un flusso di richieste, message si risolve nel messaggio di richiesta. In un flusso di risposta, message si risolve nel messaggio di risposta.

Se la variabile specificata in <Source> non può essere risolta o se si risolve in un tipo diverso da messaggio, il criterio 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 risolve 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 le maiuscole/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 si risolve 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 query. Se più parametri di ricerca hanno lo stesso nome, utilizza il riferimento indicizzato, in cui la prima istanza del parametro di query non ha indice, la seconda è all'indice 2, la terza all'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 singola variabile denominata {$}. Potrebbero essere presenti più elementi Pattern univoci, ma il primo modello 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 il riferimento indicizzato, in cui la prima istanza dell'intestazione non ha indice, la seconda è all'indice 2, la terza all'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>

In alternativa, puoi utilizzare il seguente comando per elencare tutte le intestazioni nell'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 di 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 uno 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>

<Namespaces>

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 gli spazi dei nomi nelle espressioni XPath, puoi omettere o commentare l'elemento <Namespaces>, come illustrato 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 utilizzato per fare riferimento allo spazio dei nomi nell'espressione XPath. Non deve essere lo stesso prefisso 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> del criterio.

<ThrowExceptionOnLimit>

L'elemento <ThrowExceptionOnLimit> specifica cosa succede quando vengono raggiunti i limiti di acquisizione per il numero di variabili o la dimensione massima di una variabile. Consulta Applicare i limiti di acquisizione.

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

  • false: i dati relativi alle variabili vengono inviati ad Analytics.
  • true: viene visualizzato un messaggio di errore e i dati non vengono inviati ad Analytics.

Riferimento all'errore

Errori di runtime

La tabella seguente descrive gli errori di runtime che possono verificarsi durante l'esecuzione del criterio.

Codice guasto 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 Le dimensioni di un valore acquisito hanno superato il limite di 400 byte per singola variabile.
MsgContentParsingFailed Non è stato possibile analizzare i contenuti del messaggio in 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 faceva riferimento a una variabile di messaggio.
JSONPathQueryFailed Impossibile risolvere la query JSONPath in un valore.
PrivateVariableAccess Tentativo di accesso a una variabile privata non riuscito.
XPathEvaluationFailed Impossibile risolvere XPath 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 interromperanno l'elaborazione del messaggio e restituiranno 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 viene visualizzato 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 dimensioni variabili di 400 byte.

Errori di deployment

Codice guasto Causa
DeploymentAssertionError Non è stato possibile trovare il DataCollector a cui fa riferimento il criterio 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 Compilazione della sequenza non riuscita.

Ricerca di errori DataCapture nello strumento di debug

La variabile dataCapturePolicyErrors è disponibile nello strumento di debug. Si tratta di 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à di cui è stato eseguito il 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.

Durante l'esecuzione del criterio 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 di numero di variabili, la nuova variabile verrà eliminata.
  • Se è stato raggiunto il limite di dimensione delle variabili, il valore verrà troncato in modo da rientrare nei limiti desiderati.

In entrambi i casi:

  • Nel log del processore di messaggi verrà registrato un messaggio di debug.
  • A dataCapturePolicyErrors verrà aggiunto un messaggio di errore limit reached, che sarà disponibile sia in Analytics sia 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 viene restituito un errore al client.

Argomenti correlati