Vorbereiten des Ladens von Daten über die Snowpipe REST-API

Unter diesem Thema wird beschrieben, wie Sie mit Snowpipe beim Aufruf der REST-API beginnen, einschließlich Anweisungen zur Installation des gewünschten Client-SDK, zum Erstellen eines Stagingbereichs (falls erforderlich) und einer Pipe sowie der einmaligen Sicherheitseinrichtung für jeden Snowpipe-Benutzer.

Unter diesem Thema:

Bemerkung

Bei den Anweisungen in diesem Abschnitt wird davon ausgegangen, dass Sie bereits eine Zieltabelle in Ihrer Snowflake-Datenbank haben, in die Ihre Daten geladen werden.

Clientanforderung (Java- oder Python-SDK)

Für den Snowpipe-Service ist entweder das Java-SDK oder das Python-SDK erforderlich. Diese SDKs werden von Snowflake bereitgestellt.

Wichtig

Die Binärdateien werden als Clientsoftware im Rahmen Ihres Master Service Agreements (MSA, Dienstleistungsrahmenvertrag) mit Snowflake bereitgestellt.

Installation des Java-SDK

  1. Laden Sie das Java-SDK-Installationsprogramm aus dem Maven Central Repository herunter:

    http://search.maven.org/ (oder https://repo1.maven.org/maven2/net/snowflake/snowflake-ingest-sdk)

  2. Integrieren Sie die JAR-Datei in ein bestehendes Projekt.

Bemerkung

Die Entwicklerhinweise werden mit dem Quellcode auf GitHub gehostet.

Installieren des Python-SDK

Beachten Sie, dass das Python-SDK Python 3.5 oder höher erfordert.

Führen Sie den folgenden Befehl aus, um das SDK zu installieren:

pip install snowflake-ingest

Laden Sie alternativ die Wheel-Datei von PyPI herunter und integrieren Sie sie in ein vorhandenes Projekt.

Bemerkung

Die Entwicklerhinweise werden mit dem Quellcode auf GitHub gehostet.

Schritt 1: Stagingbereich erstellen (falls erforderlich)

Snowpipe unterstützt das Laden aus den folgenden Stagingbereichstypen:

  • Benannte interne (Snowflake) oder externe (Amazon S3, Google Cloud Storage oder Microsoft Azure) Stagingbereiche

  • Tabellen-Stagingbereiche

Erstellen Sie einen benannten Stagingbereich mit dem Befehl CREATE STAGE, oder verwenden Sie einen vorhandenen Stagingbereich. Sie stellen Ihre Dateien vorübergehend im Stagingbereich bereit, bevor Snowpipe sie in Ihre Zieltabelle lädt.

Schritt 2: Pipe erstellen

Erstellt eine neue Pipe im System zum Definieren der COPYINTO <Tabelle>-Anweisung, die von Snowpipe zum Laden von Daten aus einer Erfassungswarteschlange in Tabellen verwendet wird. Weitere Informationen dazu finden Sie unter CREATE PIPE.

Bemerkung

Das Erstellen einer Pipe erfordert die Zugriffssteuerungsberechtigung CREATE PIPE sowie die Berechtigung USAGE für Datenbank, Schema und Stagingbereich.

Erstellen Sie beispielsweise im mydb.myschema-Schema eine Pipe, die alle Daten aus den im mystage-Stagingbereich bereitgestellten Dateien in die mytable-Tabelle lädt:

create pipe mydb.myschema.mypipe if not exists as copy into mydb.myschema.mytable from @mydb.myschema.mystage;

Schritt 3: Sicherheit konfigurieren (pro Benutzer)

Für jeden Benutzer, der kontinuierliches Laden von Daten mit Snowpipe durchführt, generieren Sie ein öffentlich-privates Schlüsselpaar für Aufrufe von Snowpipe-REST-Endpunkten. Vergeben Sie außerdem ausreichende Berechtigungen an den Objekten für das Laden von Daten (d. h. Zieldatenbank, Schema und Tabelle), das Stagingobjekt und die Pipe.

Wenn Sie das Snowpipe-Datenladen auf einen einzelnen Benutzer beschränken möchten, müssen Sie die Schlüsselpaar-Authentifizierung für den Benutzer nur einmal konfigurieren. Danach müssen Sie nur noch Zugriffssteuerungsrechte für die Datenbankobjekte vergeben, die für jede Datenladeoperation verwendet werden.

Bemerkung

Um dem allgemeinen Prinzip der geringsten Berechtigungen zu folgen, empfehlen wir, einen separaten Benutzer und eine eigene Rolle für die Aufnahme von Dateien über eine Pipe zu erstellen. Der Benutzer sollte mit dieser Rolle als Standardrolle erstellt werden.

