Habilitação de notificações de erro do Snowpipe para o Amazon SNS

Este tópico fornece instruções para enviar as notificações de erro do Snowpipe para o serviço Amazon Simple Notification Service (SNS). SNS é um serviço de assinatura/publicação de mensagens.

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, este recurso está limitado às contas Snowflake hospedadas em Amazon Web Services (AWS). O Snowpipe pode carregar dados de arquivos em qualquer serviço de armazenamento em nuvem suportado; no entanto, notificações por push para o SNS só são suportadas em contas Snowflake hospedadas na AWS.

Notas

  • 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.

  • 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).

Habilitação de notificações de erro

Etapa 1: Criar um tópico do Amazon SNS

Crie um tópico SNS em sua conta AWS para lidar com todas as mensagens de erro. Registre o Amazon Resource Name (ARN) para o tópico SNS.

Nota

Apenas tópicos SNS padrão são suportados. Não crie tópicos SNS FIFO (primeiro a entrar, primeiro a sair) para uso com notificações de erro. Atualmente, as notificações de erro enviadas para tópicos FIFO falham silenciosamente.

Para reduzir a latência e evitar cobranças de saída de dados pelo envio de notificações entre regiões, recomendamos criar o tópico SNS na mesma região que sua conta Snowflake.

Para instruções, consulte o tópico Criar um tópico do Amazon SNS na documentação do SNS.

Etapa 2: Criar a política IAM

Crie uma política do AWS Identity and Access Management (IAM) que concede permissões para publicar no tópico SNS. A política define as seguintes ações:

  • sns:publish

    Publicar no tópico SNS.

  1. Faça login no Console de gerenciamento AWS.

  2. No painel inicial, escolha Identity & Access Management (IAM):

  3. Escolha Account settings no painel de navegação à esquerda.

  4. Expanda a lista Security Token Service Regions, encontre a região AWS correspondente à região onde sua conta está localizada e escolha Activate se o status for Inactive.

  5. Escolha Policies no painel de navegação à esquerda.

  6. Clique em Create Policy.

  7. Clique na guia JSON.

  8. Adicione um documento de política que defina as ações que podem ser tomadas sobre seu tópico SNS.

    Copie e cole o texto a seguir no editor de políticas:

    {
        "Version": "2012-10-17",
        "Statement": [
          {
             "Effect": "Allow",
             "Action": [
                 "sns:Publish"
             ],
             "Resource": "<sns_topic_arn>"
          }
        ]
     }
    
    Copy

    Substitua sns_topic_arn pelo ARN do tópico SNS que você criou em Etapa 1: Criar um tópico do Amazon SNS (neste tópico).

  9. Clique em Review policy.

  10. Digite o nome da política (por exemplo, snowflake_sns_topic) e uma descrição opcional. Clique em Create policy.

Etapa 3: Criar a função AWS IAM

Crie uma função AWS IAM na qual atribuir privilégios sobre o tópico SNS.

  1. Faça login no Console de gerenciamento AWS.

  2. No painel inicial, escolha Identity & Access Management (IAM):

  3. Escolha Roles no painel de navegação à esquerda.

  4. Clique no botão Create role.

  5. Selecione Another AWS account como o tipo de entidade confiável.

  6. No campo Account ID, digite temporariamente sua própria ID de conta AWS.

  7. Selecione a opção Require external ID. Esta opção permite que você conceda permissões sobre os recursos de sua conta Amazon (ou seja, SNS) a um terceiro (ou seja, Snowflake).

    Por enquanto, insira uma ID fictícia, como 0000. Mais tarde, você modificará a relação de confiança e substituirá a ID fictícia pela ID externa para o IAM do Snowflake gerado pelo usuário para sua conta. Uma condição na política de confiança para sua função IAM permite que seus usuários do Snowflake assumam a função usando o objeto de integração de notificação que você criará mais tarde.

  8. Clique no botão Next.

  9. Localize a política que você criou em Etapa 2: Criar a política IAM (neste tópico) e selecione essa política.

  10. Clique no botão Next.

  11. Digite um nome e descrição para a função e clique no botão Create role.

  12. Registre o valor Role ARN localizado na página de resumo de funções. Você especificará esse valor em uma ou mais etapas posteriores.

Etapa 4: Criar a integração de notificação

Crie uma integração de notificação usando CREATE NOTIFICATION INTEGRATION. Uma integração é um objeto Snowflake que faz referência ao tópico SNS que você criou.

Uma única integração de notificação pode oferecer suporte a múltiplas tarefas e canais.

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 = AWS_SNS
  DIRECTION = OUTBOUND
  AWS_SNS_TOPIC_ARN = '<topic_arn>'
  AWS_SNS_ROLE_ARN = '<iam_role_arn>'
Copy

onde:

<nome_integração>

Nome da nova integração.

DIRECTION = OUTBOUND

