Snowpipe Streaming API REST-Endpunkte¶

Bemerkung

Wir empfehlen, mit dem Snowpipe Streaming-SDK über die REST API zu beginnen, um von der verbesserten Leistung und dem einfacheren Einstieg zu profitieren.

Die Snowpipe Streaming-REST API ist für einfache Workloads konzipiert und bietet eine flexible Möglichkeit, externe Anwendungen zu integrieren, ohne das Snowpipe Streaming-SDK zu verwenden.

Das folgende Diagramm bietet einen Überblick darüber, wie Daten vom Client zum Snowflake Server fließen. Die wichtigen API-Endpunkte im Prozess werden ausführlich beschrieben.

Header der Anforderung¶

Die folgenden Anfrage-Header gelten für alle Endpunkte von Snowpipe Streaming REST API:

Header	Beschreibung
`Authorization`	Authentifizierungstoken
`X-Snowflake-Authorization-Token-Type` (optional)	JWT/OAuth

Bemerkung

Die maximal zulässige Größe für eine einzelne Anforderungsnutzlast beträgt 16 MB. Wenn Ihre Daten größer sind, müssen Sie diese in mehrere Anforderungen aufteilen.

Hostname abrufen¶

Get Hostname gibt den Hostnamen zurück, der für die Interaktion mit Snowpipe Streaming REST API verwendet wird. Jedes Konto hat einen eindeutigen Hostnamen.

GET /v2/streaming/hostname

Antwort:

{
  "hostname": "string"
}

Copy

Beschreibung der Antwortfelder:

Feld	Typ	Beschreibung
Hostname	String	Der Hostname des Kontos.

Auf Exchange beschränktes Token¶

Exchange Scoped Token gibt ein Sicherheitstoken zurück, das nur für den Zugriff auf den API-bezogenen Service von Snowpipe Streaming verwendet werden kann. Dies bietet Sicherheitsschutz für den Kunden.

POST /oauth/token

Anfrage:

Attribut	Erforderlich	Komponente	Beschreibung
content_type	Ja	Header	„application/x-www-form-urlencoded“
grant_type	Ja	Nutzlast	„urn:ietf:params:oauth:grant-type:jwt-bearer“
scope	Ja	Nutzlast	Der Hostname des Kontos.

Antwort:

{
  "token": "string"
}

Copy

Beschreibung der Antwortfelder:

Feld	Typ	Beschreibung
Token	String	Das bereichsbezogene Token.

Offener Kanal¶

Die Operation Open Channel erstellt oder öffnet einen neuen Kanal für eine Pipe oder Tabelle. Wenn der Kanal bereits existiert, stößt Snowflake den Client-Sequencer des Kanals an und gibt das zuletzt übertragene Offset-Token zurück.

PUT /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}

Anfrage:

Attribut	Erforderlich	Komponente	Beschreibung
databaseName	Ja	URI	Datenbankname, Groß-/Kleinschreibung wird nicht berücksichtigt.
schemaName	Ja	URI	Schemaname, Groß-/Kleinschreibung wird nicht berücksichtigt.
pipeName	Ja	URI	Pipename, Groß-/Kleinschreibung wird nicht berücksichtigt.
channelName	Ja	URI	Der Name des Kanals, den Sie erstellen oder erneut öffnen; Groß-/Kleinschreibung wird nicht berücksichtigt.
offset_token	Nein	Nutzlast	Zeichenfolge, die verwendet wird, um ein Offset-Token beim Öffnen eines Kanals zu setzen.
requestId	Nein	Abfrageparameter	Ein universell eindeutiger Bezeichner (UUID), mit dem Anfragen durch das System verfolgt werden können.

Antwort:

{
  "next_continuation_token": "string",
  "channel_status": {
    "database_name": "string",
    "schema_name": "string",
    "pipe_name": "string",
    "channel_name": "string",
    "channel_status_code": "string",
    "last_committed_offset_token": "string",
    "created_on_ms": "long",
    "rows_inserted": "int",
    "rows_parsed": "int",
    "rows_error_count": "int",
    "last_error_offset_upper_bound": "string",
    "last_error_message": "string",
    "last_error_timestamp": "timestamp_utc",
    "snowflake_avg_processing_latency_ms": "int"
  }
}

