Pontos de extremidade da Snowpipe Streaming API REST¶

Nota

Recomendamos que você comece com oSDK do Snowpipe Streaming sobre API REST para se beneficiar do melhor desempenho e da experiência de introdução.

A API REST do Snowpipe Streaming foi projetada para cargas de trabalho leves e oferece uma maneira flexível de se integrar a aplicativos externos sem usar o SDK do Snowpipe Streaming.

O diagrama a seguir fornece uma visão geral geral de como os dados fluem do cliente para o servidor Snowflake, detalhando cada um dos principais pontos de extremidade da API no processo.

Cabeçalhos de solicitação¶

Os cabeçalhos de solicitação a seguir se aplicam a todos os pontos de extremidade da Snowpipe Streaming REST API:

Cabeçalho	Descrição
`Authorization`	Token de autenticação
`X-Snowflake-Authorization-Token-Type` (opcional)	JWT/OAuth

Nota

O tamanho máximo permitido para uma única carga útil de solicitação é 16 MB. Se os seus dados forem maiores, você deverá dividi-los em várias solicitações.

Obter o nome de host¶

O Get Hostname retorna o nome de host usado para interagir com a Snowpipe Streaming REST API. Cada conta tem um nome de host exclusivo.

GET /v2/streaming/hostname

Resposta:

{
  "hostname": "string"
}

Copy

Descrição dos campos de resposta:

Campo	Tipo	Descrição
Nome de host	Cadeia de caracteres	O nome do host da conta.

Exchange Scoped Token¶

O Exchange Scoped Token retorna um token de segurança que pode ser usado para acessar apenas o serviço relacionado à API do Snowpipe Streaming. Isto proporciona proteção de segurança ao cliente.

POST /oauth/token

Solicitação:

Atributo	Obrigatório	Componente	Descrição
content_type	Sim	Cabeçalho	“application/x-www-form-urlencoded”
grant_type	Sim	Carga útil	“urn:ietf:params:oauth:grant-type:jwt-bearer”
scope	Sim	Carga útil	O nome do host da conta.

Resposta:

{
  "token": "string"
}

Copy

Descrição dos campos de resposta:

Campo	Tipo	Descrição
Token	Cadeia de caracteres	O token com escopo.

Canal aberto¶

A operação Open Channel cria ou abre um novo canal em um canal ou tabela. Se o canal já existir, o Snowflake incrementa o sequenciador do cliente do canal e retorna o último token de deslocamento confirmado.

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

Solicitação:

Atributo	Obrigatório	Componente	Descrição
databaseName	Sim	URI	Nome do banco de dados, sem distinção entre maiúsculas e minúsculas.
schemaName	Sim	URI	Nome do esquema, sem distinção entre maiúsculas e minúsculas.
pipeName	Sim	URI	Nome do canal, sem distinção entre maiúsculas e minúsculas.
channelName	Sim	URI	O ome do canal que você cria ou reabre, sem distinção entre maiúsculas e minúsculas.
offset_token	Não	Carga útil	Cadeia de caracteres usada para definir um token de deslocamento ao abrir um canal.
requestId	Não	Parâmetro de consulta	Um identificador universalmente exclusivo (UUID) usado para rastrear solicitações por meio do sistema.

Resposta:

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

Descrição dos campos de resposta:

Campo	Tipo	Descrição
next_continuation_token	Cadeia de caracteres	Um token gerenciado por API que deve ser usado na solicitação subsequente de acrescentar linhas. O token vincula uma série de chamadas, garantindo um fluxo de dados contíguo e ordenado e mantendo o estado da sessão para entrega única.
channel_status	Objeto	Um objeto aninhado com as seguintes informações detalhadas sobre o canal: database_name (String): o nome do banco de dados onde o canal está localizado schema_name (String): o nome do esquema onde o canal está localizado pipe_name (String): o nome do pipe específico que está sendo usado. channel_name (String): o nome do canal de streaming. channel_status_code (String): um código que indica o status atual do canal; por exemplo, «ACTIVE». last_committed_offset_token (String): o token que representa o último deslocamento confirmado com sucesso. created_on_ms (Long): o carimbo de data/hora, em milissegundos, de quando o canal foi criado. rows_inserted (Int): o número total de linhas inseridas com sucesso. rows_parsed (Int): o número total de linhas analisadas. rows_error_count (Int): o número total de linhas que encontraram um erro. last_error_offset_upper_bound (String): um token que indica o limite superior do deslocamento onde ocorreu o último erro. last_error_message (String): a mensagem do último erro ocorrido. last_error_timestamp (Long): o carimbo de data/hora, em milissegundos, do último erro. snowflake_avg_processing_latency_ms (Int): a latência média de processamento do Snowflake em milissegundos.

