API REST Snowpipe¶

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.

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.

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.