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.

method

POST

post url

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

post body

Ein JSON-Objekt mit den folgenden Attributen:

Attribut	Erforderlich	Beschreibung
account	Ja	Kontobezeichner für Ihr Snowflake-Konto.
pipeName	Ja	Vollqualifizierter Pipename mit Unterscheidung von Groß-/Kleinschreibung. Zum Beispiel myDatabase.mySchema.myPipe.
requestId	Nein	Zeichenfolge, die verwendet wird, um Anfragen durch das System zu verfolgen. Wir empfehlen, bei jeder Anforderung eine zufällige Zeichenfolge anzugeben, z. B. eine UUID.

content-type

text/plain

application/json

header fields

Akzeptiert: text/plain oder application/json

Autorisierung: BEARER-<JWT-Token>

• Für text/plain ist der Inhalt die Liste der Pfade und Dateinamen, ein Name pro Zeile. Der Parameter size ist nicht zulässig.

• Für application/json ist der Inhalt die Liste der Pfade, Dateinamen und Dateigrößen (optional, aber für bessere Leistung empfohlen). Eine Beispiel-Nutzlast sieht folgendermaßen aus:

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

  Copy

Beachten Sie, dass, 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.

Bemerkung

• Der Post kann maximal 5.000 Dateien enthalten.

• Jeder angegebene Dateipfad muss <= 1.024 Bytes lang sein bei Serialisierung als UTF-8.

response body

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.

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.

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.

method

GET

get url

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

header fields

Akzeptieren: text/plain oder application/json

Autorisierung: BEARER-<JWT-Token>

get body

Ein JSON-Objekt mit den folgenden Attributen:

Attribut	Erforderlich	Beschreibung
account_identifier	Ja	Eindeutiger Bezeichner Ihres Snowflake-Kontos. Das bevorzugte Format für den Kontobezeichner ist wie folgt: organization_name-account_name Namen Ihrer Snowflake-Organisation und Ihres Snowflake-Kontos. Weitere Details dazu finden Sie unter Format 1 (bevorzugt): Kontoname in Ihrer Organisation. Geben Sie alternativ Ihren Konto-Locator an, ggf. zusammen mit der Region und der Cloudplattform, auf der das Konto gehostet wird. Weitere Details dazu finden Sie unter Format 2 (älter): Konto-Locator in einer Region.
pipeName	Ja	Vollqualifizierter Pipename mit Unterscheidung von Groß-/Kleinschreibung. Zum Beispiel myDatabase.mySchema.myPipe.
requestId	Nein	Zeichenfolge, die verwendet wird, um Anfragen durch das System zu verfolgen. Wir empfehlen, bei jeder Anforderung eine zufällige Zeichenfolge anzugeben, z. B. eine UUID.
beginMark	Ja	Marker, der von einem vorherigen Aufruf von insertReport zurückgegeben wurde und der verwendet werden kann, um die Anzahl der wiederholten Ereignisse zu reduzieren, die beim wiederholten Aufruf von insertReport angezeigt werden. Beachten Sie, dass dies ein Hinweis ist und wiederholte Ereignisse gelegentlich noch zurückgegeben werden können.

response body

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.

method

GET

get url

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

header fields

Akzeptieren: text/plain oder application/json

Autorisierung: BEARER-<JWT-Token>

get body

Ein JSON-Objekt mit den folgenden Attributen:

Attribut	Erforderlich	Beschreibung
account	Ja	Kontobezeichner für Ihr Snowflake-Konto.
pipeName	Ja	Vollqualifizierter Pipename mit Unterscheidung von Groß-/Kleinschreibung. Zum Beispiel myDatabase.mySchema.myPipe.
startTimeInclusive	Ja	Zeitstempel im Format ISO-8601. Beginn des Zeitbereichs zum Abrufen von Ladeverlaufsdaten.
endTimeExclusive	Nein	Zeitstempel im Format ISO-8601. Ende des Zeitraums zum Abrufen von Ladeverlaufsdaten. Wenn weggelassen, wird CURRENT_TIMESTAMP() als Ende des Zeitraums verwendet.
requestId	Nein	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).

response body

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.