Snowpipe-REST-API¶

Endpunkt: insertFiles¶

Informiert Snowflake über die Dateien, die in eine Tabelle aufgenommen werden sollen. Eine erfolgreiche Antwort von diesem Endpunkt bedeutet, dass Snowflake die Liste der Dateien aufgezeichnet hat, die der Tabelle hinzugefügt werden sollen. Das bedeutet nicht unbedingt, dass die Dateien aufgenommen wurden. Weitere Informationen finden Sie in den folgenden Antwortcodes.

In den meisten Fällen fügt Snowflake innerhalb weniger Minuten neue Daten in die Zieltabelle ein.

Methode: POST

POST URL:

https://{account}.snowflakecomputing.com/v1/data/pipes/{pipeName}/insertFiles?requestId={requestId}

URL-Parameter:

• account (Erforderlich): Kontobezeichner für Ihr Snowflake Konto.

• pipeName (Erforderlich): Vollständig qualifizierter Pipename mit Beachtung der Groß- und Kleinschreibung. Zum Beispiel myDatabase.mySchema.myPipe.

• requestId (Optional): Zeichenfolge, die verwendet wird, um Anfragen durch das System zu verfolgen. Wir empfehlen, bei jeder Anfrage eine zufällige Zeichenfolge anzugeben, z. B. eine UUID. Diese sollte wie folgt an die URL angehängt werden: ?requestId=<your_uuid>.

Header der Anfrage

• Content-Type::

  • text/plain: Für eine reine Textliste von Dateipfaden und Dateinamen, eine pro Zeile. Der Größenparameter ist in diesem Format nicht zulässig.

  • application/json: Für ein JSON-Objekt, das eine Liste von Dateien mit optionalen Größenangaben enthält.

• Authorization: BEARER <jwt_token>

Body der Anfrage (für Content-Type „application/json“)

Der Body der Anfrage muss ein JSON-Objekt mit einem einzigen Schlüssel namens „files“ sein. Der mit diesem Schlüssel verknüpfte Wert ist ein Array von JSON-Objekten, wobei jedes Objekt eine aufzunehmende Datei darstellt.

{
  "files":[
    {
      "path":"filePath/file1.csv",
      "size":100
    },
    {
      "path":"filePath/file2.csv",
      "size":100
    }
   ]
}

Jedes Element im Array „files“ ist ein JSON-Objekt mit den folgenden Attributen:

• path (Erforderlich): Der Pfad und Dateiname der Stagingdatei. Wenn Sie unsere empfohlenen Best Practices befolgen und Ihre Daten im Stagingbereich mit logischen, granularen Pfaden partitionieren, die Pfadwerte der Nutzlast die vollständigen Pfade zu den Stagingdateien beinhalten.

• size (Optional, aber für eine bessere Leistung empfohlen): Die Größe der Datei in Bytes.

Body der Anfrage (für Content-Type „text/plain“)

Der Body der Anfrage sollte eine reine Textliste von Dateipfaden und Dateinamen sein, mit einem Eintrag pro Zeile.

filePath/file_a.csv
another/path/file_b.json
yet/another/file_c.txt

Body der Antwort

Antwortcodes:

• 200 – Erfolgreich. Dateien, die der Warteschlange der aufzunehmenden Dateien hinzugefügt wurden.

• 400 – Fehlgeschlagen. Ungültige Anforderung aufgrund eines ungültigen Formats oder einer Überschreitung des Limits.

• 404 – Fehlgeschlagen. pipeName nicht erkannt.

  Dieser Fehlercode kann auch zurückgegeben werden, wenn die beim Aufruf des Endpunkts verwendete Rolle nicht über ausreichende Berechtigungen verfügt. Weitere Informationen dazu finden Sie unter Erteilen von Zugriffsrechten.

• 429 – Fehlgeschlagen. Limit für die Anforderungsrate überschritten.

• 500 – Fehlgeschlagen. Interner Fehler aufgetreten.