Campo

Tipo

Descrição

next_continuation_token

Cadeia de caracteres

Um token gerenciado por API que deve ser usado na solicitação subsequente de acrescentar linhas. O token vincula uma série de chamadas, garantindo um fluxo de dados contíguo e ordenado e mantendo o estado da sessão para entrega única.

channel_status

Objeto

Um objeto aninhado com as seguintes informações detalhadas sobre o canal:

database_name (String): o nome do banco de dados onde o canal está localizado
schema_name (String): o nome do esquema onde o canal está localizado
pipe_name (String): o nome do pipe específico que está sendo usado.
channel_name (String): o nome do canal de streaming.
channel_status_code (String): um código que indica o status atual do canal; por exemplo, «ACTIVE».
last_committed_offset_token (String): o token que representa o último deslocamento confirmado com sucesso.
created_on_ms (Long): o carimbo de data/hora, em milissegundos, de quando o canal foi criado.
rows_inserted (Int): o número total de linhas inseridas com sucesso.
rows_parsed (Int): o número total de linhas analisadas.
rows_error_count (Int): o número total de linhas que encontraram um erro.
last_error_offset_upper_bound (String): um token que indica o limite superior do deslocamento onde ocorreu o último erro.
last_error_message (String): a mensagem do último erro ocorrido.
last_error_timestamp (Long): o carimbo de data/hora, em milissegundos, do último erro.
snowflake_avg_processing_latency_ms (Int): a latência média de processamento do Snowflake em milissegundos.

Anexar linha(s)¶

A operação Append Rows insere um lote de linhas no canal fornecido.

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

Solicitação:

Atributo	Obrigatório	Componente	Descrição
databaseName	Sim	URI	Nome do banco de dados, sem distinção entre maiúsculas e minúsculas.
schemaName	Sim	URI	Nome do esquema, sem distinção entre maiúsculas e minúsculas.
pipeName	Sim	URI	Canal, sem distinção entre maiúsculas e minúsculas.
channelName	Sim	URI	Nome do canal, sem distinção entre maiúsculas e minúsculas.
continuationToken	Sim	Parâmetro de consulta	Token de continuação do Snowflake, encapsula tanto o cliente como os sequenciadores de linhas.
offsetToken	Não	Parâmetro de consulta	Cadeia de caracteres usada para definir um token de deslocamento por lote.
rows	Sim	Carga útil	A carga útil de dados real a ser ingerida no formato NDJSON. O tamanho máximo permitido para este atributo é 4 MB.
requestId	Não	Parâmetro de consulta	Um UUID usado para rastrear solicitações no sistema.

Nota

O texto JSON dentro da carga útil NDJSON deve estar em estrita conformidade com o padrão RFC 8259. Cada texto JSON deve ser seguido por um caractere de quebra de linha \n (0x0A). Você também pode inserir um retorno de carro \r (0x0D) antes do caractere de quebra de linha.

Resposta:

{
  "next_continuation_token": "string"
}

Copy

Descrição dos campos de resposta:

Campo	Tipo	Descrição
next_continuation_token	string	O próximo token de continuação do Snowflake, que encapsula os sequenciadores de cliente e de linha. Ele deve ser usado para inserir o próximo lote.

Canal de descarte¶

A operação Drop Channel descarta um canal no lado do servidor junto com seus metadados.

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

Solicitação:

