Snowpipe Streaming API REST-Endpunkte¶

Bemerkung

Wir empfehlen Ihnen, die snowpipe-streaming SDK als primäre und standardmäßige Wahl zu verwenden. Die REST API ist nicht für Szenarios mit hohem Durchsatz optimiert.

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:

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:

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	Pipe-Name, Groß-/Kleinschreibung wird nicht berücksichtigt
channelName	Ja	URI	Der Name des Kanals, den Sie erstellen oder wieder ö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	Verwendetes UUID, um Anfragen durch das System zu verfolgen

Antwort:

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	Fortsetzungs-Token von Snowflake, kapselt sowohl Client- als auch Zeilen-Sequenzer ein
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.
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:

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	Letzter bestätigter 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	Eine Zählung aller Zeilen, bei denen beim Einfügen in diesen Kanal Fehler aufgetreten sind und die daher abgelehnt wurden.
last_error_offset_upper_bound	String	Obere Schranke für das letzte Offset-Token des eingefügten Zeilensatzes, bei dem der letzte einem Fehler entspricht. Der tatsächliche Offset-Token der Zeile mit dem letzten Fehler ist entweder dieser oder der davor liegende in der Reihenfolge der Kanalaufnahme.
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, an dem der letzte Fehler aufgetreten ist.
snowflake_avg_processing_latency_ms	int	Durchschnittliche e2e-Verarbeitungszeit für diesen Kanal.

Struktur der Fehlerantwort¶

Sie sollten die folgende Nutzlastform für JSON für Fehlerantworten von allen APIs sehen:

{
   "error_code": "",
   "message": ""
}

Copy