Habilitação de notificações de erro do Snowpipe para o Microsoft Azure Event Grid

Este tópico fornece instruções para enviar notificações de erro do Snowpipe para o Microsoft Azure Event Grid (Event Grid).

Este recurso pode enviar notificações de erro para os seguintes tipos de cargas:

  • Snowpipe com ingestão automática.

  • Chamadas para o ponto de extremidade insertFiles da API REST Snowpipe.

  • Carregamentos do Apache Kafka usando o conector Snowflake para Kafka somente com o método de ingestão Snowpipe.

Neste tópico:

Suporte para a plataforma de nuvem

Atualmente, esse recurso está limitado às contas Snowflake hospedadas no Microsoft Azure. O Snowpipe pode carregar dados de arquivos em qualquer serviço de armazenamento em nuvem suportado; no entanto, notificações por push para o Event Grid só são suportadas em contas Snowflake hospedadas no Azure

Notas

  • Snowflake garante a entrega de notificações de erro pelo menos uma vez (ou seja, são feitas várias tentativas de entrega de mensagens para garantir pelo menos uma tentativa bem sucedida, o que pode resultar em mensagens duplicadas).

  • Esse recurso é implementado utilizando o objeto de integração de notificação. 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. Uma única integração de notificação pode oferecer suporte a múltiplos canais.

Habilitação de notificações de erro

Etapa 1: Criar um tópico personalizado do Event Grid

Um tópico do Event Grid oferece um ponto de extremidade para o qual a fonte envia notificações de eventos. Crie um tópico dedicado para receber notificações de erro publicadas pelo Snowflake. Você pode usar um único tópico para receber notificações de erro para todos os canais (para notificações de erro do Snowpipe) ou tarefas (para notificações de erro da tarefa) em sua conta Snowflake.

Para instruções sobre a criação de tópicos do Event Grid, consulte a documentação do Event Grid. Registre o ponto de extremidade do tópico do Event Grid, pois ele será necessário mais tarde nestas instruções.

Opcionalmente, inscreva-se no tópico para informar o Event Grid que você deseja acompanhar e para onde enviar esses eventos.

Etapa 2: Criar uma integração de notificação no Snowflake

Recupere a ID do locatário

Recupere a ID do locatário do Azure, pois ela será necessária mais tarde nestas instruções.

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

  2. 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 o URL de consentimento que concede ao Snowflake acesso ao tópico do Event Grid.

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

Crie uma integração usando o comando CREATE NOTIFICATION INTEGRATION. Uma integração é um objeto Snowflake que faz referência à fila de armazenamento Azure que você criou.

Nota

Somente administradores de conta (usuários com a função ACCOUNTADMIN) ou uma função com o privilégio global CREATE INTEGRATION podem executar este comando SQL.

CREATE NOTIFICATION INTEGRATION <integration_name>
  ENABLED = true
  TYPE = QUEUE
  NOTIFICATION_PROVIDER = AZURE_EVENT_GRID
  DIRECTION = OUTBOUND
  AZURE_EVENT_GRID_TOPIC_ENDPOINT = '<event_grid_topic_endpoint>'
  AZURE_TENANT_ID = '<azure_tenant_id>'
Copy

Por exemplo:

CREATE NOTIFICATION INTEGRATION myint
  ENABLED = true
  TYPE = QUEUE
  NOTIFICATION_PROVIDER = AZURE_EVENT_GRID
  DIRECTION = OUTBOUND
  AZURE_EVENT_GRID_TOPIC_ENDPOINT = 'https://myaccount.region-1.eventgrid.azure.net/api/events'
  AZURE_TENANT_ID = 'mytenantid';
Copy

Onde:

  • event_grid_topic_endpoint é o ponto de extremidade do tópico do Event Grid que você registrou na seção Etapa 1.

  • azure_tenant_id é sua ID de diretório Azure ou ID de locatário que você registrou anteriormente nesta seção.

Concessão de acesso do Snowflake ao tópico

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

    DESC NOTIFICATION INTEGRATION <integration_name>;
    
    Copy

    Onde:

    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 tenha um token de acesso em recursos específicos 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é Event Grid Topics » topic_name, onde topic_name é o nome do tópico que você criou para receber notificações de eventos.

  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 a permissão remetente de dados EventGrid.

Etapa 3: habilitar notificações de erro em canais

Uma única integração de notificação pode ser compartilhada por vários canais. O corpo das mensagens de erro identifica o canal, o caminho e o estágio externo, o arquivo onde o erro se originou, entre outros detalhes.

Para permitir notificações de erro de um canal, especifique um valor de parâmetro ERROR_INTEGRATION.

Nota

A criação ou modificação de um canal que faz referência a uma integração de notificação requer uma função que tenha o privilégio USAGE sobre a integração de notificação. Além disso, a função deve ter ou o privilégio CREATE PIPE sobre o esquema ou o privilégio OWNERSHIP sobre o canal, respectivamente.

Observe que operar em qualquer objeto de um esquema também requer o privilégio USAGE no banco de dados e esquema principais.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Novo canal

Crie um novo canal usando CREATE PIPE:

CREATE PIPE <name>
  AUTO_INGEST = TRUE
  [ INTEGRATION = '<string>' ]
  ERROR_INTEGRATION = <integration_name>
  AS <copy_statement>
Copy

Onde:

ERROR_INTEGRATION = <nome_integração>

Nome da integração de notificação que você criou em Etapa 4: Criar a integração de notificação (neste tópico).

Por exemplo:

CREATE PIPE mypipe
  AUTO_INGEST = TRUE
  INTEGRATION = 'my_storage_int'
  ERROR_INTEGRATION = my_notification_int
  AS
  COPY INTO mydb.public.mytable
  FROM @mydb.public.mystage;
Copy

Canal existente

Modifique um canal existente usando ALTER PIPE:

ALTER PIPE <name> SET ERROR_INTEGRATION = <integration_name>;
Copy

Em que <integration_name> é o nome da integração de notificação que você criou em Etapa 4: Criar a integração de notificação (neste tópico).

Por exemplo:

ALTER PIPE mypipe SET ERROR_INTEGRATION = my_notification_int;
Copy

Carga útil de mensagem de notificação de erro

O corpo de mensagens de erro identifica o canal e os erros encontrados durante um carregamento.

O seguinte é uma mensagem de exemplo de carga útil descrevendo um erro do Snowpipe. A carga útil pode incluir uma ou mais mensagens de erro.

{\"version\":\"1.0\",\"messageId\":\"a62e34bc-6141-4e95-92d8-f04fe43b43f5\",\"messageType\":\"INGEST_FAILED_FILE\",\"timestamp\":\"2021-10-22T19:15:29.471Z\",\"accountName\":\"MYACCOUNT\",\"pipeName\":\"MYDB.MYSCHEMA.MYPIPE\",\"tableName\":\"MYDB.MYSCHEMA.MYTABLE\",\"stageLocation\":\"azure://myaccount.blob.core.windows.net/mycontainer/mypath\",\"messages\":[{\"fileName\":\"/file1.csv_0_0_0.csv.gz\",\"firstError\":\"Numeric value 'abc' is not recognized\"}]}
Copy

Observe que você deve analisar a cadeia de caracteres em um objeto JSON para processar valores na carga útil.