Antwort-Nutzlast:

Bei einer erfolgreichen API-Anforderung (d. h. Code 200) enthält die Antwortnutzlast die Elemente requestId und status im JSON-Format. Wenn ein Fehler auftritt, kann die Antwortnutzlast Details zum Fehler enthalten.

{
  "requestId": "your_request_uuid",
  "status": "success"
}

Copy

Wenn die Anweisung COPY INTO <Tabelle> in der Pipedefinition die Kopieroption PATTERN enthält, listet das Attribut unmatchedPatternFiles alle im Header übermittelten Dateien auf, die nicht mit dem regulären Ausdruck übereinstimmen und daher übersprungen wurden.

{
  "requestId": "your_request_uuid",
  "status": "success",
  "unmatchedPatternFiles": ["some_file.txt", "another_file.dat"]
}

Copy

Endpunkt: insertReport¶

Ruft einen Bericht über Dateien ab, die über insertFiles eingereicht wurden und deren Inhalt kürzlich in eine Tabelle aufgenommen wurde. Beachten Sie, dass dies bei großen Dateien nur ein Teil der Datei sein kann.

Beachten Sie die folgenden Einschränkungen für diesen Endpunkt:

• Die 10.000 jüngsten Ereignisse werden beibehalten.

• Die Ereignisse werden für maximal 10 Minuten gespeichert.

Ein Ereignis tritt ein, wenn Daten aus einer über insertFiles übermittelten Datei in die Tabelle übertragen wurden und für Abfragen zur Verfügung stehen. Der insertReport-Endpunkt kann wie der UNIX-Tail-Befehl angesehen werden. Durch wiederholtes Aufrufen dieses Befehls ist es möglich, den vollständigen Verlauf der Ereignisse in einer Pipe über einen Zeitraum hinweg anzuzeigen. Beachten Sie, dass der Befehl oft genug aufgerufen werden muss, um Ereignisse nicht zu verpassen. Wie oft, hängt davon ab, in welcher Häufigkeit Dateien an insertFiles gesendet werden.

Methode: GET

GET URL:

https://<Kontobezeichner>.snowflakecomputing.com/v1/data/pipes/<Pipename>/insertReport?requestId=<Anforderungs-ID>&beginMark=<Startmarke>

URL-Parameter:

• account_identifier (Erforderlich): Ihr eindeutiger Kontobezeichner für das Snowflake-Konto. Das bevorzugte Format ist organization_name-account_name. Für alternative Formate (Kontosuche mit Region und Cloud-Plattform), siehe Format 1 (bevorzugt): Kontoname in Ihrer Organisation.

• pipeName (Erforderlich): Der vollständig qualifizierte Name der Snowpipe, wobei Groß- und Kleinschreibung zu beachten sind. Zum Beispiel myDatabase.mySchema.myPipe.

• requestId (Optional): Eine Zeichenfolge, die Sie angeben können, um diese spezielle Anfrage über das Snowflake-System zu verfolgen. Die Verwendung einer zufälligen Zeichenfolge wie UUID wird zur einfacheren Fehlersuche und Überwachung dringend empfohlen. Fügen Sie diese an die URL an, etwa so: ?requestId=<your_uuid>.

• beginMark (Optional): Ein Markerwert, der im Feld nextBeginMark einer früheren Antwort von insertReport zurückgegeben wurde. Durch Einfügen dieses Markers werden nachfolgende Aufrufe optimiert, da die Anzahl der zurückgegebenen doppelten Ereignisse potenziell reduziert wird. Hinweis: Obwohl beginMark als Hinweis gedacht ist, um Duplikate zu vermeiden, kann es dennoch gelegentlich zu Wiederholungen von Ereignissen kommen. Wenn beginMark nicht angegeben wird, zeigt der Bericht den Datenaufnahmeverlauf der letzten 10 Minuten. Hängen Sie dies an die URL an, etwa so: ?beginMark=<previous_nextBeginMark>.

