Pontos de extremidade da Snowpipe Streaming API REST¶

Nota

Recomendamos que você use o SDK snowpipe-streaming como a opção principal e padrão. A API REST não é otimizada para cenários de alta taxa de transferência.

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:

Campo	Tipo	Descrição
hostname	string	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:

Campo	Tipo	Descrição
token	string	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 nome 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	UUID usado para rastrear solicitações no sistema

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 pipe está localizado schema_name (String): o nome do esquema onde o pipe 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 pipe está localizado
schema_name (String): o nome do esquema onde o pipe 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 Snowflake, encapsula os sequenciadores de cliente e de linha
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.
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:

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 deslocamento comprometido
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 apresentaram erros ao serem inseridas nesse canal e, portanto, foram rejeitadas.
last_error_offset_upper_bound	Cadeia de caracteres	Limite superior para o token de deslocamento mais recente do conjunto de linhas inserido, cuja última linha corresponde a um erro. O token de deslocamento real do conjunto de linhas com o último erro é este ou está estritamente antes dele na ordem de ingestão do canal.
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 ocorreu o último erro.
snowflake_avg_processing_latency_ms	int	Tempo médio de processamento e2e para esse canal.

Estrutura da resposta de erro¶

Você deverá ver o seguinte formato de carga útil JSON para respostas de erro de todas as APIs:

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

Copy