Gespeicherte Prozeduren für die tägliche Wartung

Einführung

Snowflake Connector for Google Analytics Aggregate Data bietet mehrere gespeicherte Prozeduren, mit denen Sie die Datenaufnahme und die Konfiguration der Konnektoren programmgesteuert verwalten können. Im Folgenden finden Sie eine detaillierte Beschreibung der einzelnen gespeicherten Prozeduren, einschließlich deren Verwendung, Parameter und Beispiele.

Konfigurieren eines neuen Berichts

Die Prozedur CONFIGURE_REPORT konfiguriert einen neuen Bericht für die Datenaufnahme von Google Analytics 4 (GA4) in Snowflake. Diese Prozedur verwendet die Parameter des Berichts als Eingabe, einschließlich Dimensionen, Kennzahlen und Datenaufnahme-Zeitplan.

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

Wobei:

report_name

Eine Zeichenfolge, die den Namen des zu konfigurierenden Berichts angibt. Dieser Name wird als Präfix für die Tabellen mit Rohdaten verwendet, die in der Zieldatenbank erstellt wurden. Nach der erstmaligen Datenaufnahme wird der Berichtsname als Name für die in der Zieldatenbank erstellten Ansichten verwendet. Erforderlich

Für den Berichtsnamen muss Folgendes gelten:

  • Er muss entweder mit einem Buchstaben (Groß- oder Kleinbuchstaben) oder einem Unterstrich beginnen,

  • worauf eines oder mehrere Zeichen folgen, die Buchstaben (Groß- oder Kleinbuchstaben), Ziffern oder Unterstriche sein können,

  • und er darf höchstens 150 Zeichen lang sein.

property_id

Eine Zeichenfolge, die die ID der Google Analytics 4-Eigenschaft angibt, die für den Bericht verwendet werden soll. Die Eigenschafts-ID ist als Zahl formatiert, die aus dem GA4-Konto ermittelt wird. Stellen Sie sicher, dass die PROPERTY_ID einer GA4-Eigenschaft entspricht, auf die über die Authentifizierungsmethode des Konnektors zugegriffen werden kann (oauth2 oder Dienstkonto). Erforderlich

dimensions

Eine durch Kommas getrennte Liste von GA4-Dimensionen, die in den Bericht aufgenommen werden sollen. Die Dimensionen müssen durch Kommas getrennt werden. Wenn die date-Dimension nicht explizit angegeben ist, wird sie automatisch hinzugefügt. Es können maximal neun Dimensionen angegeben werden (einschließlich date). Erforderlich

Beispiel: 'country,city,deviceCategory,sessions'

metrics

Eine durch Kommas getrennte Liste von GA4-Kennzahlen, die in den Bericht aufgenommen werden sollen. Es ist mindestens eine Kennzahl erforderlich und es sind maximal zehn Kennzahlen zulässig. Erforderlich

Beispiel: 'sessions,pageViews'.

start_date

Eine Zeichenfolge, die das Startdatum des Berichts angibt. Das Datum muss im Format YYYY-MM-DD vorliegen. Es werden Daten ab diesem Datum aufgenommen. Erforderlich

refresh_interval

Eine Zeichenfolge, die das Aktualisierungsintervall für den Bericht angibt. Erforderlich. Das Intervall muss eines der folgenden Formate haben:

  • 'EVERY <Anzahl Minuten> MINUTE'

  • 'EVERY <Anzahl Stunden> HOUR'

  • 'EVERY <Anzahl Tage> DAY'

keep_empty_rows

Optional. Der Standardwert ist false. Wenn dies auf true festgelegt ist, enthält die Ausgabetabelle Datensätze mit Dimensionskombinationen, bei denen alle Kennzahlen null sind. Dies ist nützlich für die Analyse von Dimensionskombinationen ohne Ereignisse.

avoid_sampling

Optional. Der Standardwert ist false. Wenn dies auf true festgelegt ist, kann der Konnektor die Art und Weise anpassen, wie er die Daten von der GA4 API abruft, um zu versuchen, ein Datensampling zu vermeiden. Kann die Datengenauigkeit verbessern, kann jedoch die Häufigkeit von API-Aufrufen erhöhen.

Bemerkung

