Points de terminaison de Snowpipe Streaming API REST¶

Note

Nous vous recommandons d’utiliser le SDK :code:`snowpipe-streaming`comme choix principal et par défaut. L API REST n’est pas optimisée pour les scénarios de débit élevé.

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 :

Champ	Type	Description
hostname	string	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	Le nom d’hôte du compte

Réponse :

Champ	Type	Description
token	string	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, 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
channelName	Oui	URI	Nom du canal que vous créez ou rouvrez, non sensible à 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	UUID utilisé pour suivre les requêtes dans le système

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) : le nom de la base de données où se trouve le canal. schema_name (String) : le 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) : le nom de la base de données où se trouve le canal.
schema_name (String) : le 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, non sensible à la casse
schemaName	Oui	URI	Nom du schéma, non sensible à la casse
pipeName	Oui	URI	Canal, non sensible à la casse
channelName	Oui	URI	Nom du canal, non sensible à la casse
continuationToken	Oui	Paramètre de requête	Jeton de continuité de Snowflake, encapsule les séquenceurs de clients et 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.
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 :

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 le statut du canal.
last_committed_offset_token	Chaîne	Dernier jeton de décalage engagé
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 connu 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 du dernier jeton de décalage de l’ensemble de lignes inséré correspondant à une erreur. Le jeton de décalage réel de l’ensemble de lignes contenant la dernière erreur est soit celui-ci, soit celui qui lui est strictement antérieur dans l’ordre d’ingestion des canaux.
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 auquel la dernière erreur s’est produite.
snowflake_avg_processing_latency_ms	int	Temps moyen de traitement e2e pour ce canal.

Structure de la réponse d’erreur¶

Vous devriez voir la forme de charge utile JSON suivante pour les réponses d’erreur de toutes les APIs :

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

Copy