请求符合应用程序规范的数据共享

本主题介绍如何配置 Snowflake Native App 的规范以请求通过列表与提供商或第三方共享数据的权限。这使得合规性报告、遥测共享和数据预处理等用例成为可能。

与提供商或第三方共享应用程序中的数据

一些 Snowflake Native Apps 出于各种商业目的，需要与提供商或第三方 Snowflake 账户共享数据。常见用例包括以下内容：

  • 合规性报告： 与监管账户共享审计日志或合规性数据

  • 遥测和分析： 将使用情况指标发送回提供商以改进产品

  • 数据预处理： 与合作伙伴账户共享转换后的数据

  • 支持和故障排除： 向支持团队提供诊断数据

要从应用程序启用数据共享，应用程序需要同时提供共享和列表。共享包含要共享的数据库对象，列表提供了跨账户和区域共享数据的机制。

有关数据共享的更多信息，请参阅 关于 Secure Data Sharing。

要将应用程序配置为使用列表共享数据，请按照以下步骤操作：

  1. 使用 自动授予权限 向使用者请求创建共享和列表的权限。

  2. 创建共享并向其授予数据库对象。

  3. 创建附加到共享的外部列表。

  4. 要向使用者请求与特定目标账户共享数据的权限，请使用 应用程序规范。

备注

与其他应用程序规范类型不同，每个 LISTING 规范仅与一个列表对象相关联。一个应用程序不能为同一列表创建多个应用程序规范。

用于共享数据的应用程序规范工作流程

配置应用程序以使用列表共享数据，遵循以下一般工作流程：

  1. Providers configure automated granting of privileges for the app. This grants the app privileges to create shares and listings.

    备注

    App specifications require manifest_version: 2 to be set in the manifest file.

  2. 提供商将 CREATE SHARE 和 CREATE LISTING 权限 添加到清单文件中。

  3. 提供商在安装脚本中添加 SQL 语句，根据需要创建以下对象：

    安装或升级应用程序时，安装脚本会创建共享和列表。应用程序规范可以在安装过程中创建，也可以在运行时通过存储过程创建。

  4. 配置应用程序时，使用者审查并批准列表上的目标账户和自动履行设置。自动履行设置仅适用于跨区域共享。有关使用者如何查看和批准应用程序规范的更多信息，请参阅 使用应用程序规范批准与外部资源的连接。

共享数据的应用程序规范定义

对于类型为 LISTING 的应用程序规范，应用程序规范定义包含以下条目：

  • TARGET_ACCOUNTS：选择使用 时默认使用的角色和仓库。要与之共享数据的目标账户的逗号分隔列表（放在单引号内）。必须按格式 OrgName.AccountName 指定每个账户；例如：'ProviderOrg.ProviderAccount,PartnerOrg.PartnerAccount'。

  • LISTING：选择使用 时默认使用的角色和仓库。应用程序创建的列表对象的标识符。

  • AUTO_FULFILLMENT_REFRESH_SCHEDULE：选择使用 时默认使用的角色和仓库。可选。跨区域数据共享的刷新计划。可指定为 <num> MINUTE 或 USING CRON <expression>。

备注

应用程序规范中的列表名称必须与应用程序创建的现有列表匹配。设置后，列表名称将无法更改。

设置清单文件的版本

要启用应用程序权限的自动授予，请在清单文件的开头设置版本，如以下示例所示：

manifest_version: 2
Copy

将 CREATE SHARE 和 CREATE LISTING 权限添加到清单文件中

CREATE SHARE 和 CREATE LISTING 权限允许应用程序在安装或升级期间创建共享和列表。

  • 要配置应用程序以请求这些权限，请将以下代码添加到清单文件的 privileges 部分：

    manifest_version: 2
...
privileges:
  - CREATE SHARE:
      description: "Create a share for sharing compliance data with provider"
  - CREATE LISTING:
      description: "Create a listing for cross-region sharing of compliance data"
...
    Copy

If you set the manifest_version to 2 in the manifest file, Snowflake automatically grants the CREATE SHARE and CREATE LISTING privileges to the app during installation or upgrade.

创建共享并向其授予对象

  1. 要创建用于数据共享的共享，请将 CREATE SHARE 命令添加到安装脚本中，如以下示例所示：

CREATE SHARE compliance_share;
Copy

  1. 授予要共享的数据库对象，如以下示例所示：

-- Grant usage on a table in the app's database:
GRANT USAGE ON TABLE app_schema.compliance_data TO SHARE compliance_share;

-- If sharing from a database created by the app, do the following:
GRANT USAGE ON DATABASE app_created_db TO SHARE compliance_share;
GRANT USAGE ON SCHEMA app_created_db.reporting TO SHARE compliance_share;
GRANT SELECT ON TABLE app_created_db.reporting.metrics TO SHARE compliance_share;
Copy

备注

应用程序只能共享以下来源的数据：

  • 应用程序创建的数据库：应用程序必须是这些数据库的所有者。

应用程序无法直接将目标账户添加到共享中。这是通过应用程序规范控制的。

创建外部列表

  1. 要创建附加到共享的外部列表，请将 CREATE LISTING 命令添加到安装脚本中，如以下示例所示：

    CREATE EXTERNAL LISTING compliance_listing