Es gibt keine Garantie, dass kein Sampling der Daten erfolgt. Der Konnektor versucht, das Sampling zu vermeiden, aber dies ist möglicherweise nicht in allen Fällen möglich. Dies ist auf die Einschränkungen der GA4 API zurückzuführen.

Beispiel:

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

Entfernen des vorhandenen Berichts

Die Prozedur DELETE_REPORT löscht eine bestehende Berichtskonfiguration aus dem Konnektor und stoppt damit jede weitere Datenaufnahme für diesen Bericht. Bereits aufgenommene Daten werden nicht entfernt.

CALL DELETE_REPORT( <report_name> );
Copy

Wobei:

report_name

Eine Zeichenfolge, die den Namen des zu löschenden Berichts angibt. Muss mit dem REPORT_NAME übereinstimmen, der in CONFIGURE_REPORT verwendet wird. Erforderlich

Beispiel:

CALL DELETE_REPORT('USER_ENGAGEMENT_REPORT');
Copy

Eigenschaften des Google Analytics 4-Kontos auflisten

Die Prozedur GET_PROPERTIES gibt eine Liste aller Google Analytics 4-Eigenschaften zurück, die für die Erfassung durch den Konnektor verfügbar sind.

CALL GET_PROPERTIES();
Copy

Beispielausgabe der Prozedur:

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

Bemerkung

Der Konnektor muss über die erforderlichen Berechtigungen für den Zugriff auf die Eigenschaften verfügen. Wenn ein Ergebnis leer ist, überprüfen Sie die Zugriffsrechte in GA4.

Abrufen von Dimensionen und Kennzahlen für GA4-Eigenschaften

Die Prozedur GET_DIMENSIONS_AND_METRICS ruft die Liste der verfügbaren Dimensionen und Kennzahlen für eine angegebene GA4-Eigenschaft ab.

CALL GET_DIMENSIONS_AND_METRICS( <property_id> );
Copy

Wobei:

property_id

Eine Zeichenfolge, die die ID der Google Analytics 4-Eigenschaft angibt, die für den Bericht verwendet werden soll. Die Eigenschafts-ID ist als Zahl formatiert, die aus dem GA4-Konto ermittelt wird. Stellen Sie sicher, dass die property_id einer GA4-Eigenschaft entspricht, auf die über die Authentifizierungsmethode des Konnektors zugegriffen werden kann (oauth2 oder Dienstkonto). Erforderlich

Beispiel:

CALL GET_DIMENSIONS_AND_METRICS('123456789');
Copy

Beispielausgabe für die Prozedur:

{
  "dimensions": [
    {
      "dimension": "achievementId", "category": "Other", "description": "Some description."
    }
  ],
  "metrics": [
    {
      "metric": "active1DayUsers", "category": "User", "description": "Some description."
    },
    {
      "metric": "active28DayUsers", "category": "User", "description": "Some description."
    }
  ]
}
Copy

Bemerkung

Die verfügbaren Dimensionen und Kennzahlen können zwischen den Eigenschaften variieren.

Pausieren des Konnektors

Die Prozedur PAUSE_CONNECTOR hält den Konnektor an und stoppt die gesamte Datenaufnahme und -verarbeitung.

CALL PAUSE_CONNECTOR();
Copy

Bemerkung

  • Beim Anhalten des Konnektors wird die Datenaufnahme für alle konfigurierten Berichte angehalten.

  • Die Datenaufnahme kann mit RESUME_CONNECTOR fortgesetzt werden.

  • Vorhandene Daten bleiben während des Anhaltens zugänglich.

Fortsetzen des Konnektors

Die Prozedur RESUME_CONNECTOR setzt den Konnektor fort und beginnt mit der gesamten Datenaufnahme und Verarbeitung, die zuvor angehalten wurden. Die Datenaufnahme wird an dem Punkt fortgesetzt, an dem sie unterbrochen wurde.

CALL RESUME_CONNECTOR();
Copy

Aufnahme nach Bedarf

Die Prozedur INGEST_NOW plant die Datenaufnahme für den angegebenen Bericht im Konnektor. Diese Prozedur kann verwendet werden, um die Datenaufnahme für einen bestimmten Bericht außerhalb der geplanten Intervalle manuell zu initiieren.

Bemerkung