Header der Anfrage:

• Accept: Gibt das gewünschte Antwortformat an. Akzeptierte Werte sind text/plain oder application/json.

• Authorization: Ihr Snowflake Authentifizierungs-Token. Verwenden Sie das Format BEARER <jwt_token>.

Body der Anfrage:

Dieser Endpunkt akzeptiert keinen Anfrage-Body für GET-Anfragen. Die erforderlichen Parameter werden in den URL und den Header bereitgestellt.

Body der Antwort:

Antwortcodes:

• 200 – Erfolgreich. Bericht wurde zurückgegeben.

• 400 – Fehlgeschlagen. Ungültige Anforderung aufgrund eines ungültigen Formats oder einer Überschreitung des Limits.

• 404 – Fehlgeschlagen. pipeName nicht erkannt.

  Dieser Fehlercode kann auch zurückgegeben werden, wenn die beim Aufruf des Endpunkts verwendete Rolle nicht über ausreichende Berechtigungen verfügt. Weitere Informationen dazu finden Sie unter Erteilen von Zugriffsrechten.

• 429 – Fehlgeschlagen. Limit für die Anforderungsrate überschritten.

• 500 – Fehlgeschlagen. Interner Fehler aufgetreten.

Antwort-Nutzlast:

Eine Erfolgsmeldung (200) enthält Informationen zu Dateien, die kürzlich der Tabelle hinzugefügt wurden. Beachten Sie, dass dieser Bericht nur einen Teil einer großen Datei darstellen kann.

Beispiel:

{
  "pipe": "TESTDB.TESTSCHEMA.pipe2",
  "completeResult": true,
  "nextBeginMark": "1_39",
  "files": [
    {
      "path": "data2859002086815673867.csv",
      "stageLocation": "s3://mybucket/",
      "fileSize": 57,
      "timeReceived": "2017-06-21T04:47:41.453Z",
      "lastInsertTime": "2017-06-21T04:48:28.575Z",
      "rowsInserted": 1,
      "rowsParsed": 1,
      "errorsSeen": 0,
      "errorLimit": 1,
      "complete": true,
      "status": "LOADED"
    }
  ]
}

Copy

Antwortfelder:

Feld	Typ	Beschreibung
pipe	Zeichenfolge	Der vollqualifizierte Name der Pipe.
completeResult	Boolesch	false, wenn ein Ereignis zwischen dem gelieferten beginMark und dem ersten Ereignis in diesem Berichtsverlauf verpasst wurde. Ansonsten true.
nextBeginMark	Zeichenfolge	beginMark wird bei der nächsten Anforderung verwendet, um doppelte Datensätze zu vermeiden. Beachten Sie, dass dieser Wert ein Hinweis ist. Duplikate können noch gelegentlich auftreten.
files	Array	Ein Array von JSON-Objekten, ein Objekt für jede Datei, die Teil der Verlaufsantwort ist.
path	Zeichenfolge	Der Dateipfad in Bezug auf den Stagingbereich.
stageLocation	Zeichenfolge	Entweder die Stagingbereichs-ID (interner Stagingbereich) oder der in der Pipe definierte S3-Bucket (externer Stagingbereich).
fileSize	Lang	Dateigröße, in Bytes.
timeReceived	Zeichenfolge	Zeit, zu der diese Datei zur Verarbeitung empfangen wurde. Das Format ist ISO-8601 in der Zeitzone UTC.
lastInsertTime	Zeichenfolge	Zeit, zu der die Daten aus dieser Datei zuletzt in die Tabelle eingefügt wurden. Das Format ist ISO-8601 in der Zeitzone UTC.
rowsInserted	Lang	Anzahl der Zeilen, die aus der Datei in die Zieltabelle eingefügt wurden.
rowsParsed	Lang	Anzahl der Zeilen, die von der Datei geparst wurden. Fehlerhafte Zeilen können übersprungen werden.
errorsSeen	Ganzzahl (Integer)	Anzahl der in der Datei angezeigten Fehler
errorLimit	Ganzzahl (Integer)	Anzahl der Fehler, die in der Datei erlaubt sind, bevor sie als fehlgeschlagen gilt (basierend auf der ON_ERROR-Kopieroption).
firstError [1]	Zeichenfolge	Fehlermeldung für den ersten Fehler, der in dieser Datei aufgetreten ist.
firstErrorLineNum [1]	Lang	Zeilennummer des ersten Fehlers.
firstErrorCharacterPos [1]	Lang	Zeichenposition des ersten Fehlers.
firstErrorColumnName [1]	Zeichenfolge	Name der Spalte, in der der erste Fehler aufgetreten ist.
systemError [1]	Zeichenfolge	Allgemeiner Fehler, der beschreibt, warum die Datei nicht verarbeitet wurde.
complete	Boolesch	Gibt an, ob die Datei vollständig erfolgreich verarbeitet wurde.
status	Zeichenfolge	Ladestatus für die Datei:
		LOAD_IN_PROGRESS: Ein Teil der Datei wurde in die Tabelle geladen, aber der Ladevorgang ist noch nicht abgeschlossen.
		LOADED: Die gesamte Datei wurde in die Tabelle geladen.
		LOAD_FAILED: Das Laden der Datei ist fehlgeschlagen.
		PARTIALLY_LOADED: Einige Zeilen aus dieser Datei wurden erfolgreich geladen, andere wurden aufgrund von Fehlern nicht geladen. Die Verarbeitung dieser Datei ist abgeschlossen.

