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:

    Sonatype (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.6 oder höher erfordert.

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

pip install snowflake-ingest
Copy

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

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 von Schlüsselpaar-Authentifizierung und Schlüsselrotation

Die Snowpipe-REST-Endpunkte erfordern eine Schlüsselpaar-Authentifizierung mit JSON Web Token (JWT). JWTs werden mit einem Public/Private-Schlüsselpaar mit RSA-Verschlüsselung signiert.

Als Teil dieses Prozesses müssen Sie Folgendes tun:

  1. Generieren Sie ein öffentlich-privates Schlüsselpaar. Der generierte private Schlüssel muss sich in einer Datei befinden (z. B. mit dem Namen rsa_key.p8).

  2. Weisen Sie den öffentlichen Schlüssel Ihrem Snowflake-Benutzer zu. Nachdem Sie dem Benutzer den Schlüssel zugewiesen haben, führen Sie den Befehl DESCRIBE USER aus. In der Ausgabe muss die Eigenschaft RSA_PUBLIC_KEY_FP auf den Fingerabdruck des dem Benutzer zugewiesenen öffentlichen Schlüssels gesetzt sein.

Eine Anleitung zum Generieren des Schlüsselpaars und zum Zuweisen eines Schlüssels an einen Benutzer finden Sie unter Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.

Sprachspezifische Beispiele für das Erstellen eines Fingerabdrucks und das Generieren eines JWT-Tokens finden Sie unter:

Erteilen von Zugriffsrechten

Zum Aufrufen der Snowpipe-REST-Endpunkte ist eine Rolle mit den folgenden minimalen Berechtigungen erforderlich:

Objekt

Berechtigung

Anmerkungen

Benannte Pipe

OPERATE (insertFiles Endpunkt), MONITOR (insertReport, loadHistoryScan Endpunkte)

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>, 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 zum Beispiel eine Rolle mit dem Namen snowpipe1, die Daten über eine Pipe mit dem Namen mypipe laden kann. Die Pipe verweist auf einen externen Stagingbereich:

 -- Create a role for the Snowpipe privileges.
use role securityadmin;

create or replace role snowpipe1;

-- Grant the USAGE privilege on the database and schema that contain the pipe object.
grant usage on database mydb to role snowpipe1;
grant usage on schema mydb.myschema to role snowpipe1;

-- Grant the INSERT and SELECT privileges on the target table.
grant insert, select on mydb.myschema.mytable to role snowpipe1;

-- Grant the USAGE privilege on the external stage.
grant usage on stage mydb.myschema.mystage to role snowpipe1;

-- Grant the OPERATE and MONITOR privileges on the pipe object.
grant operate, monitor 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;
Copy

Schritt 4: Datendateien in Stagingbereich bereitstellen

Kopieren Sie Datendateien in den internen oder externen Stagingbereich, den Sie zum Laden von Dateien mit Snowpipe erstellt haben.

  • Kopieren Sie Dateien mit den vom Cloudspeicherdienst bereitgestellten Tools in einen externen Stagingbereich.

  • Kopieren Sie Dateien mit dem Befehl PUT in einen internen Stagingbereich.

    Bemerkung

    Wenn Ihr Snowflake-Konto bei Amazon Web Services gehostet wird, empfehlen wir immer die Verwendung der Syntax PUT … OVERWRITE = TRUE.

    Amazon S3 bietet Lesen-nach-Schreiben-Konsistenz für neue Objekte, die in einem Bucket erstellt werden. Wenn für ein Objekt jedoch eine HEAD- oder GET-Anforderung gesendet wird, bevor das Objekt erstellt wurde, bietet S3 Letztliche Konsistenz für das Objekt. Das bedeutet, dass eine sofortige Anforderung eines neuen Objekts nach dessen Erstellung eine file not found-Ausnahme zurückgeben könnte. Durch das Festlegen des Parameters OVERWRITE = TRUE wird die Initiierung einer HEAD-Anforderung vor dem Erstellen des Objekts im S3-Bucket verhindert.

    Weitere Informationen zum S3-Konsistenzmodell finden Sie in der S3-Dokumentation.

Nächstes Thema: Unter Übersicht zu 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.

Sprache: Deutsch