Copy

Beschreibung der Antwortfelder:

Feld	Typ	Beschreibung
next_continuation_token	String	Ein von der API verwaltetes Token, das in der nachfolgenden Zeilenanforderung verwendet werden muss. Das Token verknüpft eine Reihe von Aufrufen, wodurch ein zusammenhängender Datenstream in der richtigen Reihenfolge sichergestellt wird und der Sitzungsstatus für eine genau einmalige Bereitstellung beibehalten wird.
channel_status	Objekt	Ein verschachteltes Objekt mit den folgenden Detailinformationen zu dem Kanal: database_name (Zeichenfolge): Der Name der Datenbank, in der sich die Pipe befindet. schema_name (Zeichenfolge): Der Name des Schemas, in dem sich die Pipe befindet. Pipe-Name (Zeichenfolge): Der Name der spezifischen Pipe, die verwendet wird. channel_name (Zeichenfolge): Der Name des Streaming-Kanals. channel_status_code (Zeichenfolge): Ein Code, der den aktuellen Status des Kanals angibt; Beispiel: „ACTIVE“. last_committed_offset_token (Zeichenfolge): Das Token, das für den letzten erfolgreich übertragenen Offset steht. created_on_ms (Long): Der Zeitstempel der Kanalerstellung in Millisekunden. rows_inserted (Int): Gesamtzahl der erfolgreich eingefügten Zeilen. rows_parsed (Int): Gesamtzahl der analysierten Zeilen. rows_error_count (Int): Gesamtzahl der Zeilen, bei denen ein Fehler aufgetreten ist. last_error_offset_upper_bound (Zeichenfolge): Ein Token, das die obere Grenze des Offsets angibt, bei dem der letzte Fehler aufgetreten ist. last_error_message (Zeichenfolge): Die Nachricht des zuletzt aufgetretenen Fehlers. last_error_timestamp (Long): Der Zeitstempel des letzten Fehlers in Millisekunden. snowflake_avg_processing_latency_ms (Int): Die durchschnittliche Verarbeitungslatenz von Snowflake in Millisekunden.

Feld

Typ

Beschreibung

next_continuation_token

String

Ein von der API verwaltetes Token, das in der nachfolgenden Zeilenanforderung verwendet werden muss. Das Token verknüpft eine Reihe von Aufrufen, wodurch ein zusammenhängender Datenstream in der richtigen Reihenfolge sichergestellt wird und der Sitzungsstatus für eine genau einmalige Bereitstellung beibehalten wird.

channel_status

Objekt

Ein verschachteltes Objekt mit den folgenden Detailinformationen zu dem Kanal:

database_name (Zeichenfolge): Der Name der Datenbank, in der sich die Pipe befindet.
schema_name (Zeichenfolge): Der Name des Schemas, in dem sich die Pipe befindet.
Pipe-Name (Zeichenfolge): Der Name der spezifischen Pipe, die verwendet wird.
channel_name (Zeichenfolge): Der Name des Streaming-Kanals.
channel_status_code (Zeichenfolge): Ein Code, der den aktuellen Status des Kanals angibt; Beispiel: „ACTIVE“.
last_committed_offset_token (Zeichenfolge): Das Token, das für den letzten erfolgreich übertragenen Offset steht.
created_on_ms (Long): Der Zeitstempel der Kanalerstellung in Millisekunden.
rows_inserted (Int): Gesamtzahl der erfolgreich eingefügten Zeilen.
rows_parsed (Int): Gesamtzahl der analysierten Zeilen.
rows_error_count (Int): Gesamtzahl der Zeilen, bei denen ein Fehler aufgetreten ist.
last_error_offset_upper_bound (Zeichenfolge): Ein Token, das die obere Grenze des Offsets angibt, bei dem der letzte Fehler aufgetreten ist.
last_error_message (Zeichenfolge): Die Nachricht des zuletzt aufgetretenen Fehlers.
last_error_timestamp (Long): Der Zeitstempel des letzten Fehlers in Millisekunden.
snowflake_avg_processing_latency_ms (Int): Die durchschnittliche Verarbeitungslatenz von Snowflake in Millisekunden.

