Snowpipe-REST-API

Sie können mit einer Pipe interagieren, indem Sie Aufrufe von REST-Endpunkten tätigen. Dieses Thema beschreibt die Snowpipe-REST-API zur Definition der Liste der Dateien, die aufgenommen und abgerufen werden sollen, sowie Berichte über den Ladeverlauf.

Snowflake bietet auch Java- und Python-APIs an, die die Arbeit mit der Snowpipe-REST-API vereinfachen.

Unter diesem Thema:

Datendatei-Erfassung

Die Snowpipe-API bietet einen REST-Endpunkt zum Definieren der Liste der aufzunehmenden Dateien.

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.

Berichte zum Ladeverlauf

Die Snowpipe-API bietet REST-Endpunkte zum Abrufen von Ladeberichten.

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.

Wichtig

Dieser Endpunkt hat ein Limit für die Anforderungsrate, um übermäßige Aufrufe zu vermeiden. Um das Überschreiten des Limits (Fehlercode 429) zu vermeiden, empfehlen wir, sich stärker auf insertReport als auf loadHistoryScan zu verlassen. Geben Sie beim Aufruf von loadHistoryScan den engsten Zeitbereich an, der eine Reihe von Datenladungen enthält. Zum Beispiel würde es gut funktionieren, wenn alle 8 Minuten die letzten 10 Minuten des Verlaufs gelesen werden. Der Versuch, minütlich die letzten 24 Stunden des Verlaufs zu lesen, führt zu einem 429-Fehler, was bedeutet, dass ein Limit für die Anforderungsrate erreicht wurde. Die Limits für die Anforderungsrate sind so ausgelegt, dass jeder Verlaufsdatensatz ein paar Mal gelesen werden kann.

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.