Verwenden der Schlüsselpaar-Authentifizierung

Snowflake unterstützt die Verwendung von Schlüsselpaar-Authentifizierung anstelle der typischen Authentifizierung durch Benutzernamen und Kennwort. Dieses Authentifizierungsverfahren erfordert ein 2048-Bit-RSA-Schlüsselpaar (Minimum). Generieren Sie das öffentlich-private PEM (Privacy Enhanced Mail)-Schlüsselpaar unter Verwendung von OpenSSL. Der öffentliche Schlüssel wird dem Snowflake-Benutzer zugewiesen, der den Snowpipe-Service nutzen wird.

So konfigurieren Sie das Public/Private-Schlüsselpaar:

  1. Generieren Sie über die Befehlszeile in einem Terminalfenster einen privaten Schlüssel:

    Sie können entweder eine verschlüsselte Version des privaten Schlüssels oder eine unverschlüsselte Version des privaten Schlüssels generieren.

    Um eine unverschlüsselte Version zu generieren, verwenden Sie den folgenden Befehl:

    $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
    

    Um eine verschlüsselte Version zu generieren, verwenden Sie den folgenden Befehl (ohne „-nocrypt“):

    $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8
    

    Es ist normalerweise sicherer, eine verschlüsselte Version zu erstellen.

    Wenn Sie den zweiten Befehl zum Verschlüsseln des privaten Schlüssels verwenden, fordert OpenSSL Sie zur Eingabe einer Passphrase auf, die zum Verschlüsseln der Datei des privaten Schlüssels verwendet wird. Wir empfehlen, zum Schutz des privaten Schlüssels eine starke Passphrase zu verwenden. Notieren Sie sich diese Passphrase an einem sicheren Ort. Sie müssen sie beim Herstellen der Verbindung mit Snowflake eingeben. Beachten Sie, dass die Passphrase nur zum Schutz des privaten Schlüssels verwendet wird und niemals an Snowflake gesendet wird.

    Beispiel für einen privaten PEM-Schlüssel

    -----BEGIN ENCRYPTED PRIVATE KEY-----
    MIIE6TAbBgkqhkiG9w0BBQMwDgQILYPyCppzOwECAggABIIEyLiGSpeeGSe3xHP1
    wHLjfCYycUPennlX2bd8yX8xOxGSGfvB+99+PmSlex0FmY9ov1J8H1H9Y3lMWXbL
    ...
    -----END ENCRYPTED PRIVATE KEY-----
    
  2. Generieren Sie über die Befehlszeile den öffentlichen Schlüssel, indem Sie auf den privaten Schlüssel verweisen:

    Angenommen, der private Schlüssel befindet sich in der Datei „rsa_key.p8“, verwenden Sie den folgenden Befehl:

    $ openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
    

    Beispiel für einen öffentlichen PEM-Schlüssel

    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy+Fw2qv4Roud3l6tjPH4
    zxybHjmZ5rhtCz9jppCV8UTWvEXxa88IGRIHbJ/PwKW/mR8LXdfI7l/9vCMXX4mk
    ...
    -----END PUBLIC KEY-----
    
  3. Kopieren Sie die Dateien der öffentlichen und privaten Schlüssel zur Speicherung in einem lokalen Verzeichnis. Zeichnen Sie den Pfad zu den Dateien auf. Beachten Sie, dass der private Schlüssel im Format PKCS#8 (Public Key Cryptography Standards) gespeichert und mit der im vorherigen Schritt angegebenen Passphrase verschlüsselt wird; die Datei sollte jedoch weiterhin mit dem von Ihrem Betriebssystem bereitgestellten Dateiberechtigungsmechanismus vor unbefugtem Zugriff geschützt sein. Es liegt in Ihrer Verantwortung, die Datei zu sichern, wenn sie nicht verwendet wird.

  4. Weisen Sie dem Snowflake-Benutzer den öffentlichen Schlüssel mit ALTER USER zu. Beispiel:

    ALTER USER jsmith SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
    

    Bemerkung

    • Nur Sicherheitsadministratoren (d. h. Benutzer mit der Rolle SECURITYADMIN oder höher) können andere Benutzer ändern.

    • Schließen Sie die Kopf- und Fußzeile des öffentlichen Schlüssels in der SQL-Anweisung aus.

    Überprüfen Sie den Fingerabdruck des öffentlichen Schlüssels des Benutzers mithilfe von DESCRIBE USER:

    DESC USER jsmith;
    +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
    | property                      | value                                               | default | description                                                                   |
    |-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------|
    | NAME                          | JSMITH                                              | null    | Name                                                                          |
    ...
    ...
    | RSA_PUBLIC_KEY_FP             | SHA256:nvnONUsfiuycCLMXIEWG4eTp4FjhVUZQUQbNpbSHXiA= | null    | Fingerprint of user's RSA public key.                                         |
    | RSA_PUBLIC_KEY_2_FP           | null                                                | null    | Fingerprint of user's second RSA public key.                                  |
    +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
    

    Bemerkung

    Eine Beschreibung der Eigenschaft RSA_PUBLIC_KEY_2_FP finden Sie unter Schlüsselrotation (unter diesem Thema).

