CREATE STORAGE INTEGRATION¶

在账户中创建新的存储集成或替换现有集成。

存储集成是一个 Snowflake 对象，用于存储为外部云存储生成的 Identity and Access Management (IAM) 实体，以及一组可选的允许或阻止的存储位置（Amazon S3、Google Cloud Storage 或 Microsoft Azure）。组织中的云提供商管理员会将存储位置的权限授予生成的实体。此选项可让用户在创建暂存区或加载、卸载数据时无需提供凭据。

单个存储集成可以支持多个外部暂存区。暂存区定义中的 URL 必须与为 STORAGE_ALLOWED_LOCATIONS 参数指定的存储位置一致。

备注

存储集成可配置为支持 Amazon S3、Google Cloud Storage 或 Microsoft Azure 云存储，而不受托管 Snowflake 账户的云提供商限制。如果您的云存储与 Snowflake 账户位于不同的云平台上，则存储位置必须位于公有云中，而不能位于虚拟专用环境中。

云提供商对于传输到其自身网络以外的数据收费。为了收回这些费用，当您将数据从 Snowflake（托管在 Amazon Web Services [AWS]、Google Cloud Platform 或 Microsoft Azure 上）卸载到不同区域或不同云提供商的外部暂存区时，Snowflake 会按字节收取费用。Snowflake 不对数据入口（即将数据加载到 Snowflake）收费。有关详细信息，请参阅定价页面（在 Snowflake 网站上）。
目前只能通过在同一政府区域中托管的 Snowflake 账户，使用存储集成访问政府区域中的云存储。要从政府区域以外的 Snowflake 账户访问政府区域中的云存储，请将 CREDENTIALS 与 CREATE STAGE 结合使用。

另请参阅：: ALTER STORAGE INTEGRATION、DROP INTEGRATION、SHOW INTEGRATIONS

语法¶

CREATE [ OR REPLACE ] STORAGE INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = EXTERNAL_STAGE
  cloudProviderParams
  ENABLED = { TRUE | FALSE }
  STORAGE_ALLOWED_LOCATIONS = ('<cloud>://<bucket>/<path>/' [ , '<cloud>://<bucket>/<path>/' ... ] )
  [ STORAGE_BLOCKED_LOCATIONS = ('<cloud>://<bucket>/<path>/' [ , '<cloud>://<bucket>/<path>/' ... ] ) ]
  [ COMMENT = '<string_literal>' ]

Copy

其中：

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  [ STORAGE_AWS_EXTERNAL_ID = '<external_id>' ]
  [ STORAGE_AWS_OBJECT_ACL = 'bucket-owner-full-control' ]

Copy

cloudProviderParams (for Google Cloud Storage) ::=
  STORAGE_PROVIDER = 'GCS'

Copy

cloudProviderParams (for Microsoft Azure) ::=
  STORAGE_PROVIDER = 'AZURE'
  AZURE_TENANT_ID = '<tenant_id>'

Copy

必填参数¶

name

字符串，指定集成的标识符（即名称）；在账户中必须是唯一的。

此外，标识符必须以字母字符开头，且不能包含空格或特殊字符，除非整个标识符字符串放在双引号内（例如，"My object"）。放在双引号内的标识符也区分大小写。

有关更多详细信息，请参阅标识符要求。

TYPE = EXTERNAL_STAGE

指定集成类型：

EXTERNAL_STAGE：在 Snowflake 与外部云存储位置之间创建接口。

ENABLED = TRUE | FALSE

指定此存储集成是否可在暂存区中使用。

TRUE 允许用户创建引用此集成的新暂存区。通常引用此集成函数的现有暂存区。

FALSE 阻止用户创建引用此集成的新暂存区。引用此集成的现有暂存区无法访问暂存区定义中的存储位置。

STORAGE_ALLOWED_LOCATIONS = ('cloud_specific_url')

显式限制使用集成引用一个或多个存储位置（即 S3 桶、GCS 桶或 Azure 容器）的外部暂存区。支持以逗号分隔的现有桶 URLs，以及用于存储数据文件以进行加载/卸载的路径（可选）。此外还支持 * 通配符，即“允许访问所有桶和/或路径”。

Amazon S3

STORAGE_ALLOWED_LOCATIONS = ( 's3://bucket/path/' [ , 's3://bucket/path/' ... ] ) | STORAGE_ALLOWED_LOCATIONS = ( 's3gov://bucket/path/' [ , 's3gov://bucket/path/' ... ] )

s3 前缀代表公共 AWS 区域中的 S3 存储。

s3gov 前缀代表政府区域中的 S3 存储。

bucket 代表存储数据文件的 S3 桶的名称（例如 mybucket）。

