Aktivieren von Fehlerbenachrichtigungen für Snowpipe

Unter diesem Thema wird eine Anleitung zur Konfiguration von Fehlerbenachrichtigungen für Snowpipe bereitgestellt. Wenn Snowpipe beim Laden von Daten aus einer Stagingdatei auf Fehler stößt, löst diese Funktion eine Benachrichtigung aus, die die Fehler mithilfe von Cloudmessaging beschreibt und eine weitere Analyse der Daten in der Datei ermöglicht.

Bemerkung

Diese Funktion ist auf Snowflake-Konten beschränkt, die auf Amazon Web Services (AWS) gehostet werden. Mithilfe der Pipeobjekte in einem Konto können Daten aus Dateien jedes unterstützten Cloudspeicherdienstes geladen werden, allerdings kann Snowpipe Fehlerbenachrichtigungen derzeit nur an den Amazon Simple Notification Service (SNS) senden.

Unterstützung von Snowflake-Konten, die auf Google Cloud oder Microsoft Azure gehostet werden, und die entsprechenden Cloudmessagingdienste sind in Planung.

Diese Funktion unterstützt sowohl Aufrufe über die Snowpipe-REST-API als auch Snowpipe mit automatisierter Erfassung über einen Cloudmessagingdienst.

Unter diesem Thema:

Anmerkungen

  • Snowflake bemüht sich nach besten Kräften, die Zustellung von Fehlerbenachrichtigungen sicherzustellen, kann aber während dieser Vorschauphase die Zustellung nicht garantieren.

  • Diese Funktion wird mithilfe des Benachrichtigungsintegrationsobjekts implementiert. Eine Benachrichtigungsintegration ist ein Snowflake-Objekt, das als Schnittstelle zwischen Snowflake und Cloud-Meldungswarteschlangendiensten von Drittanbietern dient. Eine einzelne Benachrichtigungsintegration kann mehrere Pipes unterstützen.

Aktivieren von Fehlerbenachrichtigungen für Amazon S3

Dieser Abschnitt enthält eine Anleitung zum Konfigurieren von Fehlerbenachrichtigungen mit dem SNS-Dienst (Amazon Simple Notification Service). SNS ist ein Publish/Subscribe-Nachrichtendienst.

Schritt 1: Erstellen eines Amazon SNS-Themas

Erstellen Sie ein SNS-Thema in Ihrem AWS-Konto, um alle Fehlermeldungen zu bearbeiten. Notieren Sie sich den Amazon Resource Name (ARN) für das SNS-Thema.

Um die Latenz zu verringern und Gebühren für ausgehende Daten für das Senden von Benachrichtigungen zwischen Regionen zu vermeiden, empfehlen wir, das SNS-Thema in derselben Region wie Ihr Snowflake-Konto zu erstellen.

Eine Anleitung dazu finden Sie in der SNS-Dokumentation unter Erstellen eines Amazon SNS-Themas.

Schritt 2: Erstellen der IAM-Richtlinie

Erstellen Sie eine AWS-Richtlinie für die Identitäts- und Zugriffsverwaltung (IAM), die Berechtigungen zur Veröffentlichung im SNS-Thema erteilt. In der Richtlinie sind die folgenden Aktionen definiert:

  • sns:publish

    Veröffentlichen im SNS-Thema.

  1. Anmelden bei der AWS Management Console.

  2. Wählen Sie auf dem Startseiten-Dashboard die Option Identity & Access Management (IAM) aus:

  3. Wählen Sie im linken Navigationsbereich Account settings aus.

  4. Erweitern Sie die Security Token Service Regions-Liste, suchen Sie die AWS-Region, die der Region entspricht, in der sich Ihr Konto befindet, und wählen Sie Activate, wenn der Status Inactive ist.

  5. Wählen Sie im linken Navigationsbereich Policies aus.

  6. Klicken Sie auf Create Policy.

  7. Klicken Sie auf die Registerkarte JSON.

  8. Fügen Sie ein Richtliniendokument hinzu, das Aktionen definiert, die für Ihr SNS-Thema ausgeführt werden können.

    Kopieren Sie den Text, und fügen Sie ihn in den Richtlinieneditor ein:

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

    Ersetzen Sie sns_topic_arn durch den ARN des SNS-Themas, das Sie in Schritt 1: Erstellen eines Amazon SNS-Themas (unter diesem Thema) erstellt haben.

  9. Klicken Sie auf Review policy.

  10. Geben Sie den Richtliniennamen (z. B. snowflake_sns_topic) und eine optionale Beschreibung ein. Klicken Sie auf Create policy.

Schritt 3: Erstellen der AWS-IAM-Rolle