Direção das mensagem em nuvem em relação ao Snowflake. Necessário somente ao configurar notificações de erro.

<arn_tópico>

ARN do tópico SNS que você registrou em Etapa 1: Criar um tópico do Amazon SNS (neste tópico).

<arn_função_iam>

A função IAM ARN que você registrou em Etapa 3: Criar a função AWS IAM (neste tópico).

Por exemplo:

CREATE NOTIFICATION INTEGRATION my_notification_int
  ENABLED = true
  TYPE = QUEUE
  NOTIFICATION_PROVIDER = AWS_SNS
  DIRECTION = OUTBOUND
  AWS_SNS_TOPIC_ARN = 'arn:aws:sns:us-east-2:111122223333:sns_topic'
  AWS_SNS_ROLE_ARN = 'arn:aws:iam::111122223333:role/error_sns_role';
Copy

Etapa 5: Conceder acesso do Snowflake ao tópico SNS

Recuperação do ARN do usuário IAM e da ID externa do tópico SNS

  1. Execute DESCRIBE INTEGRATION:

    DESC NOTIFICATION INTEGRATION <integration_name>;
    
    Copy

    onde:

    • 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:

    DESC NOTIFICATION INTEGRATION my_notification_int;
    
    +---------------------------+-------------------+------------------------------------------------------+----------------------+
    |   property                |   property_type   |   property_value                                     |   property_default   |
    +---------------------------+-------------------+------------------------------------------------------+----------------------+
    |   ENABLED                 |   Boolean         |   true                                               |   false              |
    |   NOTIFICATION_PROVIDER   |   String          |   AWS_SNS                                            |                      |
    |   DIRECTION               |   String          |   OUTBOUND                                           |   INBOUND            |
    |   AWS_SNS_TOPIC_ARN       |   String          |   arn:aws:sns:us-east-2:111122223333:myaccount       |                      |
    |   AWS_SNS_ROLE_ARN        |   String          |   arn:aws:iam::111122223333:role/myrole              |                      |
    |   SF_AWS_IAM_USER_ARN     |   String          |   arn:aws:iam::123456789001:user/c_myaccount         |                      |
    |   SF_AWS_EXTERNAL_ID      |   String          |   MYACCOUNT_SFCRole=2_a123456/s0aBCDEfGHIJklmNoPq=   |                      |
    +---------------------------+-------------------+------------------------------------------------------+----------------------+
    
    Copy
  2. Registre os seguintes valores gerados:

    SF_AWS_IAM_USER_ARN:

    ARN para o usuário IAM do Snowflake criado para sua conta. Os usuários em sua conta Snowflake assumirão a função IAM que você criou em Etapa 3: Criar a função AWS IAM apresentando a ID externa para esse usuário usando sua integração de notificação.

    SF_AWS_EXTERNAL_ID:

    ID externa para o usuário IAM do Snowflake criado para sua conta.

    Na próxima etapa, você atualizará a relação de confiança para a função IAM com esses valores.

Observe a propriedade DIRECTION, que indica a direção da mensagem em nuvem em relação ao Snowflake.

Modifique a relação de confiança na função IAM

  1. Faça login no Console de gerenciamento AWS.

  2. No painel inicial, escolha Identity & Access Management (IAM):

  3. Escolha Roles no painel de navegação à esquerda.

  4. Clique na função que você criou em Etapa 3: Criar a função AWS IAM (neste tópico).

  5. Clique na guia Trust relationships.

  6. Clique no botão Edit trust relationship.

  7. Modifique o documento da política com os valores de saída DESC NOTIFICATION INTEGRATION registrados em Recuperação do ARN do usuário IAM e da ID externa do tópico SNS (neste tópico):

    Documento de política da função IAM

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "",
          "Effect": "Allow",
          "Principal": {
            "AWS": "<sf_aws_iam_user_arn>"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "<sf_aws_external_id>"
            }
          }
        }
      ]
    }
    
    Copy

    onde:

    • sf_aws_iam_user_arn é o valor SF_AWS_IAM_USER_ARN que você registrou.

    • sf_aws_external_id é o valor SF_AWS_EXTERNAL_ID que você registrou.

  8. Clique no botão Update Trust Policy. As alterações são salvas.

Etapa 6: 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. Observe que a configuração de carregamentos automatizados de dados (ou seja, o Snowpipe com ingestão automática) requer parâmetros adicionais do canal. Para obter instruções, consulte Automatização do carregamento contínuo de dados usando mensagens em nuvem.

CREATE PIPE <name>
  [ AUTO_INGEST = TRUE | FALSE  ]
  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).

O exemplo a seguir mostra uma instrução CREATE PIPE compatível tanto com notificações de erro como com carregamentos automatizados de dados:

CREATE PIPE mypipe
  AUTO_INGEST = TRUE
  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\":\"s3://mybucket/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.