_{[1] Werte werden für diese Felder nur dann geliefert, wenn Dateien Fehler enthalten.}

Endpunkt: loadHistoryScan¶

Ruft einen Bericht über aufgenommene Dateien ab, deren Inhalt der Tabelle hinzugefügt wurde. Beachten Sie, dass dies bei großen Dateien nur ein Teil der Datei sein kann. Dieser Endpunkt unterscheidet sich von insertReport dadurch, dass er den Verlauf zwischen zwei Zeitpunkten anzeigt. Maximal 10.000 Elemente können zurückgegeben werden. Es können jedoch mehrere Aufrufe ausgeführt werden, um den gewünschten Zeitbereich abzudecken.

Für eine umfassendere Ansicht ohne diese Limits bietet Snowflake die Information Schema-Tabellenfunktion COPY_HISTORY, die den Ladeverlauf einer Pipe oder einer Tabelle zurückgibt.

Methode: GET

GET URL:

https://{account}.snowflakecomputing.com/v1/data/pipes/{pipeName}/loadHistoryScan?startTimeInclusive=<Startzeit>&endTimeExclusive=<Endzeit>&requestId=<Anforderungs-ID>

URL-Parameter:

• account (Erforderlich): Ihr eindeutiger Kontobezeichner für das Snowflake-Konto.

• pipeName (Erforderlich): Der vollständig qualifizierte Name der Snowpipe, wobei Groß- und Kleinschreibung zu beachten sind. Beispiel: myDatabase.mySchema.myPipe.

• startTimeInclusive (Erforderlich): Der Beginn des Zeitbereichs für den Abruf von Ladeverlaufsdaten, angegeben als Zeitstempel im ISO-8601-Format (zum Beispiel 2023-10-26T10:00:00Z). Dieser Zeitstempel markiert die inklusive Untergrenze der Abfrage.

• endTimeExclusive (Optional): Das Ende des Zeitbereichs für den Abruf von Ladeverlaufsdaten, angegeben als Zeitstempel im ISO-8601-Format (zum Beispiel 2023-10-26T10:15:00Z). Dieser Zeitstempel markiert die exklusive Obergrenze der Abfrage. Wenn dieser Parameter weggelassen wird, wird der aktuelle Server-Zeitstempel (CURRENT_TIMESTAMP()) als Ende des Zeitbereichs verwendet.

