Atualização automática de tabelas de diretório para o armazenamento de blobs do Azure¶

Criação de um grupo de recursos¶

Um tópico da Event Grid fornece um ponto de extremidade para onde a origem (ou seja, o armazenamento Azure) envia eventos. Um tópico é usado para uma coleção de eventos relacionados. Os tópicos da Event Grid são recursos do Azure e devem ser colocados em um grupo de recursos do Azure.

Execute o seguinte comando para criar um grupo de recursos:

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

Onde:

• resource_group_name é o nome do novo grupo de recursos.

• location é a localização, ou região na terminologia Snowflake, de sua conta do armazenamento Azure.

Habilitação do provedor de recursos da Event Grid¶

Execute o seguinte comando para registrar o provedor de recursos da Event Grid. Note que esta etapa só é necessária se você não tiver usado anteriormente a Event Grid com sua conta Azure:

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

Criação de uma conta de armazenamento para arquivos de dados¶

Execute o seguinte comando para criar uma conta de armazenamento para seus arquivos de dados. Esta conta deve ser de armazenamento de blobs (ou seja, do tipo BlobStorage) ou GPv2 (ou seja, do tipo StorageV2), porque somente estes dois tipos de conta suportam mensagens de eventos.

Por exemplo, crie uma conta de armazenamento de blobs:

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

Onde:

• resource_group_name é o nome do grupo de recursos que você criou em Criação de um grupo de recursos.

• storage_account_name é o nome da nova conta de armazenamento.

• location é a localização de sua conta de armazenamento Azure.

Criação de uma conta de armazenamento para a fila de armazenamento¶

Execute o seguinte comando para criar uma conta de armazenamento para hospedar sua fila de armazenamento. Esta conta deve ser uma conta GPv2, porque somente este tipo de conta suporta mensagens de eventos para uma fila de armazenamento.

Por exemplo, crie uma conta GPv2:

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

Onde:

• resource_group_name é o nome do grupo de recursos que você criou em Criação de um grupo de recursos.

• storage_account_name é o nome da nova conta de armazenamento.

• location é a localização de sua conta de armazenamento Azure.

Criação de uma fila de armazenamento¶

Uma única fila de armazenamento Azure pode coletar as mensagens de eventos para muitas assinaturas da Event Grid. Para um melhor desempenho, o Snowflake recomenda a criação de uma única fila de armazenamento para acomodar todas as suas assinaturas relacionadas ao Snowflake.

Execute o seguinte comando para criar uma fila de armazenamento. Uma fila de armazenamento armazena um conjunto de mensagens, neste caso, mensagens de eventos da Event Grid:

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

Onde:

• storage_queue_name é o nome da nova fila de armazenamento.

• storage_account_name é o nome da conta de armazenamento que você criou em Criação de uma conta de armazenamento para a fila de armazenamento.

Exportação das IDs de conta e fila de armazenamento para referência¶

Execute os seguintes comandos para definir variáveis de ambiente para as IDs de conta e fila de armazenamento que serão solicitadas posteriormente nestas instruções:

• Linux ou 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

Onde:

• data_storage_account_name é o nome da conta de armazenamento que você criou em Criação de uma conta de armazenamento para arquivos de dados.

• queue_storage_account_name é o nome da conta de armazenamento que você criou em Criação de uma conta de armazenamento para a fila de armazenamento.

• resource_group_name é o nome do grupo de recursos que você criou em Criação de um grupo de recursos.

• storage_queue_name é o nome da fila de armazenamento que você criou em Criação de uma fila de armazenamento.

Instalação da extensão da Event Grid¶

Execute o seguinte comando para instalar a extensão da Event Grid para a CLI do Azure:

az extension add --name eventgrid

Criação da assinatura da Event Grid¶

Execute o seguinte comando para criar a assinatura da Event Grid. A assinatura de um tópico informa a Event Grid que eventos rastrear:

• Linux ou 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

Onde:

• storageid e queueid são as variáveis de ambiente da ID de conta e fila de armazenamento que você define em Exportação das IDs de conta e fila de armazenamento para referência.

• subscription_name é o nome da nova assinatura da Event Grid.

Recuperação da URL da fila de armazenamento e da ID do locatário¶

1. Faça login no portal do Microsoft Azure.

2. Navegue até Storage account » Queue service » Queues. Registre a URL para a fila que você criou em Criação de uma fila de armazenamento para referência posterior. A URL tem o seguinte formato:

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

   Copy

3. Navegue até Azure Active Directory » Properties. Registre o valor Tenant ID para referência posterior. A ID do diretório, ou ID do locatário, é necessária para gerar a URL de consentimento que concede ao Snowflake acesso à assinatura da Event Grid.

Criação da integração de notificação¶

Crie uma integração de notificação usando o comando 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>';

Onde:

• integration_name é o nome da nova integração.

• queue_URL e directory_ID são a URL da fila e a ID de locatário que você registrou em Recuperação da URL da fila de armazenamento e da ID do locatário.

Por exemplo:

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';

Concessão de acesso à fila de armazenamento ao Snowflake¶

Observe que etapas específicas nesta seção requerem uma instalação local da CLI do Azure.

1. Execute o comando DESCRIBE INTEGRATION para recuperar o URL de consentimento:

   DESC NOTIFICATION INTEGRATION <integration_name>;
   

   Copy

   Onde:

   • integration_name é o nome da integração que você criou em Criação da integração de notificação.

   Observe os valores nas colunas seguintes:

   AZURE_CONSENT_URL:

   URL para a página de solicitação de permissões da Microsoft.

   AZURE_MULTI_TENANT_APP_NAME:

   Nome do aplicativo cliente do Snowflake criado para sua conta. Em uma etapa posterior desta seção, você precisará conceder a este aplicativo as permissões necessárias para obter um token de acesso para seu tópico permitido.

