自动刷新 Azure Blob 存储的目录表¶

创建资源组¶

事件网格 主题 提供了一个端点，来源（即 Azure 存储）会将事件发送到该端点。主题用作相关事件的集合。事件网格主题是 Azure 资源，必须放在 Azure 资源组中。

执行以下命令以创建资源组：

az group create --name <resource_group_name> --location <location>

其中：

• resource_group_name 是新资源组的名称。

• location 指的是 Azure 存储账户的位置，即 Snowflake 术语中的 区域。

启用事件网格资源提供商¶

执行以下命令以注册事件网格资源提供商。请注意，仅当您以前未将事件网格与 Azure 账户搭配使用时，才需要执行此步骤：

az provider register --namespace Microsoft.EventGrid
az provider show --namespace Microsoft.EventGrid --query "registrationState"

为数据文件创建存储账户¶

执行以下命令以创建存储账户来存储数据文件。此账户必须是 Blob 存储（即 BlobStorage 类别）或 GPv2（即 StorageV2 类别）账户，因为只有这两种账户类型支持事件消息。

例如，创建 Blob 存储账户：

az storage account create --resource-group <resource_group_name> --name <storage_account_name> --sku Standard_LRS --location <location> --kind BlobStorage --access-tier Hot

其中：

• resource_group_name 是在 创建资源组 中创建的资源组的名称。

• storage_account_name 是新存储账户的名称。

• location 是您的 Azure 存储账户的位置。

为存储队列创建存储账户¶

执行以下命令以创建存储账户来托管存储队列。此账户必须是 GPv2 账户，因为只有此类账户才支持将事件消息发送到存储队列。

例如，创建 GPv2 账户：

az storage account create --resource-group <resource_group_name> --name <storage_account_name> --sku Standard_LRS --location <location> --kind StorageV2

其中：

• resource_group_name 是在 创建资源组 中创建的资源组的名称。

• storage_account_name 是新存储账户的名称。

• location 是您的 Azure 存储账户的位置。

创建存储队列¶

单个 Azure 队列存储队列可以收集许多事件网格订阅的事件消息。为获得最佳性能，Snowflake 建议创建单个存储队列以容纳与 Snowflake 相关的所有订阅。

执行以下命令以创建存储队列。存储队列会存储一组消息，在本例中是来自事件网格的事件消息：

az storage queue create --name <storage_queue_name> --account-name <storage_account_name>

其中：

• storage_queue_name 是新存储队列的名称。

• storage_account_name 是在 为存储队列创建存储账户 中创建的存储账户的名称。

导出存储账户和队列 IDs 以供参考¶

执行以下命令以设置存储账户和队列 IDs 的环境变量，这些指令稍后将请求这些变量：

• Linux 或 macOS：

  export storageid=$(az storage account show --name <data_storage_account_name> --resource-group <resource_group_name> --query id --output tsv)
  export queuestorageid=$(az storage account show --name <queue_storage_account_name> --resource-group <resource_group_name> --query id --output tsv)
  export queueid="$queuestorageid/queueservices/default/queues/<storage_queue_name>"
  

  Copy

• Windows：

  set storageid=$(az storage account show --name <data_storage_account_name> --resource-group <resource_group_name> --query id --output tsv)
  set queuestorageid=$(az storage account show --name <queue_storage_account_name> --resource-group <resource_group_name> --query id --output tsv)
  set queueid="%queuestorageid%/queueservices/default/queues/<storage_queue_name>"
  

  Copy

其中：

• data_storage_account_name 是在 为数据文件创建存储账户 中创建的存储账户的名称。

• queue_storage_account_name 是在 为存储队列创建存储账户 中创建的存储账户的名称。

• resource_group_name 是在 创建资源组 中创建的资源组的名称。

• storage_queue_name 是在 创建存储队列 中创建的存储队列的名称。

安装事件网格扩展程序¶

执行以下命令以安装 Azure CLI 的事件网格扩展程序：

az extension add --name eventgrid

创建事件网格订阅¶

