日常のメンテナンスのためのストアドプロシージャ

概要

Snowflake Connector for Google Analytics Aggregate Data には、データインジェスションとコネクタ構成をプログラムで管理できるいくつかのストアドプロシージャが用意されています。以下は、使用法、パラメーター、例など、各ストアドプロシージャの詳細な説明です。

新しいレポートの構成

CONFIGURE_REPORT のプロシージャでGoogleアナリティクス4（GA4）からのデータインジェスション用の新しいレポートを構成し、Snowflakeに変換します。このプロシージャは、ディメンション、メトリック、インジェスションスケジュールなど、レポートのパラメーターを入力として受け取ります。

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

条件:

report_name

構成するレポートの名前を指定する文字列。この名前は、宛先データベースで作成された生データを含むテーブルのプレフィックスとして使用されます。最初のインジェスションの後、レポート名は宛先データベースで作成されたビューの名前として使用されます。必須です。

レポート名は次の必要があります。

  • 文字（大文字または小文字）またはアンダースコアで始まる。

  • 文字（大文字または小文字）、数字、またはアンダースコアなどの1つ以上の文字で続ける。

  • 150文字以下にする。

property_id

レポートに使用するGoogleアナリティクス4プロパティIDを指定する文字列。プロパティIDには、GA4 アカウントから取得可能な数値の形式があります。PROPERTY_ID が、コネクタの認証メソッド（oauth2またはサービスアカウント）でアクセスできる GA4 プロパティに対応していることを確認してください。必須です。

dimensions

レポートに含める GA4 ディメンションのコンマ区切りリスト。ディメンションはコンマで区切る必要があります。date ディメンションが明示的に指定されていない場合、自動的に追加されます。最大9つのディメンションを指定できます（date を含む）。必須です。

例: 'country,city,deviceCategory,sessions'

metrics

レポートに含める GA4 メトリックのコンマ区切りリスト。最低1つのメトリックが必要で、上限は10個です。必須です。

例: 'sessions,pageViews'.

start_date

レポートの開始日を指定する文字列。日付は YYYY-MM-DD の形式である必要があります。この日付以降のデータが取り込まれます。必須です。

refresh_interval

レポートのリフレッシュ間隔を指定する文字列。**必須です。**間隔は以下の形式のいずれかにする必要があります。

  • 'EVERY <分数> MINUTE'

  • 'EVERY <時間数> HOUR'

  • 'EVERY <日数> DAY'

keep_empty_rows

オプション。デフォルト値は false です。true の場合、出力テーブルには、すべてのメトリックがゼロであるディメンションの組み合わせを持つ記録が含まれます。イベントなしのディメンションの組み合わせを分析するのに便利です。

avoid_sampling

オプション。デフォルト値は false です。true の場合、コネクタは GA4 API からデータをフェッチする方法を調整して、データサンプリングを回避しようとします。データの精度を改善させることはできますが、API 呼び出し頻度が増加する可能性があります。

注釈

データがサンプリングされないという保証はありません。コネクタはサンプリングを回避しようとしますが、すべてのケースで可能というわけではありません。これは、GA4 API の制限によるものです。

例：

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

既存のレポートの削除

DELETE_REPORT プロシージャは、コネクタから既存のレポート構成を削除し、そのレポートに対するそれ以上のデータインジェスションを停止します。すでに取り込まれたデータは削除されません。

CALL DELETE_REPORT( <report_name> );
Copy

条件:

report_name

削除するレポートの名前を指定する文字列。CONFIGURE_REPORT で使用される REPORT_NAME と一致する必要があります。必須です。

例：

CALL DELETE_REPORT('USER_ENGAGEMENT_REPORT');
Copy

Googleアナリティクス4アカウントからのリストのプロパティ

GET_PROPERTIES プロシージャは、コネクタによってインジェスションに使用可能なすべてのGoogleアナリティクス4プロパティのリストを返します。

CALL GET_PROPERTIES();
Copy

プロシージャからの出力例:

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

注釈

コネクタには、プロパティにアクセスするために必要な権限が必要です。結果が空の場合は、GA4 でアクセス権を確認します。

