API REST Snowpipe

Você interage com um canal fazendo chamadas para pontos de extremidade REST. Este tópico descreve a API REST Snowpipe para definir a lista de arquivos a serem ingeridos e buscar relatórios do histórico de carregamento.

O Snowflake também fornece APIs Java e Python que simplificam o trabalho com a API REST Snowpipe.

Neste tópico:

Ingestão de arquivo de dados

A API Snowpipe fornece um ponto de extremidade REST para definir a lista de arquivos a serem ingeridos.

Ponto de extremidade: insertFiles

Informa o Snowflake sobre os arquivos a serem ingeridos em uma tabela. Uma resposta bem-sucedida a partir desse ponto de extremidade significa que o Snowflake registrou a lista de arquivos a serem adicionados à tabela. Isso não significa necessariamente que os arquivos tenham sido ingeridos. Para obter mais detalhes, consulte os códigos de resposta abaixo.

Na maioria dos casos, o Snowflake insere novos dados na tabela de destino dentro de poucos minutos.

method

POST

post url

https://{account}.snowflakecomputing.com/v1/data/pipes/{pipeName}/insertFiles?requestId={requestId}

post body

Um objeto JSON com os seguintes atributos:

Atributo

Obrigatório

Descrição

account

Sim

Identificador da conta de sua conta Snowflake.

pipeName

Sim

Nome do canal totalmente qualificado que diferencia maiúsculas de minúsculas. Por exemplo, myDatabase.mySchema.myPipe.

requestId

Não

Cadeia de caracteres usada para rastrear solicitações por meio do sistema. Recomendamos fornecer uma cadeia de caracteres aleatória com cada solicitação, por exemplo, um UUID.

content-type

text/plain

application/json

header fields

Aceita: text/plain ou application/json

Autorização: BEARER <token_jwt>

  • Para text/plain, o conteúdo é a lista de caminhos e nomes de arquivos, um por linha. O parâmetro size não é permitido.

  • Para application/json, o conteúdo é a lista de caminhos, nomes de arquivos e tamanhos de arquivos (opcional, mas recomendado para um melhor desempenho). Um exemplo de carga útil é o seguinte:

    {
      "files":[
        {
          "path":"filePath/file1.csv",
          "size":100
        },
        {
          "path":"filePath/file2.csv",
          "size":100
        }
      ]
    }
    
    Copy

Observe que se você seguir nossas práticas recomendadas dividindo seus dados no estágio usando caminhos lógicos granulares. Os valores dos caminhos na carga útil incluem os caminhos completos para os arquivos preparados.

Nota

  • A postagem pode conter, no máximo, 5.000 arquivos.

  • Cada caminho de arquivo dado deve ser <= 1024 bytes longos quando serializado como UTF-8.

response body

Códigos de resposta:

  • 200 — Sucesso. Arquivos adicionados à fila de arquivos a serem ingeridos.

  • 400 — Falha. Solicitação inválida devido a um formato inválido ou limite excedido.

  • 404 — Falha. pipeName não reconhecido.

    Esse código de erro também pode ser retornado se a função utilizada ao chamar o ponto de extremidade não tiver privilégios suficientes. Para obter mais informações, consulte Concessão de privilégios de acesso.

  • 429 — Falha. O limite de taxa de solicitação foi excedido.

  • 500 — Falha. Ocorreu um erro interno.

Carga útil de resposta:

Com uma solicitação API bem-sucedida (ou seja, código 200), a carga útil de resposta contém os elementos requestId e status no formato JSON. Se ocorrer um erro, a carga útil de resposta pode conter detalhes sobre o erro.

Se a instrução COPY INTO <tabela> na definição do canal incluir a opção de cópia PATTERN, o atributo unmatchedPatternFiles lista todos os arquivos enviados no cabeçalho que não correspondem à expressão regular e que, portanto, foram ignorados.

Relatórios do histórico de carregamento

A API Snowpipe fornece pontos de extremidade REST para a obtenção de relatórios de carregamento.

Ponto de extremidade: insertReport