SHARE compliance_share
  AS
  $$
    title: "Compliance Data Share"
    subtitle: "Regulatory compliance reporting data"
    description: "Share compliance and audit data with authorized accounts"
      listing_terms:
      type: "OFFLINE"
  $$
  PUBLISH = FALSE
  REVIEW = FALSE;
    Copy

备注

  • 应用程序只能将共享（而非应用程序包）附加到列表。

  • 应用程序无法直接将目标账户或自动履行配置添加到列表中。

  • 列表清单只能包含以下属性：标题、子标题、描述和列表术语。

  • 所有新列表都必须在未发布状态下创建，并且 PUBLISH 和 REVIEW 设置为 FALSE。

  • 列表标题和描述可以根据使用者信息进行自定义，从而使提供商能够区分数据源。

为列表创建应用程序规范

  1. 要为列表创建应用程序规范，请按照以下示例操作：

ALTER APPLICATION SET SPECIFICATION shareback_spec
  TYPE = LISTING
  LABEL = 'Compliance Data Sharing'
  DESCRIPTION = 'Share compliance data with provider for regulatory reporting'
  TARGET_ACCOUNTS = 'ProviderOrg.ProviderAccount,AuditorOrg.AuditorAccount'
  LISTING = compliance_listing
  AUTO_FULFILLMENT_REFRESH_SCHEDULE = '720 MINUTE';
Copy

此命令创建了一个名为 shareback_spec 的应用程序规范，用于请求与指定目标账户共享数据的权限。

  1. 对于跨区域共享，AUTO_FULFILLMENT_REFRESH_SCHEDULE 参数为必填项。您可以将其设置为以下值之一：

    • '<num> MINUTE'：分钟数，至少 10 分钟，

    • 最长 8 天或 11520 分钟（八天）

    • 'USING CRON <expression> <time_zone>'：带时区的 Cron 表达式

备注

  • 应用程序应仅在列表和共享对象存在后创建应用程序规范。

  • 每个列表只能有一个关联的应用程序规范。

  • 更新目标账户会创建一个新的待处理请求，以供使用者批准。

验证列表配置

应用程序可以通过运行以下命令来验证列表在批准后是否已正确配置：

-- Check if the app specification is approved:
SHOW APPROVED SPECIFICATIONS IN APPLICATION;

-- Validate the listing configuration:
DESC LISTING compliance_listing;
Copy

使用者审批工作流程

使用者批准 LISTING 应用程序规范会触发以下工作流程：

  • Snowflake 会自动将目标账户添加到列表中。

  • 如果已指定，Snowflake 会配置自动履行刷新计划。

  • 该列表对目标账户可见。

  • 可以从批准的账户中查询列表所附的数据。

使用者拒绝 LISTING 应用程序规范会触发以下工作流程：

  • 列表将取消发布，任何现有目标账户都将从列表中移除。

  • 自动履行已禁用。

  • 该列表不再对任何目标账户可见。

LISTING 应用程序规范的最佳实践

通过应用程序规范实施数据共享时，请考虑以下最佳实践：

  • 共享完整性： Snowflake 不会阻止使用者修改由应用程序创建的共享。因此，提供商有责任采取措施保护底层共享数据的完整性。

  • 错误处理： 对于应用程序规范被拒绝或尚未批准的情况，实施适当的错误处理。

  • 跨区域注意事项： 应用程序提供商负责设置刷新计划，以平衡数据新鲜度要求和成本注意事项。尽管列表自动履行成本由应用程序使用者承担，但提供商在选择计划时应注意成本，以尽量减少应用程序使用者不必要的成本。

  • 合规性： 在应用程序规范描述中明确记录您共享的数据以及共享数据的原因。

在 LISTING 应用程序规范中使用回调函数

通过在清单文件中添加以下代码，应用程序可以使用生命周期回调，在使用者批准或拒绝列表规范时做出响应：

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update
Copy

在安装脚本中，添加以下回调存储过程：

CREATE OR REPLACE PROCEDURE callbacks.on_spec_update (
  name STRING,
  status STRING,
  payload STRING)
RETURNS STRING
LANGUAGE SQL
AS
$$
BEGIN
  IF (name = 'shareback_spec' AND status = 'APPROVED') THEN
    -- Start populating shared tables
    CALL populate_compliance_data();
  ELSEIF (name = 'shareback_spec' AND status = 'DECLINED') THEN
    -- Clean up or notify provider
    CALL cleanup_share_data();
  END IF;
  RETURN 'Processed specification update';
END;
$$;
Copy

该过程允许应用程序对使用者关于应用程序数据共享请求的决定做出适当的反应。

限制

本章节介绍使用应用程序规范时的限制。

审计

对于应用程序共享给提供商的数据，Snowflake 不提供内置审计功能。如果使用者有包括审计跟踪在内的合规性或监管要求，他们必须直接与提供商协调以实施自己的单独监控解决方案。

从应用程序内部共享

Snowflake 不建议直接从应用程序内部与提供商共享数据，因为以这种方式共享的数据目前不支持列表自动履行。

语言: 中文