Procédures stockées pour la maintenance quotidienne¶

Introduction¶

Le Snowflake Connector for Google Analytics Aggregate Data fournit plusieurs procédures stockées qui vous permettent de gérer votre ingestion de données et la configuration de vos connecteurs par programmation. Vous trouverez ci-dessous des descriptions détaillées de chaque procédure stockée, y compris leur utilisation, des paramètres et des exemples.

Configuration d’un nouveau rapport¶

La procédure``CONFIGURE_REPORT`` configure un nouveau rapport pour l’ingestion de données à partir de Google Analytics 4 (GA4) dans Snowflake. Cette procédure prend en entrée les paramètres du rapport, notamment les dimensions, les métriques et la planification d’ingestion.

CALL CONFIGURE_REPORT( <report_name>, <property_id>, <dimensions>, <metrics>, <start_date>, <refresh_interval>[, <keep_empty_rows>][, <avoid_sampling>]);

Copy

Où :

report_name

Chaîne qui spécifie le nom du rapport à configurer. Ce nom sera utilisé comme préfixe pour les tables contenant des données brutes créées dans la base de données de destination. Après l’ingestion initiale, le nom du rapport sera utilisé comme nom pour les vues créées dans la base de données de destination. Requis.

Le nom du rapport doit :

commencer par une lettre (majuscule ou minuscule) ou un tiret bas ;
continuer avec un ou plusieurs caractères qui peuvent être des lettres (majuscules ou minuscules), des chiffres ou des tirets bas ;
comporter 150 caractères ou moins.

property_id

Une chaîne spécifiant l’identifiant de propriété Google Analytics 4 à utiliser pour le rapport. L’identifiant de propriété se présente sous la forme d’un numéro pouvant être obtenu à partir du compte GA4. Assurez-vous que l’PROPERTY_ID correspond à une propriété GA4 accessible par la méthode d’authentification des connecteurs (oauth2 ou compte de service). Requis.

dimensions

Une liste de dimensions GA4 séparées par des virgules à inclure dans le rapport. Les dimensions doivent être séparées par des virgules. Si la dimension``date`` n’est pas explicitement spécifiée, elle sera ajoutée automatiquement. Vous pouvez spécifier neuf dimensions maximum (y compris date). Requis.

Exemple : 'country,city,deviceCategory,sessions'

metrics

Une liste de métriques GA4 séparées par des virgules à inclure dans le rapport. Au moins une métrique est requise, avec un maximum de dix métriques. Requis.

Exemple : 'sessions,pageViews'.

start_date

Une chaîne qui spécifie la date de début du rapport. La date doit être au format YYYY-MM-DD. Les données à partir de cette date seront ingérées. Requis.

refresh_interval

Une Chaîne qui spécifie l’intervalle d’actualisation du rapport. Requis. L’intervalle doit avoir l’un des formats suivants :

'EVERY <nombre de minutes> MINUTE'

'EVERY <nombre d'heures> HOUR'

'EVERY <nombre de jours> DAY'

keep_empty_rows

En option. La valeur par défaut est false. Si true, la table de sortie comprend des enregistrements avec des combinaisons de dimensions où toutes les métriques sont égales à zéro. Utile pour analyser les combinaisons de dimensions sans événements.

avoid_sampling

En option. La valeur par défaut est false. Si true, le connecteur peut ajuster la façon dont il extrait les données de l’API GA4 pour éviter l’échantillonnage des données. Peut améliorer la précision des données, mais peut augmenter la fréquence d’appel API.

Note

Il n’y a aucune garantie que les données ne seront pas échantillonnées. Le connecteur essaiera d’éviter l’échantillonnage, mais cela peut ne pas être possible dans tous les cas. Ceci est dû aux limitations de l’API GA4.

Exemple :

CALL CONFIGURE_REPORT(
    REPORT_NAME => 'USER_ENGAGEMENT_REPORT',
    PROPERTY_ID => '123456789',
    DIMENSIONS => 'country,deviceCategory',
    METRICS => 'activeUsers,newUsers',
    START_DATE => '2023-01-01',
    REFRESH_INTERVAL => 'EVERY 1 DAY',
    KEEP_EMPTY_ROWS => TRUE,
    AVOID_SAMPLING => TRUE
);

Copy

Suppression d’un rapport existant¶

La procédure DELETE_REPORT supprime du connecteur une configuration de rapport existante, ce qui arrête toute ingestion de données supplémentaire pour ce rapport. Les données déjà ingérées ne seront pas supprimées.

CALL DELETE_REPORT( <report_name> );

Copy

Où :

report_name

Une chaîne qui spécifie le nom du rapport à supprimer. Doit correspondre au REPORT_NAME utilisé dans CONFIGURE_REPORT. Requis.

Exemple :

CALL DELETE_REPORT('USER_ENGAGEMENT_REPORT');

Copy

Répertorier les propriétés du compte Google Analytics 4¶