Recupera um relatório de arquivos enviados via insertFiles, cujo conteúdo foi recentemente ingerido em uma tabela. Note que, para arquivos grandes, isso pode ser apenas parte do arquivo.

Observe as seguintes limitações desse ponto de extremidade:

  • Os 10.000 eventos mais recentes são mantidos.

  • Os eventos são retidos por um período máximo de 10 minutos.

Um evento ocorre quando os dados de um arquivo enviado via insertFiles foram enviados para a tabela e estão disponíveis para consultas. O ponto de extremidade insertReport pode ser pensado como comando tail do UNIX. Ao chamar esse comando repetidamente, é possível ver o histórico completo dos eventos em um canal ao longo do tempo. Note que o comando deve ser chamado com frequência suficiente para não perder os eventos. A frequência depende da taxa de envio dos arquivos para insertFiles.

method

GET

get url

https://<identificador_de_conta>.snowflakecomputing.com/v1/data/pipes/<pipeName>/insertReport?requestId=<requestId>&beginMark=<beginMark>

header fields

Aceitar: texto/simples ou aplicativo/json

Autorização: BEARER <token_jwt>

get body

Um objeto JSON com os seguintes atributos:

Atributo

Obrigatório

Descrição

account_identifier

Sim

Identificador único de sua conta Snowflake.

O formato preferido do identificador de conta é o seguinte:

organization_name-account_name

Nomes de sua conta e organização no Snowflake. Para obter mais detalhes, consulte Formato 1 (preferido): Nome da conta em sua organização.

Alternativamente, especifique seu localizador de contas, juntamente com a região e a plataforma de nuvem onde a conta é hospedada, se necessário. Para obter mais detalhes, consulte Formato 2 (legado): Localizador de conta em uma região.

pipeName

Sim

Nome do canal totalmente qualificado que diferencia maiúsculas de minúsculas. Por exemplo, myDatabase.mySchema.myPipe.

requestId

Não

Cadeia de caracteres usada para rastrear solicitações por meio do sistema. Recomendamos fornecer uma cadeia de caracteres aleatória com cada solicitação, por exemplo, um UUID.

beginMark

Sim

Marcador, retornado por uma chamada anterior para insertReport, que pode ser usado para reduzir o número de eventos repetidos vistos ao chamar insertReport repetidamente. Observe que isso é uma dica e eventos repetidos podem ocasionalmente ser retornados.

response body

Códigos de resposta:

  • 200 — Sucesso. Relatório retornado.

  • 400 — Falha. Solicitação inválida devido a um formato inválido ou limite excedido.

  • 404 — Falha. pipeName não reconhecido.

    Esse código de erro também pode ser retornado se a função utilizada ao chamar o ponto de extremidade não tiver privilégios suficientes. Para obter mais informações, consulte Concessão de privilégios de acesso.

  • 429 — Falha. O limite de taxa de solicitação foi excedido.

  • 500 — Falha. Ocorreu um erro interno.

Carga útil de resposta:

Uma resposta de sucesso (200) contém informações sobre arquivos que foram adicionados recentemente à tabela. Observe que esse relatório pode representar apenas uma parte de um grande arquivo.

Por exemplo:

{
  "pipe": "TESTDB.TESTSCHEMA.pipe2",
  "completeResult": true,
  "nextBeginMark": "1_39",
  "files": [
    {
      "path": "data2859002086815673867.csv",
      "stageLocation": "s3://mybucket/",
      "fileSize": 57,
      "timeReceived": "2017-06-21T04:47:41.453Z",
      "lastInsertTime": "2017-06-21T04:48:28.575Z",
      "rowsInserted": 1,
      "rowsParsed": 1,
      "errorsSeen": 0,
      "errorLimit": 1,
      "complete": true,
      "status": "LOADED"
    }
  ]
}
Copy

Campos de resposta:

Campo

Tipo

Descrição

pipe

Cadeia de caracteres

O nome totalmente qualificado do canal.

completeResult

Booleano