GA4 プロパティのディメンションとメトリックを取得中

GET_DIMENSIONS_AND_METRICS プロシージャは、指定された GA4 プロパティの使用可能なディメンションとメトリックのリストを取得します。

CALL GET_DIMENSIONS_AND_METRICS( <property_id> );
Copy

条件:

property_id

レポートに使用するGoogleアナリティクス4プロパティIDを指定する文字列。プロパティIDには、GA4 アカウントから取得可能な数値の形式があります。property_id が、コネクタの認証メソッド（oauth2またはサービスアカウント）でアクセスできる GA4 プロパティに対応していることを確認してください。必須です。

例：

CALL GET_DIMENSIONS_AND_METRICS('123456789');
Copy

プロシージャからの出力例:

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

注釈

利用可能なディメンションとメトリックはプロパティによって異なる場合があります。

コネクタの一時停止

PAUSE_CONNECTOR プロシージャは、コネクタを一時停止し、すべてのデータのインジェスションと処理を停止します。

CALL PAUSE_CONNECTOR();
Copy

注釈

  • コネクタを一時停止すると、構成されているすべてのレポートのデータインジェスションが停止されます。

  • RESUME_CONNECTOR を使用してデータインジェスションを再開できます。

  • 一時停止中も既存のデータには引き続きアクセスできます。

コネクタの再開

RESUME_CONNECTOR プロシージャはコネクタを再開し、以前に一時停止していたすべてのデータのインジェスションと処理を開始します。データインジェスションは一時停止された時点から続行されます。

CALL RESUME_CONNECTOR();
Copy

オンデマンドでのインジェスション

INGEST_NOW プロシージャは、コネクタ内の指定されたレポートのデータインジェスションをスケジュールします。このプロシージャは、スケジュールされた間隔以外で、特定のレポートのデータインジェスションを手動で開始するために使用できます。

注釈

プロシージャは EXECUTE TASK ... を使用して、指定されたレポートの即時インジェスションをスケジュールします。つまり、インジェスションはできるだけ早く開始されますが、特に同じレポートのインジェスションがすでに進行中の場合は、即時開始されない可能性があります。このプロシージャを呼び出す前に、コネクタが一時停止されていないことを確認してください。

CALL INGEST_NOW('<report_name>');
Copy

条件:

report_name

取り込むレポートの名前を指定する文字列。CONFIGURE_REPORT で使用される REPORT_NAME と一致する必要があります。必須です。

例：

CALL INGEST_NOW('USER_ENGAGEMENT_REPORT');
Copy

コネクタの現在のステータスの取得

注釈

コネクタの state およびコネクタの status は、このドキュメントのコンテキストで同じ意味で使用されます。コネクタのステータス/状態は、GET_CONNECTOR_STATUS プロシージャを使用して取得できます。

CALL GET_CONNECTOR_STATUS();
Copy

プロシージャからの出力例:

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

プロシージャは次のフィールドを持つ JSON オブジェクトを返します。

  • response_code - プロシージャが正常に実行された場合、**OK**値が返されます。**OK**以外の応答コードはエラーを示します。

  • status -コネクタの現在のステータス。このステータスは、コネクタを再/インストール、一時停止、再開、または構成プロセスを完了した場合にのみ変更できます。次の値のいずれかを持つことができます。

    • CONFIGURING - これは、リストまたはアプリケーションパッケージからコネクタをインストールした後に設定されるデフォルトの状態です。コネクタは、構成プロセスが完了するまでこの状態のままです。構成が完了すると、コネクタは STARTED 状態に移行します。

    • STARTED - コネクタが完全に構成されるか、再開して STARTED 状態に移行します。

    • PAUSED - コネクタが正常に一時停止されると、PAUSED 状態に移行します。

    • ERROR - コネクタに不可逆なエラーが発生した場合、ERROR 状態に移行してアクティブに使用できないことを示します。この状態のとき、有効な状態に移行するために RECOVER_CONNECTOR_STATE プロシージャを使用できます。

  • configurationStatus - これはメインの CONFIGURING ステータスのサブステータスです。コネクタの構成プロセスは、このサブステータスによって追跡されるいくつかのステップに分割されます。次の値のいずれかを持つことができます。

    • INSTALLED - 構成は、コネクタインスタンスの作成後に INSTALLED 状態で開始されます。

    • PREREQUISITES_DONE - ユーザーが前提条件を完了して MARK_ALL_PREREQUISITES_AS_DONE プロシージャを呼び出した後、構成は PREREQUISITES_DONE 状態に移行します。前提条件は、サードパーティデータソースへの接続の構成や宛先データベースの作成など、ユーザーが実行する必要がある手動ステップです。

    • CONFIGURED - CONFIGURE_CONNECTOR(VARIANT) プロシージャが呼び出されました。

    • CONNECTED - SET_CONNECTION_CONFIGURATION(VARIANT) プロシージャが呼び出されました。

    • FINALIZED - 最後に、構成の完了後、構成は FINALIZED 状態（FINALIZE_CONNECTOR_CONFIGURATION(VARIANT) プロシージャが呼び出された）に移行します。