path 是云存储位置中文件的可选路径（即文件的名称以公共字符串开头），且区分大小写，用于限制对一组文件的访问。不同的云存储服务也可以将路径称为前缀或 文件夹。

Google Cloud Storage

STORAGE_ALLOWED_LOCATIONS = ( 'gcs://bucket/path/' [ , 'gcs://bucket/path/' ... ] )

bucket 是存储数据文件的 GCS 桶的名称（例如 mybucket）。

path 是云存储位置中文件的可选路径（即文件的名称以公共字符串开头），且区分大小写，用于限制对一组文件的访问。不同的云存储服务也可以将路径称为前缀或 文件夹。

Microsoft Azure

STORAGE_ALLOWED_LOCATIONS = ( 'azure://account.blob.core.windows.net/container/path/' [ , 'azure://account.blob.core.windows.net/container/path/' ... ] )

account 是 Azure 存储账户的名称（例如 myaccount）。将 blob.core.windows.net 端点用于所有受支持类型的 Azure Blob 存储账户，包括 Data Lake Storage Gen2。

container 是存储数据文件的 Azure Blob 存储容器的名称（例如 mycontainer）。

path 是云存储位置中文件的可选路径（即文件的名称以公共字符串开头），且区分大小写，用于限制对一组文件的访问。不同的云存储服务也可以将路径称为前缀或 文件夹。

可选参数¶

STORAGE_BLOCKED_LOCATIONS = ('cloud_specific_url')

显式禁止使用集成的外部暂存区引用一个或多个存储位置（即 S3 桶或 GCS 桶）。支持以逗号分隔的 URLs 现有存储位置列表，以及用于存储数据文件以进行加载/卸载的路径（可选）。通常用于 STORAGE_ALLOWED_LOCATIONS 设置为 * 通配符的时候，允许访问您账户中除阻止的存储位置和路径（可选）之外的所有桶。

备注

确保仅在引号之间包含单个云存储位置 URLs。如果在引号之间包含整个 STORAGE_BLOCKED_LOCATIONS 值，则该值无效。因此，在用户创建引用存储集成的暂存区时，STORAGE_BLOCKED_LOCATIONS 参数设置会被忽略。

Amazon S3

STORAGE_BLOCKED_LOCATIONS = ( 's3://bucket/path/' [ , 's3://bucket/path/' ... ] ) | STORAGE_ALLOWED_LOCATIONS = ( 's3gov://bucket/path/' [ , 's3gov://bucket/path/' ... ] )

s3 前缀代表公共 AWS 区域中的 S3 存储。

s3gov 前缀代表政府区域中的 S3 存储。

bucket 代表存储数据文件的 S3 桶的名称（例如 mybucket）。

path 是桶中的可选路径（或目录），用于进一步限制对数据文件的访问。

Google Cloud Storage

STORAGE_BLOCKED_LOCATIONS = ( 'gcs://bucket/path/' [ , 'gcs://bucket/path/' ... ] )

bucket 是存储数据文件的 GCS 桶的名称（例如 mybucket）。

path 是桶中的可选路径（或目录），用于进一步限制对数据文件的访问。

Microsoft Azure

STORAGE_BLOCKED_LOCATIONS = ( 'azure://account.blob.core.windows.net/container/path/' [ , 'azure://account.blob.core.windows.net/container/path/' ... ] )

account 是 Azure 存储账户的名称（例如 myaccount）。

container 是存储数据文件的 Azure Blob 存储容器的名称（例如 mycontainer）。

path 是桶中的可选路径（或目录），用于进一步限制对数据文件的访问。

COMMENT = 'string_literal'

字符串（字面量），用于指定集成注释。

默认：无值

云提供商参数 (`cloudProviderParams`)¶

Amazon S3

STORAGE_PROVIDER = { S3 | S3GOV }
指定存储数据文件的云存储提供商：

S3： 公共 AWS 区域中的 S3 存储。

S3GOV： 政府区域中的 AWS S3 存储。

STORAGE_AWS_ROLE_ARN = 'iam_role'
指定 AWS Identity and Access Management (IAM) 角色的 Amazon Resource Name (ARN)，该角色授予对包含数据文件的 S3 桶的权限。有关更多信息，请参阅配置对 Amazon S3 的安全访问。

STORAGE_AWS_EXTERNAL_ID = 'external_id'
（可选）指定 Snowflake 与 AWS 建立信任关系所使用的外部 ID。您必须在为此存储集成配置的 IAM 角色的信任策略中指定相同的外部 ID。有关更多信息，请参阅向第三方授予 AWS 资源访问权限时如何使用外部 ID (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)。

如果未为此参数指定值，当您创建存储集成时 Snowflake 将自动生成外部 ID。

