La funzione di analisi aiuta gli esercenti ad analizzare rapidamente le loro transazioni all’interno di staging-wallee.com e a ottenere informazioni sulle prestazioni della loro attività. Grazie all’accesso strutturato ai propri dati, possono prevedere come adattarsi alle esigenze dei clienti. I report possono essere personalizzati scrivendo query SQL e tutte le analisi dei dati sono gestite da PrestoDB, un motore di query SQL open-source fornito da Amazon Athena.
Lo Schema Analytics descrive le strutture di dati esportate dal database principale di staging-wallee.com, che possono essere interrogate nell’interfaccia utente del portale e nelle API REST.
La panoramica di tutte le esecuzioni delle query di analytics è accessibile all’interno dell’account all’indirizzo
Figure 1. L’elenco delle esecuzioni delle query di Analytics è visibile nell’account.
L’esercente può inviare una query all’interno dell’account specifico dell’esercente all’indirizzo Account > Analytics > Submit Query
Figure 2. La query può essere inviata cliccando sul pulsante
Submit.Una query inviata viene elaborata in modo asincrono.
Inizialmente, l’esecuzione della query avrà uno stato PROCESSING e nessun dettaglio sarà disponibile.
Una volta che l’esecuzione della query è stata elaborata e completata, lo stato passerà a SUCCESS e i dettagli della query potranno essere recuperati.
Se l’esecuzione della query fallisce o viene annullata prima del completamento, lo stato passerà rispettivamente a FAILED o SUCCESS e non saranno disponibili informazioni dettagliate sulla query.
Per le restrizioni sull’invio della query, fare riferimento a Controllo degli accessi e permessi.
Il lato sinistro dell’editor di query presenta il pannello Assets, un centro centralizzato per la scoperta e la gestione dei dati. Questo pannello di visualizza:
-
Tabelle disponibili: Un elenco di tabelle e viste accessibili (in base ai permessi dell’utente), ordinate alfabeticamente.
-
Preferiti: Una raccolta curata di query salvate per un accesso rapido.
-
Esempi: Una raccolta di query di esempio che possono essere utilizzate come ispirazione.
-
Consapevolezza dei permessi: Le tabelle vengono filtrate automaticamente in base ai diritti di accesso dell’utente.
Figure 3. Risorse dell’editor di query per una maggiore facilità d’uso.
Per programmare le query di analisi per l’esecuzione regolare, utilizzare la funzione Query ricorrente.
Fase 1: Creare una query ricorrente.
-
Andare a: Account > Analytics > Query ricorrenti
Fase 2: Configurare le autorizzazioni per le query.
-
Le query ricorrenti ereditano le autorizzazioni dall’ID utente assegnato alla query. Questo garantisce un accesso coerente ai dati per sia per gli utenti reali che per quelli applicativi.
-
L’ID utente determina il contesto di sicurezza per l’esecuzione della query.
Passo 3: Definire la data di avvio
-
La data di inizio specifica quando la query inizierà a essere eseguita e fare clic su Crea.
-
Nota: per l’esecuzione della query è necessario impostare un piano di pianificazione valido nel passaggio successivo.
Fase 4: Definire la pianificazione dell’esecuzione.
-
Esegue la query a un’ora specifica nei giorni della settimana definiti.
-
Esempio: Eseguire ogni lunedì alle 9:00.
Riferimento visivo:
Figure 4. Query editor assets for ease of use.
-
Esegue la query a un’ora specifica nei giorni definiti del mese.
-
Esempio: Eseguita il 15 di ogni mese.
Riferimento visivo:
Figure 5. Pianificazione della query mensile ricorrente di Analytics.
Fallback dell’ultimo giorno:
Se la query deve essere eseguita l'ultimo giorno del mese, utilizzare questa funzione:
-
Selezionare 31 come giorno.
-
Selezionate l’opzione "Usa fallback ultimo giorno ".
-
La query si regolerà automaticamente per essere eseguita l'ultimo giorno valido dei mesi più brevi (ad esempio, 28 febbraio, 30 aprile).
-
Riferimento visivo:
Figure 6. Invia query ricorrente di Analytics.
-
Autorizzazioni coerenti: Le query ricorrenti operano nello stesso contesto di sicurezza degli account utente, garantendo che l’accesso ai dati sia in linea con i criteri dell’organizzazione.
-
Pianificazione flessibile: Le opzioni giornaliere e mensili consentono un controllo preciso sull’esecuzione delle query, con una logica di fallback per gestire i casi limite di , come i mesi più brevi.
-
Efficienza: Automatizzate le attività ripetitive per risparmiare tempo e ridurre l’impegno manuale.
L’apertura di un’esecuzione specifica di una query visualizzerà le informazioni dettagliate, tra cui la richiesta SQL della query inviata, un link per scaricare il file dei risultati (in formato CSV) e le azioni disponibili per la query (ad esempio, l’annullamento dell’esecuzione della query).
Figure 7. I dettagli dell’esecuzione della query.
L’esecuzione di una query nello stato PROCESSING può essere annullata facendo clic sul pulsante Annulla esecuzione dalla pagina di visualizzazione dettagliata dell’esecuzione della query [Dettagli dellesecuzione della query].}
Se l’esecuzione della query ha già raggiunto uno stato finale (SUCCESS, FAILED o CANCELLED), il tentativo di annullamento verrà ignorato.
Il servizio Analytics Queries REST API è utilizzato per gestire l’esecuzione delle query di Analytics.
Consente agli utenti di inviare richieste di query, recuperare i risultati in formato CSV, monitorare l’esecuzione delle query e annullare le query in corso.
Per il riferimento completo all’API, consultare la documentazione di Analytics Queries REST API.
In questo esempio, viene eseguita una query per elencare i clienti ordinati in base all’importo speso nello spazio del commerciante. Utilizzando lo schema Schema Analytics, si costruisce la seguente query PrestoDB SQL, che calcola la somma degli importi delle transazioni raggruppate per cliente:
SELECT SUM(completedamount) AS total, customerid
FROM transaction
GROUP BY customerid
ORDER BY total DESC;|
Note
|
L’utente deve specificare i nomi delle tabelle e delle colonne in minuscolo, in quanto vengono memorizzati internamente in minuscolo, anche se le parole chiave SQL, le clausole e le parole chiave riservate (come SELECT) sono insensibili alle maiuscole.
|
Una richiesta di query può essere inviata per l’esecuzione utilizzando il metodo Submit Query Execution Request (HTTP POST).
Il corpo della richiesta deve contenere una struttura Analytics Query Execution Request in formato JSON.
Per inviare la nostra query di esempio, inviamo il seguente JSON:
{
"accountId": 2,
"sql": "SELECT SUM(completedamount) AS total, customerid FROM transaction GROUP BY customerid ORDER BY total DESC"
}La richiesta di query sarà eseguita all’interno dell’account con ID 2 (specificato nel parametro accountId).
La query SQL effettiva è fornita nel parametro sql.
Per maggiori dettagli, fare riferimento a Controllo degli accessi e permessi.
La risposta a una richiesta di invio sarà una struttura Analytics Query Execution Response in formato JSON, contenente il queryToken dell’esecuzione:
{
"queryToken": "4d135f47-8c13-4b51-86ce-08c5d0f33a00"
}Una query inviata viene elaborata in modo asincrono.
Inizialmente, l’esecuzione della query sarà in stato PROCESSING e nessun risultato sarà disponibile.
Una volta che l’esecuzione della query è stata elaborata e completata, lo stato passerà a SUCCESS e i risultati della query potranno essere recuperati.
Se l’esecuzione della query fallisce o viene annullata prima del completamento, lo stato passerà rispettivamente a FAILED o CANCELLED e non verranno restituiti risultati.
Lo stato attuale di una query precedentemente inviata può essere controllato utilizzando il metodo API Query Execution Status (HTTP GET) con queryToken impostato come parametro del percorso URL (utilizzare queryToken ottenuto dalla chiamata iniziale a [Inviare lesecuzione della query]).
La risposta della chiamata al metodo Query Execution Status sarà una struttura Submitted Query Execution. Nel nostro esempio, l’URL della richiesta sarà simile a questo:
/api/v2.0/analytics/queries/4d135f47-8c13-4b51-87ce-08c5d0f33a00Quando l’esecuzione della query raggiunge lo stato SUCCESS, si riceve una risposta simile alla seguente:
{
"accountId": 2,
"createdTimestamp": "2025-03-21T07:56:56.110252Z",
"downloadRequests": 0,
"originalQuery": "SELECT SUM(completedAmount) AS total, customerId FROM transaction GROUP BY customerId ORDER BY total DESC",
"portalQueryToken": "4d135f47-8c13-4b51-87ce-08c5d0f33a00",
"resultFileBytes": 1476198,
"scannedBytes": 763075,
"status": "SUCCESS",
"totalBilledExecutionTimeMs": 1295
}|
Note
|
Questo Query Execution Status è una richiesta a lungo termine, con un timeout massimo di circa Codici di stato HTTP
|
L’esecuzione di una query nello stato PROCESSING può essere annullata con il metodo Cancel Query Execution (HTTP DELETE).
Includere il queryToken dalla risposta [Inviare lesecuzione della query].
L’URL della richiesta avrà il seguente aspetto:
/api/v2.0/analytics/queries/4d135f47-8c13-4b51-87ce-08c5d0f33a00L’annullamento dell’esecuzione di una query restituisce sempre una risposta vuota, a meno che non ci sia un errore.
Se l’esecuzione della query ha già raggiunto uno stato finale (SUCCESS, FAILED o CANCELLED), il tentativo di annullamento verrà ignorato silenziosamente.
Una volta che il Query Execution Status restituisce uno stato SUCCESS, i risultati dell’esecuzione della query possono essere recuperati chiamando il metodo API Query Execution Result (richiesta HTTP GET).
Includere il queryToken dalla risposta [Inviare l’esecuzione della query].
L’URL della richiesta avrà il seguente aspetto:
api/v2.0/analytics/queries/4d135f47-8c13-4b51-86ce-08c5d0f33a00/resultIl corpo della risposta contiene un URL Amazon S3 temporaneo (valido per circa 5 minuti), simile al seguente:
https://...s3.eu-west-1.amazonaws.com/query-results/72aaf6a7-86eb-49bb-bded-5ef34e79385b.csv?X-Amz-Security-Token=[...]&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250321T082449Z&X-Amz-SignedHeaders=host&X-Amz-Credential=[...]&X-Amz-Expires=300&X-Amz-Signature=[...]|
Note
|
Il metodo Query Execution Result genera un URL di breve durata (valido per 5 minuti) per il file dei risultati della query di Analytics. Ogni download del file di output comporta un costo e ogni generazione dell’URL del file viene conteggiata come un potenziale tentativo di download. NON utilizzare questo metodo API per verificare periodicamente la disponibilità del file dei risultati, ma utilizzare Query Execution Status per i controlli periodici. Codici di stato HTTP
|
La disponibilità di tabelle e dati è regolata dai ruoli utente, configurati dall’amministratore dell’account. Questi ruoli determinano a quali dati gli utenti possono accedere e quali azioni possono eseguire.
Esempio
-
Se un utente non ha l’accesso in lettura alla tabella delle transazioni, questa non apparirà nel Pannello delle attività e qualsiasi query che tenti di farvi riferimento fallirà.
-
Allo stesso modo, le query eseguite in spazi non associati all’account dell’utente risulteranno in un errore di autorizzazione, poiché l’accesso a è limitato agli spazi a cui l’utente può accedere.
Considerazioni chiave
-
Accesso basato sui ruoli*: Le autorizzazioni sono legate ai ruoli degli utenti, per garantire la sicurezza e la conformità dei dati.
-
Controllo a livello di account*: Gli amministratori degli account gestiscono l’assegnazione dei ruoli per controllare chi può accedere a tabelle, viste o dataset specifici di .
Avete bisogno di modifiche all’accesso?
Se avete bisogno di accedere a tabelle, set di dati o spazi di lavoro aggiuntivi, consultate il vostro Account Manager. Essi possono aiutare a modificare le autorizzazioni in base alle vostre esigenze.