Schlüsselrotation

Snowflake unterstützt mehrere aktive Schlüssel, um eine ununterbrochene Rotation zu ermöglichen. Rotieren und ersetzen Sie Ihre öffentlichen und privaten Schlüssel basierend auf dem Ablaufzeitplan, den Sie intern einhalten.

Derzeit können Sie die Parameter RSA_PUBLIC_KEY und RSA_PUBLIC_KEY_2 für ALTER USER verwenden, um einem einzelnen Benutzer bis zu zwei öffentliche Schlüssel zuzuordnen.

So rotieren Sie Ihre Schlüssel:

  1. Führen Sie die unter Verwenden der Schlüsselpaar-Authentifizierung angegebenen Schritte aus, um Folgendes zu ermöglichen:

    • Generieren eines neuen privaten und öffentlichen Schlüsselsatzes

    • Zuweisen des öffentlichen Schlüssels an einen Benutzer Setzen Sie den Wert des öffentlichen Schlüssels entweder auf RSA_PUBLIC_KEY oder RSA_PUBLIC_KEY_2 (je nachdem, welcher Schlüsselwert gerade nicht verwendet wird). Beispiel:

      alter user jsmith set rsa_public_key_2='JERUEHtcve...';
      
  2. Aktualisieren Sie den Code, um eine Verbindung zu Snowflake herzustellen. Geben Sie den neuen privaten Schlüssel an.

    Snowflake überprüft den korrekten aktiven öffentlichen Schlüssel für die Authentifizierung basierend auf dem privaten Schlüssel, der mit Ihren Verbindungsinformationen übermittelt wurde.

  3. Entfernen Sie den alten öffentlichen Schlüssel aus dem Benutzerprofil. Beispiel:

    alter user jsmith unset rsa_public_key;
    

Gewähren von Zugriffsrechten

Die Verwendung von Snowpipe erfordert eine Rolle mit den folgenden Berechtigungen:

Objekt

Berechtigung

Anmerkungen

Benannte Pipe

OWNERSHIP

Benannter Stagingbereich

USAGE (externer Stagingbereich), READ (interner Stagingbereich)

Benanntes Dateiformat

USAGE

Optional; nur erforderlich, wenn entweder der Stagingbereich (siehe Schritt 1: Stagingbereich erstellen (falls erforderlich)) oder die Pipe (siehe Schritt 2: Pipe erstellen) auf ein benanntes Dateiformat verweist.

Zieldatenbank

USAGE

Zielschema

USAGE

Zieltabelle

INSERT , SELECT

Verwenden Sie den Befehl GRANT <Berechtigungen> … TO ROLE, um der Rolle diese Berechtigungen zu erteilen.

Bemerkung

Nur Sicherheitsadministratoren (d. h. Benutzer mit der Rolle SECURITYADMIN oder höher) oder mit einer anderen Rolle, die sowohl die Berechtigung CREATE ROLE für das Konto als auch die globale Berechtigung MANAGE GRANTS besitzt, können Rollen erstellen und Berechtigungen erteilen.

Erstellen Sie beispielsweise eine Rolle mit dem Namen snowpipe1, die auf mydb.myschema-Datenbankobjekte sowie auf eine Pipe mit dem Namen mypipe zugreifen kann. Weisen Sie die Rolle einem Benutzer zu.

 -- Create a role to contain the Snowpipe privileges
use role securityadmin;

create or replace role snowpipe1;

-- Grant the required privileges on the database objects
grant usage on database mydb to role snowpipe1;

grant usage on schema mydb.myschema to role snowpipe1;

grant insert, select on mydb.myschema.mytable to role snowpipe1;

grant usage, read on stage mydb.myschema.mystage to role snowpipe1;

-- Grant the OWNERSHIP privilege on the pipe object
grant ownership on pipe mydb.myschema.mypipe to role snowpipe1;

-- Grant the role to a user
grant role snowpipe1 to user jsmith;

-- Set the role as the default role for the user
alter user jsmith set default_role = snowpipe1;

Nächstes Thema: Unter Aufrufen von Snowpipe-REST-Endpunkten zum Laden von Daten erfahren Sie, wie Sie die öffentlichen REST-Endpunkte zum Laden von Daten und zum Abrufen von Berichten über den Ladeverlauf aufrufen.