Documentation

1Introduction

La fonction d’analytics permet aux commerçants d’analytics rapidement leurs transactions dans PostFinance Checkout et d’obtenir des informations sur leurs performances commerciales. Grâce à un accès structuré à leurs données, ils peuvent prévoir comment s’adapter aux besoins des clients. Les rapports peuvent être personnalisés en écrivant des requêtes SQL, et toutes les analyses de données sont alimentées par PrestoDB, un moteur de requête SQL open-source fourni par Amazon Athena.

Le Analytics Schema décrit les structures de données exportées de la base de données principale de PostFinance Checkout, qui peuvent être interrogées dans l’interface utilisateur du portail et l’API REST.

2Aperçu

L’aperçu de toutes les exécutions de requêtes analytiques est accessible dans le compte sous Account > Analytics > Queries

Liste des exécutions de requêtes analytiques
Figure 1. La liste des exécutions de requêtes analytiques est visible dans le compte.

2.1Exécuter la soumission de la requête

Le marchand peut soumettre une requête dans son compte spécifique sous Account > Analytics > Submit Query

Soumettre une requête Analytics
Figure 2. La requête peut être soumise en cliquant sur le bouton Soumettre.

Une requête soumise est traitée de manière asynchrone. Initialement, l’exécution de la requête aura un statut PROCESSING, et aucun détail ne sera disponible. Une fois l’exécution de la requête traitée et terminée, l’état passe à SUCCESS et les détails de la requête peuvent être récupérés.

Si l’exécution de la requête échoue ou est annulée avant d’être terminée, l’état devient FAILED ou CANCELLED, respectivement, et aucune information détaillée sur la requête n’est disponible.

Pour les restrictions relatives à la soumission de la requête, voir Contrôle d`accès et autorisations.

2.1.1Actifs

La partie gauche de l’éditeur de requêtes présente le Panneau des actifs, un centre de découverte et de gestion de vos données. Ce panneau affiche :

  • Tables disponibles: Une liste de tables et de vues qui vous sont accessibles (en fonction de vos droits d’utilisateur), classées par ordre alphabétique.

  • Favoris: Une collection de requêtes sauvegardées pour un accès rapide.

  • Exemples: Une collection d’exemples de requêtes qui peuvent être utilisés comme source d’inspiration.

  • Connaissance des autorisations: Les tables sont automatiquement filtrées en fonction de vos droits d’accès.

Analytics query assets
Figure 3. Les actifs de l’éditeur de requêtes pour faciliter l’utilisation.

2.2Exécuter la soumission de requête récurrente

Pour programmer l’exécution régulière de requêtes analytiques, utilisez la fonction Recurring Query (Requête récurrente).

Étape 1 : Créer une requête récurrente

Etape 2 : Configurer les autorisations de requête

  • Les requêtes récurrentes héritent des autorisations de l'User ID assigné à la requête. Cela garantit un accès cohérent aux données pour les types d’utilisateurs réels et d’application.

  • Important : l’ID de l’utilisateur détermine le contexte de sécurité pour l’exécution de la requête.

Étape 3 : Définir la date de début

  • La date de Début le indique quand la requête commencera à être exécutée et cliquez sur Créer.

  • Note: Un plan d’ordonnancement valide doit être configuré à l’étape suivante pour que la requête puisse être exécutée.

Étape 4 : Définir le calendrier d’exécution

2.2.1Calendrier quotidien

  • Exécute la requête à l’heure spécifiée les jours de la semaine définis.

  • Exemple: Exécuter la requête tous les lundis à 9:00.

Référence visuelle:

Requête quotidienne récurrente d'Analytics
Figure 4. Ressources de l’éditeur de requêtes pour faciliter l’utilisation.

2.2.2Programme mensuel

  • Exécute la requête à l’heure spécifiée les jours définis du mois.

  • Exemple: Exécuter le 15 de chaque mois.

Référence visuelle:

Analyse des horaires de requêtes mensuelles récurrentes
Figure 5. Analyse des horaires de requêtes mensuelles récurrentes.

2.2.3Principaux éléments à prendre en compte pour les horaires mensuels

Repli sur le dernier jour : Last Day Fallback:

Si votre requête doit être exécutée le dernier jour du mois, utilisez cette fonction :

  1. Sélectionnez 31st comme jour.

  2. Cochez l’option "Use last day fallback ".

    • La requête sera automatiquement ajustée pour être exécutée le dernier jour valide des mois les plus courts (par exemple, 28 février, 30 avril).

Référence visuelle:

Soumettre une requête récurrente d'Analytics
Figure 6. Soumettre une requête récurrente d’Analytics.

2.2.4Pourquoi c`est important

  • Permissions cohérentes : Les requêtes récurrentes fonctionnent dans le même contexte de sécurité que les comptes d’utilisateur, ce qui garantit que l’accès aux données est conforme aux politiques de votre organisation.

  • Programmation flexible : Les options quotidiennes et mensuelles permettent un contrôle précis du moment où les requêtes sont exécutées, avec une logique de repli pour gérer les cas extrêmes tels que les mois plus courts.

  • Efficacité Automatisez les tâches répétitives pour gagner du temps et réduire les efforts manuels.

