用于日常维护的存储过程¶

配置新报告¶

CONFIGURE_REPORT 过程配置一份新的报告，用于将数据从 Google Analytics 4 (GA4) 提取到 Snowflake。此过程将报告的参数作为输入获取，包括维度、指标和引入时间表。

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

Copy

其中：

report_name

一个字符串，指定待配置报告的名称。此名称将用作在目标数据库中创建的原始数据的表的前缀。初始引入后，报告名称将用作目标数据库中创建的视图的名称。必填。

报告名称必须符合以下条件：

• 以字母（大写或小写）或下划线开头。

• 后接一个或多个字符，这些字符可以是字母（大写或小写）、数字或下划线。

• 不超过 150 个字符。

property_id

一个字符串，指定用于报告的 Google Analytics 4 属性 ID。属性 ID 的形式为数字，可从 GA4 账户获取。确保 PROPERTY_ID 对应于可通过连接器身份验证方法（oauth2 或服务账户）访问的 GA4 属性。必填。

dimensions

要包含在报告中的 GA4 维度列表，以逗号分隔。维度必须以逗号分隔。如果未明确指定 date 维度，则系统会自动添加。最多可以指定九个维度（包括 date）。必填。

示例：'country,city,deviceCategory,sessions'

metrics

要包含在报告中的 GA4 指标列表，以逗号分隔。至少需要有一个指标，最多可有十个指标。必填。

示例：'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 Analytics 4 账户中的属性¶

GET_PROPERTIES 过程会返回所有可供连接器提取的 Google Analytics 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 Analytics 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 过程旨在通过手动将其状态设置为 STARTED 或 PAUSED 来恢复处于中间状态或错误状态（ERROR、STARTING、PAUSING）的连接器。某些操作可能会导致连接器处于不一致的状态，其原因可能多种多样。例如，在用户将删除连接器所需的某些数据库对象的权限时。

如果新状态无效或连接器未处于预先确定的状态之一，则该过程将返回错误。允许以下转换：

• 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