Le procédure GET_PROPERTIES renvoie une liste de toutes les propriétés Google Analytics 4 disponibles pour l’ingestion par le connecteur.

CALL GET_PROPERTIES();

Copy

Exemple de sortie de la procédure :

{[
  { "propertyName": "test1", "propertyId": "1" },
  { "propertyName": "test2", "propertyId": "2" },
  { "propertyName": "test3", "propertyId": "3" }
]}
Copy
Note

Le connecteur doit disposer des autorisations nécessaires pour accéder aux propriétés. Si un résultat est vide, vérifiez les droits d’accès dans GA4.

Récupération des dimensions et de la métrique pour la propriété GA4¶

La procédure GET_DIMENSIONS_AND_METRICS récupère la liste des dimensions et des métriques disponibles pour une propriété GA4 donnée.

CALL GET_DIMENSIONS_AND_METRICS( <property_id> );

Copy

Où :

property_id

Une chaîne spécifiant l’identifiant de propriété Google Analytics 4 à utiliser pour le rapport. L’identifiant de propriété se présente sous la forme d’un numéro pouvant être obtenu à partir du compte GA4. Assurez-vous que l”property_id correspond à une propriété GA4 accessible par la méthode d’authentification des connecteurs (oauth2 ou compte de service). Requis.

Exemple :
CALL GET_DIMENSIONS_AND_METRICS('123456789');
Copy
Exemple de sortie de la procédure :
{
  "dimensions": [
    {
      "dimension": "achievementId", "category": "Other", "description": "Some description."
    }
  ],
  "metrics": [
    {
      "metric": "active1DayUsers", "category": "User", "description": "Some description."
    },
    {
      "metric": "active28DayUsers", "category": "User", "description": "Some description."
    }
  ]
}
Copy
Note

Les dimensions et les métriques disponibles peuvent varier d’une propriété à l’autre.

Mise en pause du connecteur.¶

La procédure PAUSE_CONNECTOR met le connecteur en pause, ce qui arrête l’ingestion et le traitement des données.

CALL PAUSE_CONNECTOR();
Copy
Note

La mise en pause du connecteur interrompt l’ingestion de données pour tous les rapports configurés.

L’ingestion des données peut être reprise via RESUME_CONNECTOR.

Les données existantes restent accessibles pendant la pause.

Relance du connecteur¶

La procédure RESUME_CONNECTOR relance le connecteur en démarrant l’ensemble de l’ingestion et du traitement des données qui était précédemment interrompu. L’ingestion des données reprend au point où elle a été interrompue.

CALL RESUME_CONNECTOR();

Copy

Ingestion à la demande¶

La procédure``INGEST_NOW`` planifie l’ingestion de données pour le rapport spécifié dans le connecteur. Cette procédure peut être utilisée pour lancer manuellement l’ingestion de données pour un rapport spécifique en dehors des intervalles planifiés.

Note

La procédure planifie l’ingestion immédiate du rapport spécifié à l’aide de la fonction EXECUTE TASK .... Cela signifie que l’ingestion commencera dès que possible, mais qu’elle peut ne pas être instantanée, en particulier si l’ingestion du même rapport est déjà en cours. Assurez-vous que le connecteur n’est pas en pause avant d’appeler cette procédure.
CALL INGEST_NOW('<report_name>');
Copy

Où :

report_name

Une chaîne qui spécifie le nom du rapport à ingérer. Doit correspondre au REPORT_NAME utilisé dans CONFIGURE_REPORT. Requis.

Exemple :

CALL INGEST_NOW('USER_ENGAGEMENT_REPORT');

Copy

Obtention de l’état actuel du connecteur¶

Note

Les state et status du connecteur sont utilisés de manière interchangeable dans le contexte de ce document. Le statut/l’état du connecteur peut être récupéré à l’aide de la procédure GET_CONNECTOR_STATUS.
CALL GET_CONNECTOR_STATUS();
Copy
Exemple de sortie de la procédure :
{
  "response_code": "OK",
  "status": "STARTED",
  "configurationStatus": "PREREQUISITES_DONE"
}
Copy

La procédure renvoie un objet JSON avec les champs suivants :