Die Prozedur plant die sofortige Datenaufnahme für den angegebenen Bericht unter Verwendung von EXECUTE TASK .... Das bedeutet, dass die Datenaufnahme so schnell wie möglich beginnt, aber möglicherweise nicht sofort erfolgt, insbesondere wenn die Datenaufnahme für denselben Bericht bereits ausgeführt wird. Stellen Sie sicher, dass der Konnektor nicht angehalten wurde, bevor Sie diese Prozedur aufrufen.

CALL INGEST_NOW('<report_name>');
Copy

Wobei:

report_name

Eine Zeichenfolge, die den Namen des aufzunehmenden Berichts angibt. Muss mit dem REPORT_NAME übereinstimmen, der in CONFIGURE_REPORT verwendet wird. Erforderlich

Beispiel:

CALL INGEST_NOW('USER_ENGAGEMENT_REPORT');
Copy

Abrufen des aktuellen Status des Konnektors

Bemerkung

Die Konnektorbezeichnungen state und status werden im Kontext dieses Dokuments austauschbar verwendet. Der Status des Konnektors kann über die Prozedur GET_CONNECTOR_STATUS abgerufen werden.

CALL GET_CONNECTOR_STATUS();
Copy

Beispielausgabe der Prozedur:

{
  "response_code": "OK",
  "status": "STARTED",
  "configurationStatus": "PREREQUISITES_DONE"
}
Copy

Gibt ein JSON-Objekt mit den folgenden Feldern zurück:

  • response_code: wenn die Prozedur erfolgreich ausgeführt wurde, wird der Wert OK zurückgegeben. Ein anderer Antwortcode als OK gibt einen Fehler an.

  • status: Der aktuelle Status des Konnektors. Dieser Status kann sich nur ändern, wenn Sie den Konnektor installieren/neu installieren, pausieren, fortsetzen oder den Konfigurationsprozess abschließen. Kann einen der folgenden Werte haben:

    • CONFIGURING: Dies ist der Standardstatus, der eingestellt wird, nachdem der Konnektor aus dem Freigabeangebot oder Anwendungspaket installiert wurde. Der Konnektor bleibt in diesem Zustand, bis der Konfigurationsprozess abgeschlossen ist. Nachdem die Konfiguration abgeschlossen ist, geht der Konnektor in den Status STARTED über.

    • STARTED: Sobald der Konnektor vollständig konfiguriert oder fortgesetzt wurde, wechselt er in den Status STARTED.

    • PAUSED: Wenn der Konnektor erfolgreich angehalten wurde, wechselt er in den Status PAUSED.

    • ERROR: Wenn der Konnektor auf einen nicht rückgängig zu machenden Fehler stößt, geht er zum in den Status ERROR über, der anzeigt, dass er nicht aktiv genutzt werden kann. In diesem Status kann die Prozedur RECOVER_CONNECTOR_STATE verwendet werden, um in einen gültigen Status überzugehen.

  • configurationStatus: Dies ist ein Unterstatus des Hauptstatus CONFIGURING. Der Prozess der Konnektorkonfiguration ist in mehrere Schritte unterteilt, die durch diesen Unterstatus verfolgt werden. Kann einen der folgenden Werte haben:

    • INSTALLED: Die Konfiguration beginnt im Status INSTALLED, nachdem die Konnektor-Instanz erstellt wurde.

    • PREREQUISITES_DONE: Nachdem der Benutzer die Voraussetzungen erfüllt hat und die Prozedur MARK_ALL_PREREQUISITES_AS_DONE aufruft, geht die Konfiguration in den Status PREREQUISITES_DONE über. Voraussetzungen sind manuelle Schritte, die vom Benutzer ausgeführt werden müssen, z. B. das Konfigurieren der Verbindung zu einer Datenquelle eines Drittanbieters oder das Erstellen einer Zieldatenbank.

    • CONFIGURED: Die Prozedur CONFIGURE_CONNECTOR(VARIANT) wurde aufgerufen.

    • CONNECTED: Die Prozedur SET_CONNECTION_CONFIGURATION(VARIANT) wurde aufgerufen.

    • FINALIZED: Nach Abschluss der Konfiguration geht die Konfiguration schließlich in den Status FINALIZED über (die Prozedur FINALIZE_CONNECTOR_CONFIGURATION(VARIANT) wurde aufgerufen).

