使用 Snowpipe REST API 做好加载数据的准备¶

本主题介绍在调用 REST API 时如何开始使用 Snowpipe，包括安装所需客户端 SDK、创建暂存区（如果需要）和管道以及为每个 Snowpipe 用户进行一次性安全设置的说明。

本主题内容：

备注

本部分中的说明假定您已在 Snowflake 数据库中拥有一个目标表，并将在其中加载数据。

客户端要求（Java 或 Python SDK）¶

Snowpipe 服务需要 Java SDK 或 Python SDK 中的一个。为了方便您使用，这些 SDKs 由 Snowflake 提供。

重要

根据您与 Snowflake 签订的主服务协议 (MSA) 条款，二进制文件作为客户端软件提供。

安装 Java SDK¶

从 Maven Central Repository 下载 Java SDK 安装程序：

Sonatype (https://central.sonatype.com/search?q=g%3Anet.snowflake%20snowflake-ingest-sdk) （或 https://repo1.maven.org/maven2/net/snowflake/snowflake-ingest-sdk (https://repo1.maven.org/maven2/net/snowflake/snowflake-ingest-sdk)）
将 JAR 文件集成到现有项目中。

备注

开发者说明与源代码一起托管在 GitHub (https://github.com/snowflakedb/snowflake-ingest-java) 上。

安装 Python SDK¶

请注意，Python SDK 需要 Python 3.6 或更高版本。

要安装 SDK，请执行以下命令：

pip install snowflake-ingest

Copy

或者，从 PyPI (https://pypi.org/project/snowflake-ingest/) 中下载 wheel 文件并将其集成到现有项目中。

备注

开发者说明与源代码一起托管在 GitHub (https://github.com/snowflakedb/snowflake-ingest-python) 上。

第 1 步：创建暂存区（如果需要）¶

Snowpipe 支持从以下暂存区类型进行加载：

命名的内部 (Snowflake) 或外部（Amazon S3、Google Cloud Storage 或 Microsoft Azure）暂存区
表暂存区

使用 CREATE STAGE 命令创建命名暂存区，也可以选择使用现有暂存区。在 Snowpipe 将文件加载到目标表之前，您将暂存文件。

第 2 步：创建管道¶

在系统中创建一个新管道，用于定义 COPY INTO <table> 语句，Snowpipe 可使用该语句将数据从引入队列加载到表中。有关信息，请参阅 CREATE PIPE。

备注

创建管道需要 CREATE PIPE 访问控制权限，以及数据库、架构和暂存区的 USAGE 权限。

例如，在 mydb.myschema 架构中创建管道，以便将暂存在 mystage 暂存区的文件中的所有数据加载到 mytable 表中：

create pipe mydb.myschema.mypipe if not exists as copy into mydb.myschema.mytable from @mydb.myschema.mystage;

Copy

第 3 步：配置安全性（每个用户）¶

对于将使用 Snowpipe 执行连续数据加载的每个用户，需要生成一个公钥-私钥对，用于调用 Snowpipe REST 端点。此外，需要为数据加载对象（即目标数据库、架构和表）、暂存区对象和管道授予足够的权限。

如果计划将 Snowpipe 数据加载限制为单个用户，则只需为该用户配置一次密钥对身份验证。在此之后，您只需要为用于每次数据加载的数据库对象授予访问控制权限即可。

备注

为了遵循最小权限的一般原则，我们建议使用管道创建单独的用户和角色以用于引入文件。创建用户时，应将此角色作为其默认角色。

使用密钥对身份验证和密钥轮换¶

Snowpipe REST 端点需要具有 JSON Web 令牌 (JWT) 的密钥对身份验证。JWTs 使用通过 RSA 加密的公钥/私钥对签名。

在此过程中，您必须执行以下操作：

生成公钥-私钥对。生成的私钥应位于文件中（例如，名为 rsa_key.p8）。
将公钥分配给 Snowflake 用户。将密钥分配给用户后，运行 DESCRIBE USER 命令。在输出中， RSA_PUBLIC_KEY_FP 属性应设置为分配给用户的公钥的指纹。

有关如何生成密钥对并将密钥分配给用户的说明，请参阅密钥对身份验证和密钥对轮换。

有关创建指纹和生成 JWT 令牌的语言特定示例，请参阅以下部分：

Python

Java

Node.js

授予访问权限¶

具有以下最低权限的角色才能调用 Snowpipe REST 端点：

对象	权限	备注
命名管道	OPERATE （`insertFiles` 端点）、 MONITOR （`insertReport` 和 `loadHistoryScan` 端点）
命名暂存区	USAGE （外部暂存区）、 READ （内部暂存区）
命名文件格式	USAGE	可选；只有暂存区（请参阅第 1 步：创建阶段（如果需要））或管道（请参阅第 2 步：创建管道）引用命名文件格式时才需要。
目标数据库	USAGE
目标架构	USAGE
目标表	INSERT、SELECT

使用 GRANT <privileges> 命令向角色授予这些权限。

备注

只有安全管理员（即具有 SECURITYADMIN 角色的用户）或更高级别的用户，或者同时具有账户中 CREATE ROLE 的权限和全局 MANAGE GRANTS 权限的其他角色，才能创建角色和授予权限。

例如，创建一个名为 snowpipe1 的角色，那么该角色可以通过名为 mypipe 的管道加载数据。管道引用了外部暂存区：

 -- Create a role for the Snowpipe privileges.
use role securityadmin;

create or replace role snowpipe1;

-- Grant the USAGE privilege on the database and schema that contain the pipe object.
grant usage on database mydb to role snowpipe1;
grant usage on schema mydb.myschema to role snowpipe1;

-- Grant the INSERT and SELECT privileges on the target table.
grant insert, select on mydb.myschema.mytable to role snowpipe1;

-- Grant the USAGE privilege on the external stage.
grant usage on stage mydb.myschema.mystage to role snowpipe1;

-- Grant the OPERATE and MONITOR privileges on the pipe object.
grant operate, monitor on pipe mydb.myschema.mypipe to role snowpipe1;

-- Grant the role to a user
grant role snowpipe1 to user jsmith;

-- Set the role as the default role for the user
alter user jsmith set default_role = snowpipe1;

Copy

第 4 步：暂存数据文件¶

将数据文件复制到您为使用 Snowpipe 加载文件而创建的内部或外部暂存区。

使用云存储服务提供的工具将文件复制到外部暂存区。
使用 PUT 命令将文件复制到内部暂存区。

备注

如果您的 Snowflake 账户在 Amazon Web Services 上托管，我们建议您始终使用 PUT ... OVERWRITE = TRUE 语法。

Amazon S3 为在桶中创建的新对象提供写后读相关的一致性。但是，如果在创建对象之前就对其发出了 HEAD 或 GET 请求，那么 S3 将会为对象提供 最终一致性。这意味着，在创建新对象后立即请求新对象，可能会出现返回 file not found 异常的情况。通过设置 OVERWRITE = TRUE 参数，可以避免在 S3 桶中创建对象之前发起 HEAD 请求。

有关 S3 一致性模型的更多信息，请参阅 S3 文档 (https://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html#ConsistencyModel)。

后续主题： 请参阅用于加载数据的 Snowpipe REST 端点概述，了解如何调用公共 REST 端点来加载数据并检索加载历史记录报告。