response_code : si la procédure a bien été exécutée, la valeur OK est renvoyée. Un code de réponse différent de OK indique une erreur.
status : l’état actuel du connecteur. Cet état ne peut changer que lorsque vous (ré)installez, mettez en pause, relancez le connecteur ou finalisez le processus de configuration. Il peut avoir l’une des valeurs suivantes :
- CONFIGURING : il s’agit de l’état par défaut défini après l’installation du connecteur à partir de la liste ou du paquet d’application. Le connecteur reste dans cet état jusqu’à ce que le processus de configuration soit finalisé. Une fois la configuration finalisée, le connecteur passe à l’état STARTED.
- STARTED : une fois que le connecteur est entièrement configuré ou relancé, il passe à l’état STARTED.
- PAUSED : lorsque le connecteur est bien mis en pause, il passe à l’état PAUSED.
- ERROR : si le connecteur rencontre une erreur irréversible, il passe à l’état ERROR, indiquant qu’il ne peut pas être utilisé activement. Lorsqu’il est dans cet état, la procédure RECOVER_CONNECTOR_STATE peut être utilisée pour passer à un état valide.
configurationStatus : il s’agit d’un sous-état de l’état principal CONFIGURING. Le processus de configuration du connecteur est divisé en quelques étapes qui sont suivies par ce sous-état. Il peut avoir l’une des valeurs suivantes :
- INSTALLED : la configuration démarre à l’état INSTALLED après la création de l’instance du connecteur.
- PREREQUISITES_DONE : une fois que l’utilisateur a rempli les conditions préalables et appelé la procédure``MARK_ALL_PREREQUISITES_AS_DONE``, la configuration passe à l’état PREREQUISITES_DONE. Les conditions préalables sont des étapes manuelles qui doivent être exécutées par l’utilisateur, par exemple la configuration de la connexion à une source de données tierce ou la création d’une base de données de destination.
- CONFIGURED : la procédure CONFIGURE_CONNECTOR(VARIANT) a été appelée.
- CONNECTED : la procédure SET_CONNECTION_CONFIGURATION(VARIANT) a été appelée.
- FINALIZED : enfin, après avoir terminé la configuration, la configuration passe à l’état FINALIZED (la procédure FINALIZE_CONNECTOR_CONFIGURATION(VARIANT) a été appelée).

Redémarrage du processus de configuration¶

La procédure stockée RESET_CONFIGURATION réinitialise la configuration du connecteur à son état par défaut. Cette procédure peut être utilisée pour réinitialiser la configuration du connecteur avant que la configuration n’ait été finalisée. Pour que la procédure fonctionne, le connecteur doit être à l’état CONFIGURING. Pour en savoir plus sur les états principaux et les sous-états de configuration du connecteur, reportez-vous à Obtention de l’état actuel du connecteur.

Si la phase de configuration est terminée (FINALIZED), cette procédure renverra une erreur.

CALL RESET_CONFIGURATION();

Copy

Récupération à partir d’un état intermédiaire ou erroné¶

La procédure RECOVER_CONNECTOR_STATE a pour but de récupérer le connecteur lorsqu’il est bloqué dans un état intermédiaire ou d’erreur (ERROR, STARTING, PAUSING) en définissant manuellement son état sur STARTED ou PAUSED. Certaines opérations peuvent entraîner des incohérences au niveau du connecteur et cela peut se produire pour diverses raisons. Par exemple, lorsque l’utilisateur supprime des autorisations pour certains objets de base de données dont le connecteur a besoin.

La procédure renverra une erreur si le nouvel état n’est pas valide ou si le connecteur ne se trouve pas dans l’un des états prédéterminés. Les transitions suivantes sont autorisées :

ERROR -> PAUSED.

ERROR -> STARTED.

PAUSING -> PAUSED.

PAUSING -> STARTED.

STARTING -> PAUSED.

STARTING -> STARTED.
CALL RECOVER_CONNECTOR_STATE('<new_state>');
Copy

Où :

new_state

Une chaîne qui spécifie le nouvel état du connecteur. L’état doit être STARTED ou PAUSED. Requis.

Exemple :

CALL RECOVER_CONNECTOR_STATE('STARTED');

Copy

Récupération des rapports après la suppression d’un connecteur¶

La procédure IMPORT_STATE est utilisée pour récupérer les rapports configurés et l’historique des ingestions après la désinstallation du connecteur. Cette procédure est destinée à être utilisée une fois que le connecteur a été réinstallé et que le nouveau connecteur a été configuré pour utiliser la même base de données que celle utilisée par le connecteur désinstallé. L’état en cours d’importation se trouve dans la base de données de destination utilisée par l’instance précédente du connecteur, sous la forme de tables avec le suffixe``SFSDKEXPORT``. Pour en savoir plus sur le processus, consultez le guide Reprise après sinistre. La procédure n’écrasera pas l’état existant dans le connecteur si elle détecte que l’état n’est pas intact, à moins que le paramètre force soit défini sur true. L’état intact est l’état qui suit immédiatement la finalisation du processus de configuration lorsqu’aucun rapport n’est configuré. Si les rapports ont été configurés mais supprimés ultérieurement, l’état est également supposé ne pas être intact.

Note

Lorsque le connecteur a été désinstallé (supprimé) avec les options CASCADE, cette procédure ne fonctionnera pas.
CALL IMPORT_STATE([force]);
Copy

Où :

force

En option. La valeur par défaut est false. Si true, la procédure écrasera l’état existant dans le connecteur. Y compris tous les rapports déjà configurés. Si false, la procédure renverra une erreur si elle détecte que l’état n’est pas intact.

Exemple :

CALL IMPORT_STATE();

Copy