Zeile(n) anhängen¶

Die Operation Append Rows fügt ein Batch von Zeilen in den angegebenen Kanal ein.

POST /v2/streaming/data/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}/rows

Anfrage:

Attribut	Erforderlich	Komponente	Beschreibung
databaseName	Ja	URI	Datenbankname, Groß-/Kleinschreibung wird nicht berücksichtigt.
schemaName	Ja	URI	Schemaname, Groß-/Kleinschreibung wird nicht berücksichtigt.
pipeName	Ja	URI	Pipe, Groß-/Kleinschreibung wird nicht berücksichtigt.
channelName	Ja	URI	Kanalname, Groß-/Kleinschreibung wird nicht berücksichtigt.
continuationToken	Ja	Abfrageparameter	Fortsetzungstoken von Snowflake, kapselt sowohl Client- als auch Zeilensequenzierer.
offsetToken	Nein	Abfrageparameter	Zeichenfolge, die verwendet wird, um ein Offset-Token pro Batch zu setzen.
rows	Ja	Nutzlast	Die eigentliche Datennutzlast, die in aufgenommen werden soll, im NDJSON-Format. Die maximal zulässige Größe für dieses Attribut ist 4 MB.
requestId	Nein	Abfrageparameter	Eine UUID, die verwendet wird, um Anfragen durch das System zu verfolgen.

Bemerkung

Der JSON-Text innerhalb der NDJSON-Nutzlast muss strikt dem RFC 8259-Standard entsprechen. Auf jeden JSON-Text muss ein Neue-Zeile-Zeichen \n (0x0A) folgen. Sie können auch einen Zeilenumbruch \r (0x0D) vor dem Neue-Zeile-Zeichen einfügen.

Antwort:

{
  "next_continuation_token": "string"
}

Copy

Beschreibung der Antwortfelder:

Feld	Typ	Beschreibung
next_continuation_token	string	Das nächste Fortsetzungs-Token von Snowflake, das sowohl Client- als auch Zeilen-Sequenzer einkapselt. Es sollte für das Einfügen des nächsten Batch verwendet werden.

Kanal löschen¶

Der Vorgang Drop Channel legt einen Kanal zusammen mit seinen Metadaten auf der Serverseite ab.

DELETE /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}

Anfrage:

Attribut	Erforderlich	Komponente	Beschreibung
databaseName	Ja	URI	Datenbankname, Groß-/Kleinschreibung wird nicht berücksichtigt
schemaName	Ja	URI	Schemaname, Groß-/Kleinschreibung wird nicht berücksichtigt
pipeOrTableName	Ja	URI	Pipe- oder Tabellenname, Groß-/Kleinschreibung wird nicht berücksichtigt
channelName	Ja	URI	Kanalname, Groß-/Kleinschreibung wird nicht berücksichtigt
requestId	Nein	Abfrageparameter	Eine UUID, mit der Sie Anfragen im System verfolgen können

Antwort:

Diese Operation gibt eine Nutzlast ohne spezifische erfolgreiche Antwort außer dem HTTP-Statuscode zurück.

Bulk-Kanalstatus abrufen¶

Die Operation Bulk Get Channel Status gibt den Status eines Kanals für einen bestimmten Client-Sequenzer zurück.

POST /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}:bulk-channel-status

Anfrage:

Attribut	Erforderlich	Komponente	Beschreibung
databaseName	Ja	URI	Datenbankname, Groß-/Kleinschreibung wird nicht berücksichtigt
schemaName	Ja	URI	Schemaname, Groß-/Kleinschreibung wird nicht berücksichtigt
pipeName	Ja	URI	Pipe-Name, Groß-/Kleinschreibung wird nicht berücksichtigt
channel_names	Ja	Nutzlast	Ein Array von String-Kanalnamen, für die der Kunde den Status abrufen möchte. Bei den Namen wird zwischen Groß- und Kleinschreibung unterschieden. Beispiel: `{"channel_names":["channel1", "channel2"]}`.

