Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza
documentazione di Apigee Edge.
Panoramica
Il criterio Data Capture acquisisce dati (ad esempio payload, intestazioni HTTP e parametri di percorso o di query) da un proxy API per l'uso in Analytics. Puoi usare i dati acquisiti nei report personalizzati di Analytics, nonché per implementare senso, monetizzazione, e regole di monitoraggio.
Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni per l'utilizzo, consulta Tipi di criteri.
Risorsa raccoglitore dati
Per utilizzare il criterio DataCapture
, devi prima creare un
raccoglitore dati. Per conoscere i passaggi per creare una risorsa raccoglitore dati utilizzando l'interfaccia utente di Apigee
l'API Apigee, vedi
Creazione di un raccoglitore dati.
<DataCapture>
L'elemento <DataCapture>
definisce un criterio DataCapture
.
<DataCapture async="true" continueOnError="true" enabled="true" name="DC">
Ecco un esempio di criterio DataCapture
:
<DataCapture name="DC-1"> <Capture> <DataCollector>dc_data_collector</DataCollector> <Collect ref="my_data_variable" /> </Capture> </DataCapture>
L'elemento principale del
Il criterio DataCapture
è l'elemento <Capture>
,
che specifica i mezzi per acquisire i dati. Ha due elementi secondari obbligatori:
- Lo
<DataCollector>
, che specifica un risorsa REST del raccoglitore dati. In questo caso, la risorsa è denominatadc_data_collector
. - L'elemento
<Collect>
, che specifica i mezzi per acquisire i dati.
In questo semplice esempio, i dati vengono estratti da una variabile denominata
my_data_variable
, che è stato creato altrove nel proxy.
La variabile è specificata dall'attributo ref
.
L'elemento <Collect>
offre anche diversi altri modi
di acquisire dati da varie origini tramite
elementi secondari.
Consulta gli esempi per ulteriori esempi di acquisizione dei dati.
con il criterio DataCapture
.
La sintassi dell'elemento DataCapture
è la seguente.
<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/A | Obbligatorio |
Il nome interno del criterio. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
continueOnError |
falso | Facoltativo | Imposta su false per restituire un errore in caso di errore del criterio. Questo è un comportamento previsto per
la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un errore nel 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 | Deprecato | 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 DataCapture
.
Acquisizione dei dati per una variabile integrata
L'esempio di codice seguente illustra come acquisire i dati
per una variabile integrata, message.content
, che contiene
contenuti della richiesta, della risposta o del messaggio di errore. Consulta
Variabili di flusso per
maggiori informazioni sulle variabili integrate.
<DataCapture name="DC-FullMessage"> <Capture> <DataCollector>dc_data_collector</DataCollector> <Collect ref="message.content" /> </Capture> </DataCapture>
Nel codice precedente, l'attributo ref
dell'elemento </Collect>
specifica la variabile da acquisire, che in questo esempio è
denominato "message.content"
.
L'esempio acquisisce i dati con un elemento <Capture>
,
che contiene anche un elemento <DataCollector>
che specifica
il nome della risorsa raccoglitore dati.
Acquisizione dei dati in linea
Il prossimo esempio mostra come acquisire i dati in linea utilizzando
<JSONPayload>
, un elemento secondario di
<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. - La
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
il messaggio è stato ricevuto: 1120
. Poi
la voce risultante inviata ad Analytics
{ "dc_data_collector": "1120" }
<Capture>
L'elemento <Capture>
specifica il metodo 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 raccoglitore dati. |
<Collect> |
Obbligatorio | Specifica i mezzi per acquisire i dati. |
<DataCollector>
L'elemento <DataCollector>
specifica
di raccolta dei dati.
<DataCollector>dc_data_collector</DataCollector>Nella tabella seguente vengono descritti gli attributi dell'elemento
<DataCollector>
.
Attributo | Descrizione | Predefinito | Obbligatorio? | Tipo |
---|---|---|---|---|
ambito |
Specifica questo attributo e imposta il valore su |
N/D | Facoltativo | Stringa |
Il corpo dell'elemento <DataCollector>
contiene il nome dell'elemento
raccoglitore dati.
<Collect>
L'elemento <Collect>
specifica i mezzi per acquisire i dati.
<Collect ref="existing-variable" default="0"/>
Nella tabella seguente vengono descritti gli attributi dell'elemento <Collect>
.
Attributo | Descrizione | Predefinito | Obbligatorio? | Tipo |
---|---|---|---|---|
riferimento |
La variabile per la quale stai acquisendo i dati. |
N/D | Facoltativo: se ref viene omesso, esattamente uno dei valori
è necessario specificare quanto segue:
QueryParam ,
Header ,
FormParam ,
URIPath ,
JSONPayload oppure
XMLPayload .
|
Stringa |
predefinita | Specifica il valore inviato ad Analytics se il valore
la variabile non viene compilata in fase di runtime. Ad esempio, se imposti
default="0" , il valore inviato ad Analytics sarà 0.
|
Se non specifichi il valore
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
oppure
per 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 dalla tabella proxy.pathsuffix
di un messaggio di origine della 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 di risposta specificato. |
<FormParam> |
Facoltativo | Estrae un valore dal parametro del modulo specificato del messaggio di richiesta o di 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 la variabile da analizzare. Il valore di
Il valore predefinito di <Source>
è message
. Il valore message
è sensibile al contesto. In un flusso di richiesta, message
si risolve nel messaggio di richiesta. Nel
un flusso di risposta, message
si risolve nel messaggio di risposta.
Anche se spesso utilizzi questo criterio per estrarre informazioni da un messaggio di richiesta o di risposta,
puoi utilizzarlo per estrarre informazioni da qualsiasi variabile. Ad esempio, puoi usarlo per estrarre
informazioni di un'entità creata dal criterio AccessEntity, dai dati
restituiti dal criterio ServiceCallout oppure estrarre informazioni da un oggetto XML o JSON.
Se non è possibile risolvere <Source>
o se viene risolto in un tipo non messaggio,
il criterio non risponderà.
Valore predefinito | N/D |
Obbligatorio? | Facoltativo |
Tipo | Stringa |
Elemento principale |
<Collect> |
Elementi secondari | N/D |
Attributi
Attributo | Descrizione | Predefinito | Obbligatorio? | Tipo |
---|---|---|---|---|
clearPayload |
Impostalo su true se vuoi cancellare il payload specificato in
Utilizza l'opzione |
falso |
Facoltativo | Booleano |
<Source clearPayload="true|false">request</Source>
<URIPath>
Estrae un valore
da proxy.pathsuffix
di un messaggio di origine request
. Il percorso applicato a
il pattern è proxy.pathsuffix
, che non include il percorso base per il proxy API. Se
il messaggio di origine si risolve in un tipo di messaggio di 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 si risolve in un tipo di messaggio response
, l'elemento
niente.
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, usa i riferimenti indicizzati, in cui la prima istanza del parametro di query non ha un indice, il secondo è all'indice 2, il terzo all'indice 3, ecc. |
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 esserci più elementi Pattern
univoci, ma verrà usato il primo pattern corrispondente
per una determinata richiesta.
<Header>
Estrae un valore
dall'intestazione HTTP specificata dell'elemento request
specificato
response
messaggio. Se più intestazioni contengono
con lo stesso nome, i relativi valori sono archiviati 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ù
hanno lo stesso nome, usa riferimenti indicizzati, in cui la prima istanza
intestazione non ha un indice, la seconda è all'indice 2, la terza all'indice 3 e così via.
.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 nella array:
<Collect> <Header name="my_header.2"> <Pattern ignoreCase="true">{$}</Pattern> </Header> </Collect>
o di seguito 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 di modulo specificato del valore di request
o response
specificato
. Parametri modulo
può essere estratta 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 la
Messaggio in formato JSON da cui verrà estratto il valore della variabile. 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 la
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 la
Messaggio in formato XML da cui verrà estratto il valore della variabile. Payload XML
vengono estratte 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>
<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 il
<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 nell'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 deve essere necessariamente 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 . Sono supportate solo 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 dichiarare
gli spazi dei nomi
Sezione <XMLPayload><Namespaces>
delle norme.
<ThrowExceptionOnLimit>
L'elemento <ThrowExceptionOnLimit>
specifica cosa succede quando l'acquisizione
vengono raggiunti i limiti di numero di variabili
o la dimensione massima di una variabile. Consulta
Applicazione dei limiti di acquisizione.
Il valore di <ThrowExceptionOnLimit>
può essere uno dei seguenti:
false
: i dati relativi al valore vengono inviate ad Analytics.true
: È stato visualizzato un messaggio di errore e i dati non vengono inviati ad Analytics.
Riferimento errori
Errori di runtime
La tabella seguente descrive gli errori di runtime, che possono verificarsi durante l'esecuzione del criterio.
Codice di errore | Causa |
---|---|
DataCollectorTypeMismatch |
Il valore da acquisire non corrisponde al tipo |
ExtractionFailure |
Estrazione dei dati non riuscita. |
UnresolvedVariable |
La variabile non esiste. |
VariableCountLimitExceeded |
Il numero di variabili acquisite ha superato il limite di 100 variabili variabili |
VariableValueLimitExceeded |
La dimensione di un valore acquisito ha superato il limite di variabile singola di 400 byte. |
MsgContentParsingFailed |
Impossibile analizzare i contenuti del messaggio in XML o JSON. |
InvalidMsgContentType |
Il tipo di contenuto del messaggio non corrisponde a quello previsto nella clausola di acquisizione dei criteri. |
NonMsgVariable |
Il valore dell'elemento <Source> non faceva riferimento a una variabile del messaggio. |
JSONPathQueryFailed |
Impossibile risolvere la query JSONPath in un valore. |
PrivateVariableAccess |
Tentativo di accedere 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
)Se l'attributo
continueOnError
del criterio è impostato sufalse
, che si verificano durante L'esecuzione del criterio interromperà l'elaborazione dei messaggi e restituirà un messaggio di errore descrittivo. Il criterio tenterà di acquisire tutti gli errori pertinenti presenti nel criterio relativo all'acquisizione dei dati prima di restituire il messaggio. DataCapture
campo di analisi degli erroriIl campo
dataCapturePolicyErrors
contiene un elenco di tutti gli errori che si sono verificati. Un esempio di come apparirebbe nella mappa dei dati di analisi è come mostrato di seguito:# Example payload [ { errorType: TypeMismatch, policyName: MyDataCapturePolicy-1, dataCollector: purchaseValue }, { errorType: MaxValueSizeLimitReached, policyName: MyDataCapturePolicy-1, dataCollector: purchasedItems }, ]
Questo campo è soggetto al limite di 400 byte per le dimensioni delle variabili.
Errori di deployment
Codice di errore | Causa |
---|---|
DeploymentAssertionError |
Impossibile trovare il DataCollector a cui viene fatto riferimento nel criterio nell'organizzazione durante il deployment. |
JsonPathCompilationFailed |
Compilazione con il valore JSONPath specificato non riuscita. |
XPathCompilationFailed |
Se il prefisso o il valore utilizzato nell'elemento XPath non fa parte
di uno qualsiasi dei
gli spazi dei nomi dichiarati nel criterio, il deployment del proxy API
non riesce. |
PatternCompilationFailed |
Compilazione di pattern non riuscita. |
Individuare DataCapture
errore nello strumento di debug
La variabile dataCapturePolicyErrors
è disponibile nello strumento di debug.
Si tratta di uno strumento aggiuntivo che puoi utilizzare per individuare gli errori senza dover accedere ad Analytics.
Ad esempio, puoi individuare un errore che si verifica se esegui l'upgrade della versione del runtime ibrido
e interrompere inavvertitamente l'analisi in un proxy già distribuito.
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 dati, prima che venga aggiunto un valore alla mappa di acquisizione dati nella 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à tagliato per adattarsi entro i 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 adataCapturePolicyErrors
, disponibili sia in Analytics che in Debug. Nota: Verrà aggiunto un solo messaggio di errore per raggiungere il numero massimo di variabili consentite. - Se <ThrowExceptionOnLimit> è
true
, i dati non vengono inviati ad Analytics e viene restituito un errore al client.