Points de terminaison de Snowpipe Streaming API REST¶

Note

Nous vous recommandons de commencer par le SDK Snowpipe Streaming sur l’API REST pour bénéficier de l’amélioration des performances et de l’expérience de démarrage.

L’API REST Snowpipe Streaming est conçue pour les charges de travail légères et fournit un moyen flexible d’intégrer des applications externes sans utiliser le SDK de Snowpipe Streaming.

Le diagramme suivant donne un aperçu visuel de la manière dont les données circulent depuis le client vers le serveur Snowflake, en détaillant chacun des points de terminaison d’API clés dans le processus.

En-têtes de requête¶

Les en-têtes de requête suivants s’appliquent à tous les points de terminaison de Snowpipe Streaming REST API :

En-tête	Description
`Authorization`	Jeton d’authentification
`X-Snowflake-Authorization-Token-Type` (facultatif)	JWT/OAuth

Note

La taille maximale autorisée pour une seule charge utile de requête est de 16 MB. Si vos données sont plus volumineuses, vous devez les diviser en plusieurs requêtes.

Get Hostname¶

Get Hostname renvoie le nom d’hôte utilisé pour interagir avec Snowpipe Streaming REST API. Chaque compte a un nom d’hôte unique.

GET /v2/streaming/hostname

Réponse :

{
  "hostname": "string"
}

Copy

Description des champs de réponse :

Champ	Type	Description
Nom d’hôte	Chaîne	Nom d’hôte du compte.

Jeton d’échange restreint¶

Le Exchange Scoped Token renvoie un jeton de sécurité qui peut être utilisé pour accéder uniquement au service lié à l” API Snowpipe Streaming. Cela protège la sécurité du client.

POST /oauth/token

Requête :

Attribut	Obligatoire	Composant	Description
content_type	Oui	En-tête	« application/x-www-form-urlencoded »
grant_type	Oui	Charge utile	« urn:ietf:params:oauth:grant-type:jwt-bearer »
scope	Oui	Charge utile	Nom d’hôte du compte.

Réponse :

{
  "token": "string"
}

Copy

Description des champs de réponse :

Champ	Type	Description
Jeton	Chaîne	Le jeton restreint.

Open Channel¶

L’opération Open Channel permet de créer ou d’ouvrir un nouveau canal par rapport à un canal ou à une table. Si le canal existe déjà, Snowflake bouscule le séquenceur client du canal et renvoie le dernier jeton de décalage engagé.

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

Requête :

Attribut	Obligatoire	Composant	Description
databaseName	Oui	URI	Nom de la base de données, insensible à la casse.
schemaName	Oui	URI	Nom du schéma, insensible à la casse.
pipeName	Oui	URI	Nom du canal, insensible à la casse.
channelName	Oui	URI	Nom du canal que vous créez ou que vous rouvrez, insensible à la casse.
offset_token	Non	Charge utile	Chaîne utilisée pour définir un jeton de décalage lors de l’ouverture d’un canal.
requestId	Non	Paramètre de requête	Un identificateur unique universel (UUID) utilisé pour suivre les requêtes dans le système.

Réponse :