構成プロセスを再開中

RESET_CONFIGURATION ストアドプロシージャは、コネクタの構成をデフォルトの状態にリセットします。このプロシージャは、構成が確定する前にコネクタの構成をリセットするために使用できます。プロシージャを機能させるには、コネクタが CONFIGURING ステータスにある必要があります。コネクタのメインステータスと構成のサブステータスの詳細については、コネクタの現在のステータスの取得 をご参照ください。

構成フェーズが完了すると（FINALIZED）このプロシージャはエラーを返します。

CALL RESET_CONFIGURATION();
Copy

中間状態またはエラー状態からの回復

RECOVER_CONNECTOR_STATE プロシージャは、コネクタが中間状態またはエラー状態（ERROR、STARTING、PAUSING）でスタックしたときに、手動でステータスを STARTED または PAUSED のいずれかに設定してコネクタを回復することを目的としています。一部の操作では、コネクタの一貫性が失われる場合があります。これはさまざまな理由で発生する可能性があります。たとえば、ユーザーがコネクタに必要な特定のデータベースオブジェクトに対する権限をドロップする場合です。

新しい状態が有効でない場合、またはコネクタが事前に設定された状態のいずれかにない場合、プロシージャはエラーを返します。次の移行は許可されています。

  • ERROR -> PAUSED

  • ERROR -> STARTED

  • PAUSING -> PAUSED

  • PAUSING -> STARTED

  • STARTING -> PAUSED

  • STARTING -> STARTED

CALL RECOVER_CONNECTOR_STATE('<new_state>');
Copy

条件:

new_state

コネクタの新しい状態を指定する文字列。状態は STARTED または PAUSED. のいずれかである必要があります。必須です。

例：

CALL RECOVER_CONNECTOR_STATE('STARTED');
Copy

コネクタがドロップされた後のレポートの回復

IMPORT_STATE プロシージャは、コネクタのアンインストール後に構成されたレポートとインジェスション履歴を回復するために使用されます。このプロシージャは、コネクタが再インストールされ、アンインストールされたものと同じデータベースを使用するように新しいコネクタが構成された後に使用することを目的としています。インポート中の状態は、コネクタの以前のインスタンスによって使用される宛先データベースに、SFSDKEXPORT サフィックスが付くテーブルの形式で配置されます。プロセスの詳細については、障害復旧 ガイドをご参照ください。プロシージャは、force パラメーターが true に設定されていない限り、初期の状態ではないことを検出すると、コネクタの既存の状態を上書きしません。初期の状態とは、構成プロセスの終了直後で、レポートが構成されていない状態です。レポートが構成され、後で削除された場合も、状態は初期ではないと見なされます。

注釈

CASCADE オプションでコネクタがアンインストール（ドロップ）された場合、このプロシージャは機能しません。

CALL IMPORT_STATE([force]);
Copy

条件:

force

オプション。デフォルト値は false です。true の場合、プロシージャはコネクタの既存の状態を上書きします。既に構成されているレポートを含みます。false の場合、状態が初期ではないことを検出すると、プロシージャはエラーを返します。

例：

CALL IMPORT_STATE();
Copy
言語: 日本語