执行以下命令以创建事件网格订阅。订阅主题可告知事件网格要跟踪哪些事件：

• Linux 或 macOS：

  az eventgrid event-subscription create \
  --source-resource-id $storageid \
  --name <subscription_name> --endpoint-type storagequeue \
  --endpoint $queueid \
  --advanced-filter data.api stringin CopyBlob PutBlob PutBlockList FlushWithClose SftpCommit DeleteBlob DeleteFile SftpRemove
  

  Copy

• Windows：

  az eventgrid event-subscription create \
  --source-resource-id %storageid% \
  --name <subscription_name> --endpoint-type storagequeue \
  --endpoint %queueid% \
  -advanced-filter data.api stringin CopyBlob PutBlob PutBlockList FlushWithClose SftpCommit DeleteBlob DeleteFile SftpRemove
  

  Copy

其中：

• storageid 和 queueid 是在 导出存储账户和队列 IDs 以供参考 中设置的存储账户和队列 ID 环境变量。

• subscription_name 是新事件网格订阅的名称。

检索存储队列 URL 和租户 ID¶

1. 登录 Microsoft Azure 门户。

2. 导航到 Storage account » Queue service » Queues。记录在 创建存储队列 中创建的队列的 URL，以供以后参考。URL 具有以下格式：

   https://<storage_account_name>.queue.core.windows.net/<storage_queue_name>
   

   Copy

3. 导航到 Azure Active Directory » Properties。记录 Tenant ID 值以供以后参考。需要目录 ID 或 租户 ID 来生成授予 Snowflake 访问事件网格订阅的许可 URL。

创建通知集成¶

使用 CREATE NOTIFICATION INTEGRATION 命令创建通知集成。

CREATE NOTIFICATION INTEGRATION <integration_name>
  ENABLED = true
  TYPE = QUEUE
  NOTIFICATION_PROVIDER = AZURE_STORAGE_QUEUE
  AZURE_STORAGE_QUEUE_PRIMARY_URI = '<queue_URL>'
  AZURE_TENANT_ID = '<directory_ID>';

其中：

• integration_name 是新集成的名称。

• queue_URL 和 directory_ID 是在 检索存储队列 URL 和租户 ID 中记录的队列 URL 和租户 ID。

例如：

CREATE NOTIFICATION INTEGRATION my_notification_int
  ENABLED = true
  TYPE = QUEUE
  NOTIFICATION_PROVIDER = AZURE_STORAGE_QUEUE
  AZURE_STORAGE_QUEUE_PRIMARY_URI = 'https://myqueue.queue.core.windows.net/mystoragequeue'
  AZURE_TENANT_ID = 'a123bcde-1234-5678-abc1-9abc12345678';

授予 Snowflake 对存储队列的访问权限¶

请注意，本部分中的特定步骤需要在本地安装 Azure CLI。

1. 执行 DESCRIBE INTEGRATION 命令以检索许可 URL：

   DESC NOTIFICATION INTEGRATION <integration_name>;
   

   Copy

   其中：

   • integration_name 是您在 创建通知集成 中创建的集成的名称。

   请注意以下列中的值：

   AZURE_CONSENT_URL:

   Microsoft 权限请求页面的 URL。

   AZURE_MULTI_TENANT_APP_NAME:

   为账户创建的 Snowflake 客户端应用程序的名称。在本部分后面的步骤中，需要授予此应用程序必要的权限，使其获取允许主题的访问令牌。

2. 在 Web 浏览器中，导航到 AZURE_CONSENT_URL 列中的 URL。该页面显示 Microsoft 权限请求页面。

3. 点击 Accept 按钮。此操作允许为 Snowflake 账户创建的 Azure 服务主体获取租户内任何资源的访问令牌。仅当您授予服务主体对容器的适当权限时，才能成功获取访问令牌（请参阅下一步）。

   Microsoft 权限请求页面会重定向到 Snowflake 公司站点 (snowflake.com)。

4. 登录 Microsoft Azure 门户。