{
  "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

Description des champs de réponse :

Champ	Type	Description
next_continuation_token	Chaîne	Un jeton géré par une API qui doit être utilisé dans la prochaine requête Append Rows. Le jeton relie une série d’appels, garantissant un flux de données contigu et dans l’ordre, et maintenant l’état de la session pour une livraison unique et exacte.
channel_status	Objet	Un objet imbriqué avec les informations détaillées suivantes sur le canal : database_name (String) : Nom de la base de données où se trouve le canal. schema_name (String) : Nom du schéma où se trouve le canal. pipe_name (String) : le nom du canal spécifique utilisé. channel_name (String) : le nom du canal de streaming. channel_status_code (String) : un code qui indique le statut actuel du canal ; par exemple, « ACTIVE ». last_committed_offset_token (String) : le jeton qui représente le dernier décalage correctement engagé. created_on_ms (Long) : l’horodatage, en millisecondes, de la création du canal. rows_inserted (Int) : le nombre total de lignes insérées avec succès. rows_parsed (Int) : le nombre total de lignes analysées. rows_error_count (Int) : le nombre total de lignes qui ont rencontré une erreur. last_error_offset_upper_bound (String) : un jeton qui indique la limite supérieure du décalage où la dernière erreur s’est produite. last_error_message (String) : le message de la dernière erreur qui s’est produite. last_error_timestamp (Long) : l’horodatage, en millisecondes, de la dernière erreur. snowflake_avg_processing_latency_ms (Int) : la latence moyenne de traitement de Snowflake en millisecondes.

Champ

Type

Description

next_continuation_token

Chaîne

Un jeton géré par une API qui doit être utilisé dans la prochaine requête Append Rows. Le jeton relie une série d’appels, garantissant un flux de données contigu et dans l’ordre, et maintenant l’état de la session pour une livraison unique et exacte.

channel_status

Objet

Un objet imbriqué avec les informations détaillées suivantes sur le canal :

database_name (String) : Nom de la base de données où se trouve le canal.
schema_name (String) : Nom du schéma où se trouve le canal.
pipe_name (String) : le nom du canal spécifique utilisé.
channel_name (String) : le nom du canal de streaming.
channel_status_code (String) : un code qui indique le statut actuel du canal ; par exemple, « ACTIVE ».
last_committed_offset_token (String) : le jeton qui représente le dernier décalage correctement engagé.
created_on_ms (Long) : l’horodatage, en millisecondes, de la création du canal.
rows_inserted (Int) : le nombre total de lignes insérées avec succès.
rows_parsed (Int) : le nombre total de lignes analysées.
rows_error_count (Int) : le nombre total de lignes qui ont rencontré une erreur.
last_error_offset_upper_bound (String) : un jeton qui indique la limite supérieure du décalage où la dernière erreur s’est produite.
last_error_message (String) : le message de la dernière erreur qui s’est produite.
last_error_timestamp (Long) : l’horodatage, en millisecondes, de la dernière erreur.
snowflake_avg_processing_latency_ms (Int) : la latence moyenne de traitement de Snowflake en millisecondes.

Append Row(s)¶

L’opération Append Rows insère un lot de lignes dans le canal donné.

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

Requête :

Attribut	Obligatoire	Composant	Description
databaseName	Oui	URI	Nom de la base de données, insensible à la casse.
schemaName	Oui	URI	Nom du schéma, insensible à la casse.
pipeName	Oui	URI	Canal, insensible à la casse.
channelName	Oui	URI	Nom du canal, insensible à la casse.
continuationToken	Oui	Paramètre de requête	Jeton de continuation de Snowflake, qui encapsule à la fois le client et les séquenceurs de lignes.
offsetToken	Non	Paramètre de requête	Chaîne utilisée pour l’ensemble des jetons de décalage par lot.
rows	Oui	Charge utile	La charge utile réelle des données à ingérer au formatNDJSON. La taille maximale autorisée pour cet attribut est 4 MB.
requestId	Non	Paramètre de requête	UUID utilisé pour suivre les requêtes dans le système.

Note

Le texte JSON dans la charge utile NDJSON doit être strictement conforme à la norme RFC 8259. Chaque texte JSON doit être suivi d’un caractère de nouvelle ligne \n (0x0A). Vous pouvez également insérer un retour chariot. \r (0x0D) avant le caractère de nouvelle ligne.

Réponse :

{
  "next_continuation_token": "string"
}

Copy

Description des champs de réponse :

Champ	Type	Description
next_continuation_token	string	Le jeton de continuation suivant provient de Snowflake, qui encapsule à la fois les séquenceurs de clients et de lignes. Il doit être utilisé pour l’insertion du lot suivant.

Drop Channel¶

L’opération Drop Channel dépose un canal sur le serveur avec ses métadonnées.

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

Requête :

Attribut	Obligatoire	Composant	Description
databaseName	Oui	URI	Nom de la base de données, non sensible à la casse
schemaName	Oui	URI	Nom du schéma, non sensible à la casse
pipeOrTableName	Oui	URI	Nom du canal ou de la table, non sensible à la casse
channelName	Oui	URI	Nom du canal, non sensible à la casse
requestId	Non	Paramètre de requête	UUID utilisé pour suivre les requêtes dans le système

Réponse :

Cette opération renvoie une charge utile sans réponse correcte spécifique autre que le code d’état HTTP.

Bulk Get Channel Status¶

L’opération Bulk Get Channel Status renvoie le statut d’un canal pour un séquenceur client spécifique.

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

Requête :

Attribut	Obligatoire	Composant	Description
databaseName	Oui	URI	Nom de la base de données, non sensible à la casse
schemaName	Oui	URI	Nom du schéma, non sensible à la casse
pipeName	Oui	URI	Nom du canal, non sensible à la casse
channel_names	Oui	Charge utile	Un tableau de noms de canaux de chaîne pour lesquels le client souhaite obtenir un état. Les noms sont sensibles à la casse. Par exemple, `{"channel_names":["channel1", "channel2"]}`.

Réponse :

{
  "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

Note

Si aucun canal demandé n’est trouvé dans le service, la charge utile de réponse ne comporte pas d’entrée pour ce canal dans l’objet channel_statuses.

Description des champs channel_statuses pour chaque canal :

Champ	Type	Description
channel_status_code	Chaîne	Indique l’état du canal.
last_committed_offset_token	Chaîne	Dernier jeton de décalage validé.
database_name	Chaîne	Le nom de la base de données à laquelle le canal appartient.
schema_name	Chaîne	Le nom du schéma auquel le canal appartient.
nom_canal	Chaîne	Le nom du canal auquel le canal appartient.
channel_name	Chaîne	Le nom du canal.
rows_inserted	int	Un compte de toutes les lignes insérées dans ce canal.
rows_parsed	int	Un compte de toutes les lignes analysées, mais pas nécessairement insérées dans ce canal.
rows_errors	int	Un compte de toutes les lignes qui ont rencontré des erreurs lors de l’insertion dans ce canal et qui ont donc été rejetées.
last_error_offset_upper_bound	Chaîne	La limite supérieure d’une erreur d’ingestion. L’erreur sera située au niveau de ce jeton de décalage validé, ou avant ce dernier.
last_error_message	Chaîne	Un message lisible par l’être humain correspondant au dernier code d’erreur pour ce canal, avec les données sensibles du client expurgées.
last_error_timestamp	timestamp_utc	Horodatage au moment où la dernière erreur s’est produite.
snowflake_avg_processing_latency_ms	int	Temps moyen de traitement de bout en bout pour ce canal.

Structure de la réponse d’erreur¶

Les APIs REST Snowpipe Streaming renvoient une charge utile JSON pour les réponses d’erreur. Cette structure fournit des informations exploitables, tant pour la gestion automatisée des erreurs que pour l’analyse humaine.

La charge utile de la réponse a la structure suivante :

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

Copy

Champs de réponse¶

Champ	Type	Description
Code	Chaîne	Un code d’erreur stable et programmatique. Cette valeur peut être utilisée pour la gestion et la journalisation automatisées des erreurs. Par exemple, la logique d’une application peut vérifier la présence d’un code spécifique pour déclencher une action prédéfinie.
Message	Chaîne	Un message lisible par un humain, qui décrit l’erreur. Ce message est susceptible d’être modifié et ne doit pas être utilisé pour des analyses automatisées.

Exemple¶

L’exemple suivant montre une réponse d’erreur que vous pouvez recevoir :

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

Copy

Cet exemple montre la réponse à une tentative d’utilisation d’un jeton de continuation avec un séquenceur de canal obsolète. Le code fournit un identificateur clair et lisible par une machine pour l’erreur, et le message offre un texte descriptif utile pour l’utilisateur.