false se um evento foi perdido entre o evento fornecido beginMark e o primeiro evento neste histórico de relatórios. Caso contrário, true.

nextBeginMark

Cadeia de caracteres

beginMark para usar na próxima solicitação para evitar ver registros duplicados. Observe que esse valor é uma dica. Duplicatas ainda podem ocorrer ocasionalmente.

files

Matriz

Uma matriz de objetos JSON, um objeto para cada arquivo que faz parte da resposta do histórico.

path

Cadeia de caracteres

O caminho do arquivo relativo à localização do estágio.

stageLocation

Cadeia de caracteres

Ou a ID do estágio (estágio interno) ou o bucket S3 (estágio externo) definido no canal.

fileSize

Long

Tamanho do arquivo, em bytes.

timeReceived

Cadeia de caracteres

Hora em que esse arquivo foi recebido para processamento. O formato é ISO-8601 no fuso horário do UTC.

lastInsertTime

Cadeia de caracteres

Hora em que os dados desse arquivo foram inseridos pela última vez na tabela. O formato é ISO-8601 no fuso horário do UTC.

rowsInserted

Long

Número de linhas inseridas na tabela de destino a partir do arquivo.

rowsParsed

Long

Número de linhas analisadas a partir do arquivo. Linhas com erros podem ser ignoradas.

errorsSeen

Inteiro

Número de erros encontrados no arquivo

errorLimit

Inteiro

Número de erros permitidos no arquivo antes de ser considerado falha (com base na opção de cópia ON_ERROR).

firstError [1]

Cadeia de caracteres

Mensagem de erro referente ao primeiro erro encontrado nesse arquivo.

firstErrorLineNum [1]

Long

Número da linha do primeiro erro.

firstErrorCharacterPos [1]

Long

Posição do caractere do primeiro erro.

firstErrorColumnName [1]

Cadeia de caracteres

Nome da coluna onde ocorreu o primeiro erro.

systemError [1]

Cadeia de caracteres

Erro geral que descreve o motivo pelo qual o arquivo não foi processado.

complete

Booleano

Indica se o arquivo foi completamente processado com sucesso.

status

Cadeia de caracteres

Status de carregamento do arquivo:

  • LOAD_IN_PROGRESS: Parte do arquivo foi carregada na tabela, mas o processo de carregamento ainda não foi concluído.

  • LOADED: O arquivo inteiro foi carregado na tabela.

  • LOAD_FAILED: O carregamento do arquivo falhou.

  • PARTIALLY_LOADED: Algumas linhas deste arquivo foram carregadas com sucesso, mas outras não foram carregadas devido a erros. O processamento deste arquivo está concluído.

[1] Os valores só são fornecidos para esses campos quando os arquivos incluem erros.

Ponto de extremidade: loadHistoryScan

Busca um relatório sobre arquivos ingeridos, cujo conteúdo foi adicionado à tabela. Note que, para arquivos grandes, isso pode ser apenas parte do arquivo. Esse ponto de extremidade difere de insertReport na medida em que vê o histórico entre dois pontos no tempo. Há um máximo de 10.000 itens retornados, mas várias chamadas podem ser emitidas para cobrir o intervalo desejado.

Importante

Esse ponto de extremidade é limitado para evitar chamadas excessivas. Para ajudar a evitar exceder o limite de taxa (código de erro 429), recomendamos contar mais fortemente com insertReport do que com loadHistoryScan. Ao chamar loadHistoryScan, especifique o menor intervalo que inclui um conjunto de carregamentos de dados. Por exemplo, ler os últimos 10 minutos de histórico a cada 8 minutos funcionaria bem. Tentar ler as últimas 24 horas do histórico a cada minuto resultará em 429 erros indicando que um limite de taxa foi atingido. Os limites de taxa são projetados para permitir que cada registro de histórico seja lido várias vezes.

Para uma exibição mais abrangente, sem esses limites, o Snowflake oferece uma função de tabela do Information Schema, COPY_HISTORY, que retorna o histórico de carregamento de um canal ou tabela.

method

GET