Atributo	Obrigatório	Componente	Descrição
databaseName	Sim	URI	Nome do banco de dados, sem distinção entre maiúsculas e minúsculas
schemaName	Sim	URI	Nome do esquema, sem distinção entre maiúsculas e minúsculas
pipeOrTableName	Sim	URI	Nome do canal ou da tabela, sem distinção entre maiúsculas e minúsculas
channelName	Sim	URI	Nome do canal, sem distinção entre maiúsculas e minúsculas
requestId	Não	Parâmetro de consulta	Um UUID usado para rastrear solicitações no sistema

Resposta:

Essa operação retorna uma carga útil sem nenhuma resposta bem-sucedida específica além do código de status HTTP.

Obter status do canal em massa¶

A operação Bulk Get Channel Status retorna o status de um canal para um sequenciador de cliente específico.

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

Solicitação:

Atributo	Obrigatório	Componente	Descrição
databaseName	Sim	URI	Nome do banco de dados, sem distinção entre maiúsculas e minúsculas
schemaName	Sim	URI	Nome do esquema, sem distinção entre maiúsculas e minúsculas
pipeName	Sim	URI	Nome do canal, sem distinção entre maiúsculas e minúsculas
channel_names	Sim	Carga útil	Uma matriz de nomes de canais de cadeia de caracteres cujo status o cliente deseja obter; os nomes diferenciam maiúsculas de minúsculas. Por exemplo, `{"channel_names":["channel1", "channel2"]}`.

Resposta:

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

Nota

Se nenhum canal solicitado for encontrado no serviço, a carga útil de resposta não terá uma entrada para esse canal no objeto channel_statuses.

Descrição dos campos channel_statuses para cada canal:

Campo	Tipo	Descrição
channel_status_code	Cadeia de caracteres	Indica o status do canal.
last_committed_offset_token	Cadeia de caracteres	Último token de offset confirmado.
database_name	Cadeia de caracteres	O nome do banco de dados ao qual o canal pertence.
schema_name	Cadeia de caracteres	O nome do esquema ao qual o canal pertence.
pipe_name	Cadeia de caracteres	O nome do canal ao qual o canal pertence.
channel_name	Cadeia de caracteres	O nome do canal.
rows_inserted	int	Uma contagem de todas as linhas inseridas nesse canal.
rows_parsed	int	Uma contagem de todas as linhas analisadas, mas não necessariamente inseridas nesse canal.
rows_errors	int	Uma contagem de todas as linhas que sofreram erros ao serem inseridas neste canal e que, portanto, foram rejeitadas.
last_error_offset_upper_bound	Cadeia de caracteres	O limite superior para um erro de ingestão. O erro estará localizado no ou antes deste token de offset confirmado.
last_error_message	Cadeia de caracteres	Uma mensagem legível para humanos correspondente ao código de erro mais recente para esse canal, com os dados confidenciais do cliente redigidos.
last_error_timestamp	timestamp_utc	Carimbo de data/hora em que o último erro ocorreu.
snowflake_avg_processing_latency_ms	int	Tempo médio de processamento de ponta a ponta para este canal.

Estrutura da resposta de erro¶

As APIs REST do Snowpipe Streaming retornam uma carga útil JSON para respostas de erro. Essa estrutura fornece informações acionáveis tanto para o tratamento automatizado de erros quanto para análise humana.

A carga útil de resposta tem a seguinte estrutura:

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

Copy

Campos de resposta:¶

Campo	Tipo	Descrição
Código	Cadeia de caracteres	Um código de erro estável e programático. Esse valor pode ser usado para o tratamento e registro em log de erros de forma automatizada. Por exemplo, a lógica de um aplicativo pode verificar um código específico para acionador uma ação predefinida.
Mensagem	Cadeia de caracteres	Uma mensagem legível por humanos que descreve o erro. Essa mensagem está sujeita a alterações e não deve ser usada para análise automatizada.

Exemplo¶

O exemplo a seguir mostra uma resposta de erro que você pode receber:

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

Copy

Esse exemplo mostra a resposta para uma tentativa de usar um token de continuação com um sequenciador de canal obsoleto. O código fornece um identificador claro e legível por máquina para o erro, e a mensagem oferece um texto útil e descritivo para o usuário.