2.3Détails de l’exécution de la requête

L’ouverture d’une requête spécifique affichera les informations détaillées, y compris la requête SQL soumise, un lien de téléchargement vers le fichier de résultat (au format CSV), et les actions disponibles pour la requête (par exemple, l’annulation de l’exécution de la requête).

Analytics Query Execution Details
Figure 7. les détails de l’exécution de la requête.

2.4Annuler l’exécution de la requête

L’exécution d’une requête dans l’état PROCESSING peut être annulée en cliquant sur le bouton Annuler l’exécution de la page de vue [Détails de l’exécution de la requête].

Si l’exécution de la requête a déjà atteint un état final (SUCCESS, FAILED, ou CANCELLED), la tentative d’annulation sera ignorée.

3L`API REST des requêtes analytiques

Le Analytics Queries REST API est utilisé pour gérer l’exécution des requêtes Analytics. Il permet aux utilisateurs de soumettre des requêtes, de récupérer les résultats au format CSV, de surveiller l’exécution des requêtes et d’annuler les requêtes en cours.

Pour une référence complète de l’API, voir la documentation Analytics Queries REST API.

3.1Exemple : Liste des clients par montant cumulé des transactions

Dans cet exemple, une requête est exécutée pour lister les clients en fonction du montant qu’ils ont dépensé dans l’espace marchand. En utilisant le Analytics Schema, nous construisons la requête SQL PrestoDB suivante, qui calcule la somme des montants de transaction groupés par client:

SELECT SUM(completedamount) AS total, customerid
FROM transaction
GROUP BY customerid
ORDER BY total DESC ;
Note
L’utilisateur doit spécifier les noms de tables et de colonnes en minuscules, car ils sont stockés en interne en minuscules, même si les mots-clés SQL, les clauses et les mots-clés réservés (tels que SELECT) ne sont pas sensibles à la casse.

3.2Soumettre l`exécution de la requête

Une requête peut être soumise pour exécution en utilisant la méthode Submit Query Execution Request (HTTP POST). Le corps de la requête doit contenir une structure Analytics Query Execution Request au format JSON.

Pour soumettre notre exemple de requête, nous envoyons le JSON suivant :

{
 "accountId" : 2,
 "sql" : "SELECT SUM(completedamount) AS total, customerid FROM transaction GROUP BY customerid ORDER BY total DESC"
}

La requête sera exécutée dans le compte avec l’ID 2 (spécifié dans le paramètre accountId). La requête SQL réelle est fournie dans le paramètre sql. Pour plus de détails, voir {access-control-and-permissions}.

La réponse à une requête de soumission sera une structure Analytics Query Execution Response au format JSON, contenant le queryToken de l’exécution :

{
"queryToken" : "4d135f47-8c13-4b51-86ce-08c5d0f33a00"
}

3.3Surveiller l`état d`exécution de la requête

Une requête soumise est traitée de manière asynchrone. Au départ, l’exécution de la requête sera dans l’état PROCESSING, et aucun résultat ne sera disponible. Une fois l’exécution de la requête traitée et terminée, l’état passe à SUCCESS et les résultats de la requête peuvent être récupérés.

Si l’exécution de la requête échoue ou est annulée avant d’être terminée, l’état devient FAILED ou CANCELLED, respectivement, et aucun résultat n’est renvoyé.