get url

https://{account}.snowflakecomputing.com/v1/data/pipes/{pipeName}/loadHistoryScan?startTimeInclusive=<startTime>&endTimeExclusive=<endTime>&requestId=<requestId>

header fields

Aceitar: texto/simples ou aplicativo/json

Autorização: BEARER <token_jwt>

get body

Um objeto JSON com os seguintes atributos:

Atributo

Obrigatório

Descrição

account

Sim

Identificador da conta de sua conta Snowflake.

pipeName

Sim

Nome do canal totalmente qualificado que diferencia maiúsculas de minúsculas. Por exemplo, myDatabase.mySchema.myPipe.

startTimeInclusive

Sim

Carimbo de data/hora no formato ISO-8601. Início do intervalo para recuperar os dados do histórico de carregamento.

endTimeExclusive

Não

Carimbo de data/hora no formato ISO-8601. Fim do intervalo para recuperar os dados do histórico de carregamento. Se omitido, então CURRENT_TIMESTAMP() é usado como o fim do intervalo.

requestId

Não

Cadeia de caracteres usada para rastrear solicitações por meio do sistema. Recomendamos fornecer uma cadeia de caracteres aleatória com cada solicitação (por exemplo, um UUID).

response body

Códigos de resposta:

  • 200 — Sucesso. Os resultados do escaneamento do histórico de carregamento são retornados.

  • 400 — Falha. Solicitação inválida devido a um formato inválido ou limite excedido.

  • 404 — Falha. pipeName não reconhecido.

  • 429 — Falha. O limite de taxa de solicitação foi excedido.

  • 500 — Falha. Ocorreu um erro interno.

Carga útil de resposta:

Uma resposta de sucesso (200) contém informações sobre arquivos que foram adicionados recentemente à tabela. Observe que esse relatório pode representar apenas uma parte de um grande arquivo.

Por exemplo:

{
  "pipe": "TESTDB.TESTSCHEMA.pipe2",
  "completeResult": true,
  "startTimeInclusive": "2017-08-25T18:42:31.081Z",
  "endTimeExclusive":"2017-08-25T22:43:45.552Z",
  "rangeStartTime":"2017-08-25T22:43:45.383Z",
  "rangeEndTime":"2017-08-25T22:43:45.383Z",
  "files": [
    {
      "path": "data2859002086815673867.csv",
      "stageLocation": "s3://mystage/",
      "fileSize": 57,
      "timeReceived": "2017-08-25T22:43:45.383Z",
      "lastInsertTime": "2017-08-25T22:43:45.383Z",
      "rowsInserted": 1,
      "rowsParsed": 1,
      "errorsSeen": 0,
      "errorLimit": 1,
      "complete": true,
      "status": "LOADED"
    }
  ]
}
Copy

Campos de resposta:

Campo

Tipo

Descrição

pipe

Cadeia de caracteres

Nome totalmente qualificado do canal.

completeResult

Booleano

false se o relatório estiver incompleto (ou seja, o número de entradas no intervalo especificado exceder o limite de 10.000 entradas). Se false, o usuário pode especifique o valor atual rangeEndTime como o valor startTimeInclusive para a próxima solicitação para prosseguir para o próximo conjunto de entradas.

startTimeInclusive

Cadeia de caracteres

Carimbo de data/hora inicial (no formato ISO 8601) fornecido na solicitação.

endTimeExclusive

Cadeia de caracteres

Carimbo de data/hora final (no formato ISO 8601) fornecido na solicitação.

rangeStartTime

Cadeia de caracteres

Carimbo de data/hora (no formato ISO 8601) da entrada mais antiga dos arquivos incluídos na resposta.

rangeEndTime

Cadeia de caracteres

Carimbo de data/hora (no formato ISO 8601) da entrada mais recente dos arquivos incluídos na resposta.

files

Matriz

Uma matriz de objetos JSON, um objeto para cada arquivo que faz parte da resposta do histórico. Dentro da matriz, os campos de resposta são os mesmos que os retornados na resposta insertReport.