Antwort:

{
  "channel_statuses": {
    "channel1": {
      "channel_status_code": "String",
      "last_committed_offset_token": "String",
      "database_name": "String",
      "schema_name": "String",
      "pipe_name": "String",
      "channel_name": "String",
      "rows_inserted": "int",
      "rows_parsed": "int",
      "rows_errors": "int",
      "last_error_offset_upper_bound": "String",
      "last_error_message": "String",
      "last_error_timestamp": "timestamp_utc",
      "snowflake_avg_processing_latency_ms": "int"
    },
    "channel2": {
      "comment": "same structure as channel1"
    }
    "comment": "potentially other channels"
  }
}

Copy

Bemerkung

Wenn im Service kein angeforderter Kanal gefunden wird, hat die Antwortnutzlast keinen Eintrag für diesen Kanal im channel_statuses-Objekt.

Beschreibung von channel_statuses-Felder für jeden Kanal:

Feld	Typ	Beschreibung
channel_status_code	String	Zeigt den Status des Kanals an.
last_committed_offset_token	String	Letztes bestätigtes Offset-Token.
database_name	String	Der Name der Datenbank, zu der der Kanal gehört.
schema_name	String	Der Name des Schemas, zu dem der Kanal gehört.
Pipe-Name	String	Der Name der Pipe, zu der der Kanal gehört.
channel_name	String	Der Name des Kanals.
rows_inserted	int	Eine Zählung aller in diesen Kanal eingefügten Zeilen.
rows_parsed	int	Eine Zählung aller Zeilen, die geparst, aber nicht unbedingt in diesen Kanal eingefügt wurden.
rows_errors	int	Anzahl aller Zeilen, bei denen beim Einfügen in diesen Kanal ein Fehler auftrat und die daher abgelehnt wurden.
last_error_offset_upper_bound	String	Die obere Grenze für einen Datenaufnahmefehler. Der Fehler wird bei oder vor diesem bestätigten Offset-Token platziert.
last_error_message	String	Eine von Menschen lesbare Nachricht, die dem letzten Fehlercode für diesen Kanal entspricht, wobei sensible Kundendaten unkenntlich gemacht wurden.
last_error_timestamp	timestamp_utc	Zeitstempel zu dem Zeitpunkt, an dem der letzte Fehler auftrat.
snowflake_avg_processing_latency_ms	int	Durchschnittliche End-to-End-Verarbeitungszeit für diesen Kanal.

Struktur der Fehlerantwort¶

Die Snowpipe Streaming-REST APIs geben eine JSON-Nutzlast für Fehlerantworten zurück. Diese Struktur liefert verwertbare Informationen sowohl für die automatische Fehlerbehandlung als auch für die menschliche Analyse.

Die Antwortnutzlast hat die folgende Struktur:

{
  "code": "...",
  "message": "..."
}

Copy

Antwortfelder¶

Feld	Typ	Beschreibung
Code	String	Ein stabiler, programmgesteuerter Fehlercode. Dieser Wert kann für die automatische Fehlerbehandlung und Protokollierung verwendet werden. Die Logik einer Anwendung kann zum Beispiel prüfen, ob ein bestimmter Code eine vordefinierte Aktion auslöst.
Meldung	String	Eine von Menschen lesbare Meldung, die den Fehler beschreibt. Diese Meldung kann sich ändern und sollte nicht für das automatische Parsen verwendet werden.

Beispiel¶

Das folgende Beispiel zeigt eine Fehlerantwort, die Sie möglicherweise erhalten:

{
  "code": "STALE_CONTINUATION_TOKEN_SEQUENCER",
  "message": "Channel sequencer in the continuation token is stale. Please reopen the channel"
}

Copy

Dieses Beispiel zeigt die Antwort bei einem Versuch, ein Fortsetzungstoken mit einem veralteten Kanalsequenzierer zu verwenden. Der Code liefert einen klaren, maschinell lesbaren Bezeichner für den Fehler, und die Meldung bietet einen hilfreichen, aussagekräftigen Text für Benutzer.