Erstellen Sie eine AWS-IAM-Rolle, der Sie Berechtigung für das SNS-Thema zuweisen können.

  1. Anmelden bei der AWS Management Console.

  2. Wählen Sie auf dem Startseiten-Dashboard die Option Identity & Access Management (IAM) aus:

  3. Wählen Sie im linken Navigationsbereich Roles aus.

  4. Klicken Sie auf die Schaltfläche Create role.

  5. Wählen Sie Another AWS account als vertrauenswürdigen Entitätstyp aus.

  6. Geben Sie im Feld Account ID vorläufig Ihre eigene AWS-Konto-ID ein.

  7. Wählen Sie die Option Require external ID aus. Mit dieser Option können Sie Dritten (z. B. Snowflake) Berechtigungen für die Ressourcen Ihres Amazon-Kontos (d. h. SNS) erteilen.

    Geben Sie vorläufig eine Dummy-ID ein, wie z. B. 0000. Später werden Sie die Vertrauensstellung ändern und die Dummy-ID durch die externe ID für den Snowflake-IAM-Benutzer ersetzen, der für Ihr Konto erstellt wurde. Eine Bedingung in der Vertrauensrichtlinie Ihrer IAM-Rolle ermöglicht es Ihren Snowflake-Benutzern, die Rolle mithilfe des Benachrichtigungsintegrationsobjekts zu übernehmen, das Sie später erstellen werden.

  8. Klicken Sie auf die Schaltfläche Next.

  9. Suchen Sie die Richtlinie, die Sie in Schritt 2: Erstellen der IAM-Richtlinie (unter diesem Thema) erstellt haben, und wählen Sie diese Richtlinie aus.

  10. Klicken Sie auf die Schaltfläche Next.

  11. Geben Sie einen Namen und eine Beschreibung für die Rolle ein, und klicken Sie auf die Schaltfläche Create role.

  12. Notieren Sie den Role ARN-Wert, der auf der Übersichtsseite der Rolle angegeben ist. Sie werden diesen Wert in einem oder mehreren späteren Schritten angeben.

Schritt 4: Erstellen der Benachrichtigungsintegration

Erstellen Sie eine Benachrichtigungsintegration mit CREATE NOTIFICATION INTEGRATION. Eine Integration ist ein Snowflake-Objekt, das auf das von Ihnen erstellte SNS-Thema verweist.

Eine einzelne Benachrichtigungsintegration kann mehrere Pipes unterstützen.

Bemerkung

Dieser SQL-Befehl kann nur von Kontoadministratoren (Benutzer mit der Rolle ACCOUNTADMIN) oder von Rollen mit der globalen Berechtigung CREATE INTEGRATION ausgeführt werden.

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

Wobei:

<Name_der_Integration>

Name der neuen Integration.

DIRECTION = OUTBOUND

Richtung für das Cloudmessaging in Bezug auf Snowflake. Nur für das Konfigurieren von Fehlerbenachrichtigungen erforderlich.

<ARN_des_Themas>

SNS-Thema-ARN, den Sie sich in Schritt 1: Erstellen eines Amazon SNS-Themas (unter diesem Thema) notiert haben.

<ARN_der_IAM-Rolle>

IAM-Rollen-ARN, den Sie sich in Schritt 3: Erstellen der AWS-IAM-Rolle (unter diesem Thema) notiert haben.

Beispiel:

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

Schritt 5: Snowflake Zugriff auf das SNS-Thema gewähren

IAM-Benutzer-ARN und externe SNS-Thema-ID abrufen

  1. Führen Sie DESCRIBE INTEGRATION aus:

    DESC NOTIFICATION INTEGRATION <integration_name>;
    

    Wobei:

    • Name_der_Integration ist der Name der Benachrichtigungsintegration, die Sie in Schritt 4: Erstellen der Benachrichtigungsintegration (unter diesem Thema) erstellt haben.

    Beispiel:

    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=   |                      |
    +---------------------------+-------------------+------------------------------------------------------+----------------------+
    
  2. Notieren Sie sich die folgenden generierten Werte:

    SF_AWS_IAM_USER_ARN

    ARN des Snowflake-IAM-Benutzers, der für Ihr Konto erstellt wurde. Die Benutzer in Ihrem Snowflake-Konto übernehmen die IAM-Rolle, die Sie in Schritt 3: Erstellen der AWS-IAM-Rolle erstellt haben, indem Sie die externe ID dieses Benutzers über Ihre Benachrichtigungsintegration übermitteln.

    SF_AWS_EXTERNAL_ID

    Externe ID des Snowflake-IAM-Benutzers, der für Ihr Konto erstellt wurde.

    Im nächsten Schritt werden Sie die Vertrauensstellung für die IAM-Rolle mit diesen Werten aktualisieren.

