Origens Singer

Descrição

Uma origem Singer permite que o PlaidCloud extraia dados de um amplo catálogo de aplicativos SaaS, APIs e bancos de dados, como Stripe, GitHub, Slack e BigQuery, usando taps do Singer. Cada tap é um conector para uma origem; você escolhe o tap ao criar a conexão, e o PlaidCloud mostra os campos de configuração de que esse tap precisa.

O uso de uma origem Singer tem duas partes:

1. Uma conexão Origem Singer guarda a escolha do tap e suas configurações (token de API, ID da conta, data de início e assim por diante).
2. Uma etapa de fluxo de trabalho Import Singer Source descobre os streams disponíveis do tap, permite escolher quais importar e onde cada um é gravado, e executa a extração.

Nota

O PlaidCloud inclui um catálogo selecionado de taps com licenças permissivas. Os campos exatos de configuração variam de tap para tap: o formulário da conexão é gerado a partir do tap selecionado.

Uma conexão de origem Singer guarda o tap e suas configurações; a etapa Import Singer Source descobre os streams do tap e grava os que você escolher em tabelas de projeto.

Antes de começar

Você precisará das credenciais do sistema de origem (por exemplo, um token de acesso pessoal do GitHub ou uma chave de API do Stripe), além do projeto e do fluxo de trabalho em que deseja gravar os dados.

Criar uma conexão Origem Singer

1. Abra Tools > Connections.
2. Clique em Nova conexão e escolha Origem Singer.
3. Dê à conexão um Nome (por exemplo, GitHub (prod)).
4. Escolha um Tap na lista suspensa. O formulário abaixo dela é reconstruído para mostrar os campos desse tap. Consulte Origens Singer para ver o catálogo completo e um link para a documentação de configuração de cada origem.
5. Preencha os campos de configuração do tap e clique em Criar.

Tipos de campos de configuração

Os campos dependem do tap, e cada um é exibido de acordo com o valor que o tap espera:

• Texto: um valor de uma linha (por exemplo, um ID de conta ou uma data de início).

• Senha: um segredo, como um token ou uma chave de API. Os segredos são somente de gravação: não são exibidos quando você edita a conexão, e deixar um em branco ao salvar mantém o valor armazenado.

• Número: um inteiro ou decimal (por exemplo, uma porta ou um tamanho de página).

• Lista: uma entrada por linha (por exemplo, uma lista de repositórios ou de IDs de projeto).

• JSON: um valor estruturado informado como JSON, usado quando um tap espera um objeto ou uma matriz de objetos. Por exemplo, as definições de arquivo de um tap de CSV:

  [
    { "entity": "orders", "path": "/data/orders.csv", "keys": ["id"] }
  ]

• Caixa de seleção: uma opção ativada/desativada.

Os campos obrigatórios são marcados, e o formulário os valida (inclusive se os campos JSON e numéricos estão bem formados) antes de salvar.

Importar streams em um fluxo de trabalho

1. Abra o fluxo de trabalho e vá para a guia Analyze Steps.
2. Adicione uma etapa e escolha Importar: Origem Singer como tipo. O editor abre com uma guia Origem e uma guia Streams.
3. Na guia Origem:
   • Escolha a Conexão (sua conexão Origem Singer).
   • Escolha um Modo de sincronização: Tabela completa (substituir a cada execução), Incremental (anexar novos dados) ou Upsert (mesclar pela chave).
   • Clique em Descobrir streams. A descoberta é executada no runner e pode levar cerca de três minutos na primeira vez; o status mostra quantos streams foram encontrados.
4. Na guia Streams, você verá uma linha para cada stream descoberto. Para cada stream desejado:
   • Abra o painel Stream dele e marque Importar este stream.
   • Escolha uma Tabela de destino para onde os dados do stream serão gravados.
   • Se o modo de sincronização for Upsert, defina as Colunas-chave do stream, um nome de coluna por linha. O campo assume por padrão a chave primária declarada do tap; substitua-a para mesclar por outras colunas. Todo stream importado precisa de pelo menos uma coluna-chave quando o modo é Upsert.
5. Salve a etapa e execute-a como parte do fluxo de trabalho (ou isoladamente).

Cuidado

Os streams que você seleciona são o conjunto salvo. Para alterar quais streams são importados, clique em Descobrir streams novamente: os streams que reaparecem mantêm a tabela de destino e a seleção que você já definiu.

Modos de sincronização

• Tabela completa (substituir a cada execução) extrai novamente todo o stream a cada execução e substitui a tabela de destino. Use para origens pequenas ou totalmente atualizadas.
• Incremental (anexar novos dados) extrai somente as linhas que são novas desde a última execução e as anexa, retomando de onde a execução anterior parou. Funciona apenas para streams que o tap consegue sincronizar de forma incremental, ou seja, que expõem uma chave de replicação (como um carimbo de data/hora de atualização ou um ID incremental). Se você escolher incremental e um stream selecionado não tiver chave de replicação, a etapa pede que você mude esse stream para tabela completa ou o desmarque.
• Upsert (mesclar pela chave) extrai novamente todo o stream a cada execução e depois o mescla no destino pelas Colunas-chave do stream: as linhas cuja chave corresponde a uma linha existente são atualizadas no lugar, e as linhas com uma chave nova são inseridas. As linhas existentes que não estão nesta execução são mantidas. Use para manter uma tabela em sincronia com uma origem cujos registros mudam ao longo do tempo, sem as duplicatas que um anexo criaria nem a reconstrução completa que uma substituição faria. A tabela de destino é criada na primeira execução; portanto, o upsert inicial insere todas as linhas.

Nota

O progresso incremental é rastreado por etapa. A primeira execução incremental extrai tudo; as execuções seguintes pegam somente as linhas novas.

Nota

O upsert extrai novamente o stream inteiro a cada execução (não usa uma chave de replicação); portanto, é adequado para origens em que as linhas existentes são atualizadas e você quer uma linha por chave. Defina as Colunas-chave de cada stream na guia Streams; elas assumem por padrão a chave primária declarada do tap.

Cuidado

Escolha colunas-chave que estejam sempre presentes. O upsert corresponde as linhas pelo valor exato da chave, e uma chave vazia (nula) nunca corresponde a outra; portanto, as linhas com chave nula são sempre inseridas em vez de mescladas e podem se acumular ao longo das execuções.

Como as credenciais são tratadas

A etapa armazena uma referência à conexão, não uma cópia de suas credenciais. Cada execução lê as credenciais atuais da conexão no momento da execução. Assim, quando você troca um token ou uma chave, atualize-o uma vez na conexão e todas as etapas que a usam adotam o novo valor na próxima execução; não há nada a atualizar nas etapas individuais.

A extração é executada em um job isolado que recebe apenas a configuração do próprio tap; ele não tem acesso a outras conexões nem aos serviços internos do PlaidCloud.

Relacionados

• Catálogo de origens Singer: todas as origens disponíveis e a documentação de configuração de cada uma
• Referência da etapa Import Singer Source
• Conexões