Neustart des Konfigurationsprozesses

Die gespeicherte Prozedur RESET_CONFIGURATION setzt die Konfiguration des Konnektors auf den Standardstatus zurück. Diese Prozedur kann verwendet werden, um die Konfiguration des Konnektors zurückzusetzen, bevor die Konfiguration abgeschlossen ist. Damit die Prozedur funktioniert, muss sich der Konnektor im Status CONFIGURING befinden. Weitere Informationen zu den Hauptstatus und Unterstatus der Konfiguration von Konnektoren finden Sie unter Abrufen des aktuellen Status des Konnektors.

Falls die Konfigurationsphase abgeschlossen ist (FINALIZED), gibt diese Prozedur einen Fehler zurück.

CALL RESET_CONFIGURATION();
Copy

Wiederherstellung nach einem Zwischen- oder Fehlerstatus

Die Prozedur RECOVER_CONNECTOR_STATE ist dazu gedacht, den Konnektor wiederherzustellen, wenn er in einem Zwischen- oder Fehlerzustand feststeckt (ERROR, STARTING, PAUSING), indem sein Status manuell entweder auf STARTED oder PAUSED festgelegt wird. Einige Operationen können dazu führen, dass der Konnektor in einem inkonsistenten Zustand bleibt, was aus verschiedenen Gründen geschehen kann. Beispiel: Wenn der Benutzer Berechtigungen für bestimmte Datenbankobjekte löscht, die der Konnektor benötigt.

Die Prozedur gibt einen Fehler zurück, wenn der neue Status ungültig ist oder wenn sich der Konnektor in keinem der vorgegebenen Status befindet. Die folgenden Übergänge sind zulässig:

  • ERROR -> PAUSED

  • ERROR -> STARTED

  • PAUSING -> PAUSED

  • PAUSING -> STARTED

  • STARTING -> PAUSED

  • STARTING -> STARTED

CALL RECOVER_CONNECTOR_STATE('<new_state>');
Copy

Wobei:

new_state

Eine Zeichenfolge, die den neuen Status des Konnektors angibt. Der Status muss entweder STARTED oder PAUSED sein. Erforderlich

Beispiel:

CALL RECOVER_CONNECTOR_STATE('STARTED');
Copy

Wiederherstellen von Berichten, nachdem ein Konnektor gelöscht wurde

Die Prozedur IMPORT_STATE wird verwendet, um konfigurierte Berichte und den Datenaufnahmeverlauf wiederherzustellen, nachdem der Konnektor deinstalliert wurde. Diese Prozedur soll verwendet werden, nachdem der Konnektor neu installiert wurde und der neue Konnektor so konfiguriert wurde, dass er dieselbe Datenbank verwendet, die von dem deinstallierten Konnektor verwendet wurde. Der Status, der importiert wird, befindet sich in der Zieldatenbank, die von der vorherigen Instanz des Konnektors verwendet wurde, in Form von Tabellen mit dem Suffix SFSDKEXPORT. Um mehr über den Prozess zu erfahren, lesen Sie das Notfallwiederherstellung-Benutzerhandbuch. Die Prozedur überschreibt den bestehenden Status im Konnektor nicht, wenn sie feststellt, dass der Status nicht sauber ist, es sei denn, der Parameter force ist auf true festgelegt. Ein sauberer Status ist ein Status direkt nach Abschluss des Konfigurationsprozesses, wenn noch keine Berichte konfiguriert sind. Wenn Berichte konfiguriert, aber später gelöscht wurden, wird ebenfalls davon ausgegangen, dass der Status nicht sauber ist.

Bemerkung

Wenn der Konnektor mit den Optionen CASCADE deinstalliert (gelöscht) wurde, funktioniert diese Prozedur nicht.

CALL IMPORT_STATE([force]);
Copy

Wobei:

force

Optional. Der Standardwert ist false. Wenn true, überschreibt die Prozedur den bestehenden Status des Konnektors. Einschließlich aller Berichte, die bereits konfiguriert sind. Wenn false, gibt die Prozedur einen Fehler zurück, wenn sie feststellt, dass der Status nicht sauber ist.

Beispiel:

CALL IMPORT_STATE();
Copy
Sprache: Deutsch