STORAGE_AWS_OBJECT_ACL = 'bucket-owner-full-control'
启用对 AWS 访问控制列表 (ACLs) 的支持，以授予桶拥有者完全控制权。通过卸载的表数据在 Amazon S3 桶中创建的文件由 AWS Identity and Access Management (IAM) 角色所拥有。ACLs 支持以下用例：配置一个 AWS 账户中的 IAM 角色，以访问一个或多个其他 AWS 账户中的 S3 桶。若没有 ACL 支持，桶所有者账户中的用户无法访问使用存储集成卸载到外部 (S3) 暂存区的数据文件。

当用户使用 COPY INTO <location> 将 Snowflake 表数据卸载到 S3 暂存区中的数据文件时，卸载操作会将 ACL 应用到卸载的数据文件。数据文件将 "s3:x-amz-acl":"bucket-owner-full-control" 权限应用于文件，授予 S3 桶所有者对它们的完全控制权。

Google Cloud Storage

STORAGE_PROVIDER = 'GCS'
指定存储数据文件的云存储提供商。

Microsoft Azure

STORAGE_PROVIDER = 'AZURE'
指定存储数据文件的云存储提供商。

AZURE_TENANT_ID = 'tenant_id'
为允许和阻止的存储账户所属的 Office 365 租户指定 ID。存储集成只能对一个租户进行身份验证，因此允许和阻止的存储位置必须引用同属于此租户的存储账户。

要查找租户 ID，请登录 Azure 门户并点击 Azure Active Directory » Properties。租户 ID 将显示在 Tenant ID 字段中。

访问控制要求¶

用于执行此 SQL 命令的角色必须至少具有以下权限：

权限	对象	备注
CREATE INTEGRATION	账户	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

有关创建具有指定权限集的自定义角色的说明，请参阅创建自定义角色。

有关对安全对象执行 SQL 操作的相应角色和权限授予的一般信息，请参阅访问控制概述。

使用说明¶

小心

重新创建存储集成（使用 CREATE OR REPLACE STORAGE INTEGRATION）会导致存储集成与引用它的任何暂存区之间的关联断开。原因在于，暂存区使用隐藏的 ID（而非存储集成的名称）链接到存储集成。在后台， CREATE OR REPLACE 语法会删除对象，并使用其他隐藏 ID 重新创建对象。

如果将存储集成链接到一个或多个暂存区后，必须重新创建该存储集成，则必须通过执行 ALTER STAGE stage_name SET STORAGE_INTEGRATION = storage_integration_name 来重新建立每个暂存区与存储集成之间的关联，其中：

stage_name 是暂存区的名称。
storage_integration_name 是存储集成的名称。

关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。
CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

示例¶

以下示例创建一个集成，该集成显式限制使用该集成引用两个桶和路径之一的外部暂存区：

Amazon S3

CREATE STORAGE INTEGRATION s3_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::001234567890:role/myrole'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('s3://mybucket1/path1/', 's3://mybucket2/path2/');

Copy

Google Cloud Storage

CREATE STORAGE INTEGRATION gcs_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('gcs://mybucket1/path1/', 'gcs://mybucket2/path2/');

Copy

Microsoft Azure

CREATE STORAGE INTEGRATION azure_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'AZURE'
  ENABLED = TRUE
  AZURE_TENANT_ID = '<tenant_id>'
  STORAGE_ALLOWED_LOCATIONS = ('azure://myaccount.blob.core.windows.net/mycontainer/path1/', 'azure://myaccount.blob.core.windows.net/mycontainer/path2/');

Copy

以下示例创建一个集成，允许外部暂存区使用该集成引用您的账户中的任意桶和路径，但显式阻止的和路径除外：

Amazon S3

CREATE STORAGE INTEGRATION s3_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::001234567890:role/myrole'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('s3://mybucket3/path3/', 's3://mybucket4/path4/');

Copy

Google Cloud Storage

CREATE STORAGE INTEGRATION gcs_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('gcs://mybucket3/path3/', 'gcs://mybucket4/path4/');

Copy

Microsoft Azure

CREATE STORAGE INTEGRATION azure_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'AZURE'
  ENABLED = TRUE
  AZURE_TENANT_ID = 'a123b4c5-1234-123a-a12b-1a23b45678c9'
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('azure://myaccount.blob.core.windows.net/mycontainer/path3/', 'azure://myaccount.blob.core.windows.net/mycontainer/path4/');

Copy

CREATE STORAGE INTEGRATION¶

语法¶

必填参数¶

可选参数¶

云提供商参数 (cloudProviderParams)¶

访问控制要求¶

使用说明¶

示例¶

云提供商参数 (`cloudProviderParams`)¶