2. Em um navegador da Web, navegue até o URL na coluna AZURE_CONSENT_URL. A página exibe uma página de solicitação de permissões da Microsoft.

3. Clique no botão Accept. Esta ação permite que a entidade de segurança do serviço Azure criada para sua conta Snowflake obtenha um token de acesso a qualquer recurso dentro de seu locatário. A obtenção de um token de acesso só tem sucesso se você conceder à entidade de segurança de serviço as permissões apropriadas sobre o contêiner (consulte a próxima etapa).

   A página de solicitações de permissão da Microsoft é redirecionada para o site corporativo da Snowflake (snowflake.com).

4. Faça login no portal do Microsoft Azure.

5. Navegue até Azure Active Directory » Enterprise applications. Verifique se o identificador do aplicativo Snowflake que você registrou na Etapa 2 nesta seção está listado.

   Importante

   Se você excluir o aplicativo Snowflake no Azure Active Directory posteriormente, a integração da notificação deixa de funcionar.

6. Navegue até Queues » storage_queue_name, onde storage_queue_name é o nome da fila de armazenamento que você criou em Criação de uma fila de armazenamento.

7. Clique em Access Control (IAM) » Add role assignment.

8. Pesquise a entidade de segurança do serviço Snowflake. Esta é a identidade na propriedade AZURE_MULTI_TENANT_APP_NAME na saída DESC NOTIFICATION INTEGRATION (na Etapa 1). Pesquise a cadeia de cadeia de caracteres antes do sublinhado na propriedade AZURE_MULTI_TENANT_APP_NAME.

   Importante

   • Pode levar uma hora ou mais para que o Azure crie a entidade de segurança do serviço Snowflake solicitada por meio da página de solicitação da Microsoft nesta seção. Se a entidade de segurança de serviço não estiver disponível imediatamente, recomendamos esperar uma ou duas horas e depois procurar novamente.

   • Se você excluir a entidade de segurança do serviço, a integração da notificação deixa de funcionar.

9. Conceda ao aplicativo Snowflake as seguintes permissões:

   • Role: Colaborador de dados da fila de armazenamento

   • Assign access to: Usuário, grupo ou entidade de segurança do Azure AD

   • Select: O valor appDisplayName.

   O identificador do aplicativo Snowflake deve agora estar listado em Storage Queue Data Contributor (na mesma caixa de diálogo).

Parâmetros da tabela de diretório (directoryTable)¶

ENABLE = TRUE | FALSE

Especifica se deve ser adicionada uma tabela de diretório ao estágio. Quando o valor é TRUE, uma tabela de diretório é criada com o estágio.

Padrão: FALSE

AUTO_REFRESH = TRUE | FALSE

Especifica se o Snowflake deve permitir acionar atualizações automáticas dos metadados da tabela de diretório quando os arquivos de dados novos ou atualizados estiverem disponíveis no estágio externo nomeado especificado na configuração de [ WITH ] LOCATION =.

TRUE

O Snowflake permite acionar a atualização automática dos metadados da tabela de diretório.

FALSE

O Snowflake não permite acionar atualizações automáticas dos metadados da tabela de diretório. Você deve atualizar manualmente os metadados da tabela de diretório periodicamente usando ALTER STAGE … REFRESH para sincronizar os metadados com a lista atual de arquivos no caminho do estágio.

Padrão: FALSE

Microsoft Azure

NOTIFICATION_INTEGRATION = '<nome_integração_notificação>'

Especifica o nome da integração da notificação usada para atualizar automaticamente os metadados da tabela de diretório usando as notificações de Event Grid do Azure. Uma integração de notificação é um objeto Snowflake que fornece uma interface entre o Snowflake e serviços de enfileiramento de mensagens de terceiros.

O exemplo a seguir cria um estágio chamado mystage no esquema ativo para a sessão do usuário. O URL de armazenamento em nuvem inclui o caminho files. O estágio faz referência a uma integração de armazenamento chamada 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'
  );

O parâmetro NOTIFICATION_INTEGRATION faz referência à integração my_notification_int que você criou na Etapa 2: Criar a integração de notificação. O nome da integração deve ser fornecido em letras maiúsculas.

Quando arquivos de dados novos ou atualizados são adicionados ao local de armazenamento na nuvem, a notificação de evento informa ao Snowflake para verificá-los nos metadados da tabela de diretório.

Sintaxe¶

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

Onde:

REFRESH

Acessa os arquivos de dados preparados referenciados na definição da tabela de diretório e atualiza os metadados da tabela:

• Novos arquivos no caminho são adicionados aos metadados da tabela.

• As mudanças nos arquivos do caminho são atualizadas nos metadados da tabela.

• Os arquivos que não estão mais no caminho são removidos dos metadados da tabela.

Atualmente, é necessário executar este comando cada vez que arquivos são adicionados ao estágio, atualizados ou descartados. Esta etapa sincroniza os metadados com o último conjunto de arquivos associados na definição do estágio para a tabela de diretório.

SUBPATH = '<relative-path>'

Opcionalmente, especifique um caminho relativo para atualizar os metadados de um subconjunto específico dos arquivos de dados.

Exemplos¶

Atualizar manualmente os metadados da tabela de diretório em um estágio chamado mystage:

ALTER STAGE mystage REFRESH;