Origens Singer

Descrição

Uma origem Singer permite ao PlaidCloud extrair dados de um vasto catálogo de aplicações SaaS, APIs e bases de dados — como Stripe, GitHub, Slack e BigQuery — através de taps Singer. Cada tap é um conector para uma origem; escolhe o tap ao criar a ligação e o PlaidCloud mostra os campos de configuração de que esse tap necessita.

A utilização de uma origem Singer tem duas partes:

1. Uma ligação de origem Singer guarda a escolha do tap e as respetivas definições (token de API, ID da conta, data de início, etc.).
2. Um passo de fluxo de trabalho Import Singer Source deteta os canais disponíveis do tap, permite escolher quais importar e onde cada um é carregado, e executa a extração.

Nota

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

Uma ligação de origem Singer guarda o tap e as respetivas definições; o passo Import Singer Source deteta os canais do tap e carrega os que escolher em tabelas do projeto.

Antes de Começar

Vai precisar das credenciais do sistema de origem (por exemplo, um token de acesso pessoal do GitHub ou uma chave de API do Stripe) e do projeto e do fluxo de trabalho onde pretende que os dados sejam carregados.

Criar uma Ligação de Origem Singer

1. Abra Tools > Connections.
2. Clique em Nova ligação e escolha Origem Singer.
3. Atribua à ligação um Nome (por exemplo, GitHub (prod)).
4. Escolha um Tap na lista pendente. O formulário abaixo é reconstruído para mostrar os campos desse tap. Consulte Origens Singer para o catálogo completo e uma ligação 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 é apresentado de acordo com o valor que o tap espera:

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

• Palavra-passe — um segredo, como um token ou uma chave de API. Os segredos são apenas de escrita: não são mostrados quando edita a ligação, e deixar um em branco ao guardar 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 projetos).

• JSON — um valor estruturado introduzido como JSON, utilizado quando um tap espera um objeto ou uma matriz de objetos. Por exemplo, as definições de ficheiros de um tap CSV:

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

• Caixa de verificação — uma opção ligada/desligada.

Os campos obrigatórios estão assinalados, e o formulário valida-os (incluindo se os campos JSON e numéricos estão bem formados) antes de guardar.

Importar Canais para um Fluxo de Trabalho

1. Abra o fluxo de trabalho e aceda ao separador Analyze Steps.
2. Adicione um passo e escolha Importar: Origem Singer como tipo. O editor abre com um separador Origem e um separador Canais.
3. No separador Origem:
   • Escolha a Ligação (a sua ligação de origem Singer).
   • Escolha um Modo de sincronização — Tabela completa (substituir em cada execução), Incremental (acrescentar novos dados) ou Upsert (fundir pela chave).
   • Clique em Detetar fluxos. A deteção é executada no runner e pode demorar até cerca de três minutos na primeira vez; o estado mostra quantos canais foram encontrados.
4. No separador Canais, vê uma linha por canal detetado. Para cada canal pretendido:
   • Abra o respetivo painel Canal e marque Importar este fluxo.
   • Escolha uma Tabela de destino para onde os dados do canal são carregados.
   • Se o modo de sincronização for Upsert, defina as Colunas-chave do canal — um nome de coluna por linha. O campo assume por predefinição a chave primária declarada do tap; substitua-a para fundir por outras colunas. Cada canal importado precisa de pelo menos uma coluna-chave quando o modo é Upsert.
5. Guarde o passo e execute-o como parte do fluxo de trabalho (ou isoladamente).

Cuidado

Os canais que seleciona são o conjunto guardado. Para alterar os canais importados, clique novamente em Detetar fluxos — os canais que reaparecem mantêm a tabela de destino e a seleção que já definiu.

Modos de Sincronização

• Tabela completa (substituir em cada execução) volta a extrair o canal inteiro em cada execução e substitui a tabela de destino. Utilize-o para origens pequenas ou totalmente atualizadas.
• Incremental (acrescentar novos dados) extrai apenas as linhas novas desde a última execução e acrescenta-as, retomando do ponto onde a execução anterior parou. Só funciona para canais que o tap consegue sincronizar de forma incremental — os que expõem uma chave de replicação (como uma data/hora de atualização ou um ID incremental). Se escolher incremental e um canal selecionado não tiver chave de replicação, o passo pede-lhe que mude esse canal para tabela completa ou que o desmarque.
• Upsert (fundir pela chave) volta a extrair o canal inteiro em cada execução e depois funde-o no destino pelas Colunas-chave do canal: as linhas cuja chave corresponde a uma linha existente são atualizadas no local, e as linhas com uma chave nova são inseridas. As linhas existentes que não estão nesta execução são mantidas. Utilize-o para manter uma tabela alinhada com uma origem cujos registos mudam ao longo do tempo — sem os duplicados que um acrescento criaria nem a reconstrução total que uma substituição faria. A tabela de destino é criada na primeira execução, pelo que o primeiro upsert insere todas as linhas.

Nota

O progresso incremental é acompanhado por passo. A primeira execução incremental extrai tudo; as execuções seguintes recolhem apenas as linhas novas.

Nota

O upsert volta a extrair o canal completo em cada execução (não utiliza uma chave de replicação), pelo que é adequado a origens em que as linhas existentes são atualizadas e pretende uma linha por chave. Defina as Colunas-chave de cada canal no separador Canais; assumem por predefinição a chave primária declarada do tap.

Cuidado

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

Como as Credenciais São Tratadas

O passo guarda uma referência à ligação, não uma cópia das respetivas credenciais. Cada execução lê as credenciais atuais da ligação no momento da execução. Assim, quando roda um token ou uma chave, atualize-o uma vez na ligação e todos os passos que a utilizam assumem o novo valor na execução seguinte — não há nada para atualizar nos passos individuais.

A extração é executada numa tarefa isolada que recebe apenas a configuração do próprio tap; não tem acesso a outras ligações nem aos serviços internos do PlaidCloud.

Relacionado

• Catálogo de origens Singer — todas as origens disponíveis e a respetiva documentação de configuração
• Referência do passo Import Singer Source
• Ligações