L’état actuel d’une requête précédemment soumise peut être vérifié à l’aide de la méthode API Query Execution Status (HTTP GET) avec queryToken comme paramètre de chemin URL (utilisez queryToken que vous avez obtenu lors de votre appel initial à Soumettre l`exécution de la requête.

La réponse à l’appel à la méthode Query Execution Status sera une structure Submitted Query Execution. Dans notre exemple, l’URL de la requête ressemblera à ceci :

/api/v2.0/analytics/queries/4d135f47-8c13-4b51-87ce-08c5d0f33a00

Lorsque l’exécution de la requête atteint le statut SUCCESS, une réponse similaire à la suivante est reçue :

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

Ce Query Execution Status est une requête de longue durée, avec un délai maximum d’environ 100 secondes. Les requêtes sont traitées de manière asynchrone et peuvent prendre plusieurs minutes avant d’atteindre le statut final, ce qui implique généralement de longues interrogations, qui peuvent prendre jusqu’à 100 secondes. Si l’exécution de la requête a toujours le statut PROCESSING après ce temps, il est recommandé de répéter l’appel plus tard. Evitez de faire des requêtes fréquentes à cette méthode API, car cela n’aura aucun effet sur le traitement de la requête.

Codes d’état HTTP:

  • 200 OK : La requête a atteint son statut final. Si la requête est encore en cours de traitement, un statut 200 est retourné avec un en-tête Retry-After.

  • 5xx - Erreurs internes du serveur.

3.4Annuler l`exécution de la requête

L’exécution d’une requête dans l’état PROCESSING peut être annulée en utilisant la méthode Cancel Query Execution (HTTP DELETE). Inclure le queryToken de la réponse Soumettre l`exécution de la requête

L’URL de la requête se présentera comme suit :

/api/v2.0/analytics/queries/4d135f47-8c13-4b51-87ce-08c5d0f33a00

L’annulation de l’exécution d’une requête renvoie toujours une réponse vide, sauf en cas d’erreur. Si l’exécution de la requête a déjà atteint un état final (SUCCESS, FAILED, ou CANCELLED), la tentative d’annulation sera silencieusement ignorée.

3.5Obtenir les résultats de l`exécution de la requête

Une fois que le Query Execution Status renvoie un état SUCCESS, les résultats de l’exécution de la requête peuvent être récupérés en appelant la méthode API Query Execution Result (requête HTTP GET). Incluez le queryToken de la réponse Soumettre l`exécution de la requête.

The request URL will look as follows:

api/v2.0/analytics/queries/4d135f47-8c13-4b51-86ce-08c5d0f33a00/result

Le corps de la réponse contient une URL Amazon S3 temporaire (valable pendant environ 5 minutes), semblable à ce qui suit :

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

La méthode Query Execution Result génère une URL éphémère (valable 5 minutes) pour le fichier de résultat de la requête analytique. Chaque téléchargement du fichier de sortie est payant, et nous comptons également chaque génération d’URL de fichier comme une tentative de téléchargement potentielle.

Veuillez NE PAS utiliser cette méthode API pour des vérifications périodiques de la disponibilité du fichier de résultat - utilisez Query Execution Status pour des vérifications périodiques à la place.

Codes d’état HTTP:

  • 200 OK : L’URL éphémère est disponible.

  • 202 Accepted : Le résultat devrait être disponible plus tard.

  • 204 No Content : L’ensemble des résultats est vide (cela peut indiquer que la requête a été annulée ou a échoué).

  • 404 Not Found : Aucune requête n’a été trouvée pour le token donné.

4Contrôle d`accès et autorisations

La disponibilité des tables et des données est régie par les rôles d’utilisateur, qui sont configurés par votre administrateur de compte. Ces rôles déterminent les données auxquelles les utilisateurs peuvent accéder et les actions qu’ils peuvent effectuer.

Exemple

  • Si un utilisateur n’a pas l’accès en lecture à la table des transactions, celle-ci n’apparaîtra pas dans le panneau Actifs et toute requête tentant d’y faire référence échouera.

  • De même, les requêtes exécutées dans des espaces non associés au compte de l’utilisateur entraîneront une erreur d’autorisation, car l’accès à est limité aux espaces auxquels l’utilisateur peut accéder.

Considérations clés:

  • Accès basé sur le rôle* : Les autorisations sont liées aux rôles des utilisateurs, ce qui garantit la sécurité des données et la conformité.

  • Contrôle au niveau du compte : Les administrateurs de compte gèrent les attributions de rôles pour contrôler qui peut accéder à des tables, des vues ou des ensembles de données spécifiques.

Besoin de modifications d’accès?

Si vous avez besoin d’accéder à des tables, des ensembles de données ou des espaces de travail supplémentaires, veuillez consulter votre responsable de compte. Il peut aider à ajuster les autorisations en fonction de vos besoins.