• requestId (Optional): Eine Zeichenfolge, die Sie angeben können, um diese spezielle Anfrage über das Snowflake-System zu verfolgen. Wir empfehlen die Verwendung einer zufälligen Zeichenfolge wie UUID, um die Fehlersuche und Überwachung zu erleichtern. Fügen Sie diese an die URL an, etwa so: ?requestId=<your_uuid>.

Header der Anfrage:

• Accept: Gibt das gewünschte Antwortformat an. Akzeptierte Werte sind text/plain oder application/json.

• Authorization: Ihr Snowflake Authentifizierungs-Token. Verwenden Sie das Format BEARER <jwt_token>.

Body der Anfrage:

Dieser Endpunkt akzeptiert keinen Anfrage-Body für GET-Anfragen. Alle erforderlichen Parameter sind in den URL und den Header enthalten.

Body der Antwort:

Antwortcodes:

• 200 – Erfolgreich. Die Scanergebnisse des Ladeverlaufs werden zurückgegeben.

• 400 – Fehlgeschlagen. Ungültige Anforderung aufgrund eines ungültigen Formats oder einer Überschreitung des Limits.

• 404 – Fehlgeschlagen. pipeName nicht erkannt.

• 429 – Fehlgeschlagen. Limit für die Anforderungsrate überschritten.

• 500 – Fehlgeschlagen. Interner Fehler aufgetreten.

Antwort-Nutzlast:

Eine Erfolgsmeldung (200) enthält Informationen zu Dateien, die kürzlich der Tabelle hinzugefügt wurden. Beachten Sie, dass dieser Bericht möglicherweise nur einen Teil einer großen Datei darstellt.

Beispiel:

{
  "pipe": "TESTDB.TESTSCHEMA.pipe2",
  "completeResult": true,
  "startTimeInclusive": "2017-08-25T18:42:31.081Z",
  "endTimeExclusive":"2017-08-25T22:43:45.552Z",
  "rangeStartTime":"2017-08-25T22:43:45.383Z",
  "rangeEndTime":"2017-08-25T22:43:45.383Z",
  "files": [
    {
      "path": "data2859002086815673867.csv",
      "stageLocation": "s3://mystage/",
      "fileSize": 57,
      "timeReceived": "2017-08-25T22:43:45.383Z",
      "lastInsertTime": "2017-08-25T22:43:45.383Z",
      "rowsInserted": 1,
      "rowsParsed": 1,
      "errorsSeen": 0,
      "errorLimit": 1,
      "complete": true,
      "status": "LOADED"
    }
  ]
}

Copy

Antwortfelder:

Feld	Typ	Beschreibung
pipe	Zeichenfolge	Vollqualifizierter Name der Pipe.
completeResult	Boolesch	false, wenn der Bericht unvollständig ist (d. h. die Anzahl der Einträge im angegebenen Zeitbereich überschreitet das Eingabelimit von 10.000). Wenn false, kann der Benutzer den aktuellen rangeEndTime-Wert als startTimeInclusive-Wert für die nächste Anforderung angeben, um zur nächsten Gruppe von Einträgen überzugehen.
startTimeInclusive	Zeichenfolge	Startzeitstempel (im Format ISO-8601), der in der Anforderung angegeben ist.
endTimeExclusive	Zeichenfolge	Endzeitstempel (im Format ISO-8601), der in der Anforderung angegeben ist.
rangeStartTime	Zeichenfolge	Zeitstempel (im Format ISO-8601) des ältesten Eintrags in den in der Antwort enthaltenen Dateien.
rangeEndTime	Zeichenfolge	Zeitstempel (im Format ISO-8601) des letzten Eintrags in den in der Antwort enthaltenen Dateien.
files	Array	Ein Array von JSON-Objekten, ein Objekt für jede Datei, die Teil der Verlaufsantwort ist. Innerhalb des Arrays sind die Antwortfelder die gleichen wie die in der insertReport-Antwort zurückgegebenen.