5. 导航到 Azure Active Directory » Enterprise applications。验证是否列出了在本部分第 2 步中记录的 Snowflake 应用程序标识符。

   重要

   如果以后在 Azure AD 中删除 Snowflake 应用程序，通知集成将会停止工作。

6. 导航到 Queues » storage_queue_name，其中 storage_queue_name 是在 创建存储队列 中创建的存储队列的名称。

7. 点击 Access Control (IAM) » Add role assignment。

8. 搜索 Snowflake 服务主体。这是 DESC NOTIFICATION INTEGRATION 输出（第 1 步中）中 AZURE_MULTI_TENANT_APP_NAME 属性的身份。在 AZURE_MULTI_TENANT_APP_NAME 属性中搜索下划线 之前 的字符串。

   重要

   • Azure 可能需要一个小时或更长时间才能创建通过此部分中的 Microsoft 请求页面请求的 Snowflake 服务主体。如果服务主体不能立即使用，我们建议等待一两个小时，然后再次搜索。

   • 如果删除服务主体，通知集成将停止工作。

9. 授予 Snowflake 应用程序以下权限：

   • Role: 存储队列数据消息处理者（所需的最低权限角色）或存储队列数据贡献者

   • Assign access to: Azure AD 用户、组或服务主体

   • Select: appDisplayName 值。

   Snowflake 应用程序标识符现在应列于 Storage Queue Data Message Processor 或 Storage Queue Data Contributor 下方（同一对话框上）。

目录表参数 (directoryTable)¶

ENABLE = TRUE | FALSE

指定是否向暂存区添加目录表。当值为 TRUE 时，将创建包含暂存区的目录表。

默认：FALSE

AUTO_REFRESH = TRUE | FALSE

指定当 新的或更新的 数据文件在 URL 值中指定的命名外部暂存区中可用时，Snowflake 是否应支持触发目录表元数据自动刷新。

TRUE

Snowflake 支持触发目录表元数据自动刷新。

FALSE

Snowflake 不支持触发目录表元数据自动刷新。必须使用 ALTER STAGE ... REFRESH 定期手动刷新目录表元数据，以使元数据与暂存区路径中的当前文件列表同步。

默认：FALSE

Microsoft Azure

NOTIFICATION_INTEGRATION = '<notification_integration_name>'

指定用于使用 Azure 事件网格通知自动刷新目录表元数据的通知集成的名称。通知集成是一个 Snowflake 对象，它在 Snowflake 和第三方云消息队列服务之间提供一个接口。

以下示例会在活动架构中为用户会话创建一个名为 mystage 的暂存区。云存储 URL 包括路径 files。该暂存区引用名为 my_storage_int 的存储集成。

USE SCHEMA mydb.public;

Copy

CREATE STAGE mystage
  URL='azure://myaccount.blob.core.windows.net/load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (
    ENABLE = true
    AUTO_REFRESH = true
    NOTIFICATION_INTEGRATION = 'MY_NOTIFICATION_INT'
  );

NOTIFICATION_INTEGRATION 参数引用您在 第 2 步：创建通知集成 中创建的 my_notification_int 集成。集成名称须全部大写。

将新的或更新的数据文件添加到云存储位置时，事件通知会通知 Snowflake 将它们扫描到目录表元数据中。

语法¶

ALTER STAGE [ IF EXISTS ] <name> REFRESH [ SUBPATH = '<relative-path>' ]

其中：

REFRESH

访问目录表定义中引用的暂存数据文件并更新表元数据：

• 路径中的新文件将添加到表元数据中。

• 对路径中文件的更改将在表元数据中更新。

• 路径中不再存在的文件将从表元数据中移除。

目前，每次将文件添加到暂存区、更新或删除文件时，都需要执行此命令。此步骤将元数据与目录表的暂存区定义中的最新关联文件集同步。

SUBPATH = '<relative-path>'

（可选）指定相对路径以刷新数据文件的特定子集的元数据。

示例¶

在名为 mystage 的暂存区中手动刷新目录表元数据：

ALTER STAGE mystage REFRESH;