Beachten Sie die Eigenschaft DIRECTION, die die Richtung für das Cloudmessaging in Bezug auf Snowflake angibt.

Vertrauensstellung in der IAM-Rolle ändern

  1. Anmelden bei der AWS Management Console.

  2. Wählen Sie auf dem Startseiten-Dashboard die Option Identity & Access Management (IAM) aus:

  3. Wählen Sie im linken Navigationsbereich Roles aus.

  4. Klicken Sie auf die Rolle, die Sie in Schritt 3: AWS-IAM-Rolle erstellen (unter diesem Thema) erstellt haben.

  5. Klicken Sie auf die Registerkarte Trust relationships.

  6. Klicken Sie auf die Schaltfläche Edit trust relationship.

  7. Ändern Sie das Richtliniendokument mit den DESC NOTIFICATION INTEGRATION-Ausgabewerten, die Sie sich unter IAM-Benutzer-ARN und externe SNS-Thema-ID abrufen (unter diesem Thema) notiert haben:

    Richtliniendokument für die IAM-Rolle

    {
      "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>"
            }
          }
        }
      ]
    }
    

    Wobei:

    • sf_aws_iam_user_arn ist der von Ihnen notierte SF_AWS_IAM_USER_ARN-Wert.

    • sf_aws_external_id ist der von Ihnen notierte SF_AWS_EXTERNAL_ID-Wert.

  8. Klicken Sie auf die Schaltfläche Update Trust Policy. Die Änderungen werden gespeichert.

Schritt 6: Aktivieren von Fehlerbenachrichtigungen in Pipes

Eine einzelne Benachrichtigungsintegration kann von mehreren Pipes gemeinsam genutzt werden. Im Hauptteil der Fehlermeldung werden unter anderem die Pipe, der externe Stagingbereich mit seinem Pfad sowie die Datei, in der der Fehler aufgetreten ist, angegeben.

Um Fehlerbenachrichtigungen für eine Pipe zu aktivieren, geben Sie einen ERROR_INTEGRATION-Parameterwert an.

Bemerkung

Zum Erstellen oder Ändern einer Pipe, die auf eine Benachrichtigungsintegration verweist, ist eine Rolle erforderlich, die über die Berechtigung USAGE für die Benachrichtigungsintegration verfügt. Außerdem muss die Rolle entweder die CREATE PIPE-Berechtigung für das Schema oder die OWNERSHIP-Berechtigung für die Pipe haben.

Neue Pipe

Erstellen Sie eine neue Pipe mit CREATE PIPE. Beachten Sie, dass für die Konfiguration des automatischen Ladens von Daten (z. B. automatische Erfassung mit Snowpipe) zusätzliche Pipe-Parameter erforderlich sind. Eine Anleitung dazu finden Sie unter Automatisieren des kontinuierlichen Ladens von Daten mithilfe von Cloudmessaging.

CREATE PIPE <name>
  [ AUTO_INGEST = TRUE | FALSE  ]
  ERROR_INTEGRATION = <integration_name>
  AS <copy_statement>

Wobei:

ERROR_INTEGRATION = <Name_der_Integration>

Name der Benachrichtigungsintegration, die Sie in Schritt 4: Erstellen der Benachrichtigungsintegration (unter diesem Thema) erstellt haben.

Das folgende Beispiel zeigt eine CREATE PIPE-Anweisung, die sowohl Fehlerbenachrichtigungen als auch das automatische Laden von Daten unterstützt:

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

Vorhandene Pipe

Ändern Sie eine vorhandene Pipe mit ALTER PIPE:

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

<Name_der_Integration> ist der Name der Benachrichtigungsintegration, die Sie in Schritt 4: Erstellen der Benachrichtigungsintegration (unter diesem Thema) erstellt haben.

Beispiel:

ALTER PIPE my_notification_int SET ERROR_INTEGRATION = my_notification_int;

Meldungsnutzlast von Fehlerbenachrichtigungen

Im Hauptteil der Fehlermeldungen werden die Pipe und die während des Ladevorgangs aufgetretenen Fehler angegeben.

Nachfolgend finden Sie ein Beispiel für eine Meldungsnutzlast, die einen Snowpipe-Fehler beschreibt. Die Nutzlast kann eine oder mehrere Fehlermeldungen enthalten.

{\"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\"}]}

Beachten Sie, dass Sie die Zeichenfolge in ein JSON-Objekt parsen müssen, um die Werte in der Nutzlast zu verarbeiten.

Zurück zum Anfang