Pular para o conteúdo

Criar e gerir uma ligação

Uma ligação é uma configuração guardada que permite ao PlaidCloud aceder a um sistema externo — uma base de dados, um data lake, um ERP, uma API REST, um serviço na nuvem ou um fornecedor de Git. Os passos do fluxo de trabalho referenciam a ligação pelo nome, pelo que os detalhes do ponto de acesso e as credenciais ficam num só local e são reutilizados em todos os passos e projetos que precisem deles.

As ligações são geridas em Tools > Connections.

  1. Abra Tools > Connections
  2. Clique em New Connection na barra de ferramentas e escolha, no menu, o sistema ao qual pretende ligar-se
  3. Preencha o formulário da ligação (os separadores e os campos variam consoante o tipo — consulte Formulário da ligação abaixo)
  4. Clique em Create para guardar

A nova ligação aparece na lista, com a si como proprietário.

As ligações Acumatica, Bill.com, Dynamics, Eclipse, HFM/FCCS, NetSuite, Workday e Workday Financials são guardadas como ligações REST, e a coluna Tipo da lista mostra o tipo próprio do serviço. Cada uma abre no seu próprio formulário para criar, editar e escolher em passos. Os cabeçalhos, a autenticação e a paginação encontram-se em Edit REST settings, a que se acede a partir do menu de contexto (clique com o botão direito do rato; consulte Editar uma ligação).

A maioria das ligações abre um formulário com vários separadores. Os separadores exatos dependem do tipo, mas é comum ver:

  • Configuração da ligação (ou Detalhes da ligação para REST) — o Name da ligação, um Memo opcional, o anfitrião/porta/base de dados (ou o anfitrião/tipo de autenticação para REST), o interruptor Usage (Active) e o Security Model. Numa ligação a uma base de dados, as credenciais encontram-se aqui, num grupo Credenciais de autenticação; numa ligação REST, têm o seu próprio separador Autenticação.
  • Configuração SSL — Use SSL mais o modo SSL e certificados opcionais de cliente/raiz para uma ligação cifrada.
  • Configuração SSH — Use SSH mais o anfitrião bastion, a porta, o utilizador e a chave para encaminhar a ligação através de um anfitrião de salto SSH.

Os campos de palavra-passe, token e outras credenciais são só de escrita: aparecem em branco quando volta a abrir uma ligação guardada, e deixá-los em branco ao guardar mantém o segredo armazenado. Volte a escrever um valor apenas quando pretender alterá-lo. Isto abrange a chave de API, o segredo de cliente OAuth e o token de atualização OAuth de uma ligação REST. As credenciais de várias linhas — um certificado privado do NetSuite, um certificado e uma chave privada do Anaplan, uma chave de API do Postman, um URL de webhook de entrada do Slack ou do Teams — são só de escrita da mesma forma e ficam mascaradas enquanto as escreve ou cola. Uma substituição composta apenas por espaços é recusada em vez de ser guardada sobre a credencial armazenada; limpe o campo para manter o valor guardado. A chave de cliente SSL e a chave privada SSH de uma ligação SQL ou Git também são só de escrita, mas permanecem visíveis enquanto as escreve. Todos os outros campos mostram o seu valor guardado real em todos os locais onde a ligação é apresentada, no editor e através da API, incluindo campos que parecem sensíveis pelo nome (o indicador de só de leitura de uma base de dados, um identificador de conta, um esquema, um nome de anfitrião) — apenas uma credencial real é mascarada ou ocultada.

Através da API REST e do MCP, um campo de credencial segue a mesma regra do editor: envie uma cadeia vazia e o PlaidCloud mantém o valor armazenado; envie null para o limpar. Todos os campos que não são credenciais continuam a ser limpos quando os envia em branco.

Os campos obrigatórios são validados ao guardar; se faltar algo, o formulário muda para o separador que contém o primeiro campo inválido e assinala-o.

O Security Model de uma ligação controla quem na área de trabalho a pode utilizar:

Opção Quem pode utilizar a ligação
Privado (apenas proprietários) Apenas os proprietários.
Apenas membros específicos Os proprietários mais uma lista explícita de membros.
Apenas grupos de segurança específicos Os proprietários mais os membros de grupos de segurança indicados.
Todos os membros da área de trabalho Todas as pessoas da área de trabalho.

Quando escolhe Specific Members Only ou Specific Security Groups Only, conceda o acesso a partir do menu Actions da lista — Members para Specific Members Only ou Groups para Specific Security Groups Only, mais Agents e Owners, abrem cada um uma lista de verificação filtrável onde assinala quem tem acesso (consulte Atribuir com o seletor). Apenas um proprietário da ligação, ou um administrador da área de trabalho, pode alterar aí o acesso. Qualquer outra pessoa que possa editar ligações pode abri-las para ver quem tem acesso, numa lista só de leitura das pessoas já atribuídas. Um administrador da área de trabalho pode alterar o acesso a uma ligação de que não é proprietário, para a transmitir quando os respetivos proprietários tiverem saído.

Qualquer pessoa que possa utilizar uma ligação pode abri-la e ver as suas definições, e navegar pelos repositórios, ramos e ficheiros de uma ligação Git. As palavras-passe, os tokens e as chaves de uma ligação nunca são devolvidos a uma pessoa, sejam quais forem as suas permissões: através da API REST e do MCP, são devolvidos mascarados, como __redacted__ através de REST e <redacted> através de MCP. Apenas as contas de serviço os recebem: os agentes PlaidLink e a própria conta de serviço de um projeto, que o executor de fluxos de trabalho e o código que um fluxo de trabalho executa, como uma função definida pelo utilizador, utilizam. O início de sessão de uma pessoa nunca os recebe. Enviar __redacted__ de volta sem alterações mantém o valor armazenado.

Alterar o destino para onde uma ligação envia as suas credenciais, como o anfitrião ou o URL do token, exige que essas credenciais sejam introduzidas novamente. Caso contrário, guardar a alteração é interrompido com uma mensagem que indica as credenciais a introduzir novamente, e um teste das definições alteradas é recusado da mesma forma.

Quando navega por uma ligação Git com um URL de servidor diferente do guardado, introduza um token para esse servidor.

Uma ligação pode conter uma configuração diferente por ambiente (por exemplo, um anfitrião de desenvolvimento e um anfitrião de produção sob o mesmo nome de ligação). O seletor de ambiente na barra de ferramentas escolhe a configuração de que ambiente está a ver e a editar.

  • New Environment — adicionar um ambiente de ligação
  • Edit Environment — mudar o nome do ambiente selecionado
  • Delete Environment — remover o ambiente selecionado, depois de nenhum projeto o utilizar, nenhum passo o ter como ambiente fixo e nenhum agente o servir. Caso contrário, a mensagem indica o que ainda o utiliza. O ambiente predefinido não pode ser eliminado.

A coluna Available na lista mostra se a ligação selecionada está configurada para o ambiente escolhido.

Os ambientes são partilhados com os agentes PlaidLink, pelo que o ambiente de um projeto pode alterar o agente que executa os seus passos remotos, bem como as ligações que lê. Consulte Ambientes de agentes.

  1. Selecione a ligação na lista
  2. Clique em Edit na barra de ferramentas (ou clique com o botão direito do rato na linha)
  3. Altere os campos e clique em Update

Numa ligação Acumatica, Bill.com, Dynamics, Eclipse, HFM/FCCS, NetSuite, Workday ou Workday Financials, Edit abre o formulário próprio desse serviço. Para alterar os cabeçalhos, a autenticação ou a paginação da ligação REST subjacente, clique com o botão direito do rato na ligação e escolha Edit REST settings.

A forma de testar depende do tipo:

  • As ligações a bases de dados — Databricks, Snowflake, PostgreSQL e Redshift — têm um botão Testar ligação no editor. Abre a ligação com as credenciais que introduziu e indica o êxito (com a versão do servidor a que chegou) ou o motivo da falha, sem fechar o editor, para que possa corrigir e tentar novamente no próprio local.
  • As ligações a bases de dados com SSH também expõem um teste do túnel SSH no separador SSH Config.
  • A ligação REST genérica tem um separador Testing que dispara um pedido ad hoc através da ligação guardada.

Guarde a ligação antes de testar — os testes são executados com a configuração armazenada.

Endereços que uma ligação não consegue alcançar

Seção intitulada “Endereços que uma ligação não consegue alcançar”

Uma ligação não pode apontar para um endereço de loopback, de ligação local ou de metadados da nuvem. O PlaidCloud verifica o endereço para o qual um nome de anfitrião é resolvido quando testa a ligação e quando um passo a utiliza, e um endereço que não seja elegível falha com um erro que indica o anfitrião e o endereço para o qual foi resolvido. Os endereços da sua rede privada não são afetados.

  • Clonar — duplicar a configuração de uma ligação como base para uma nova. Consulte Clonar uma ligação.
  • Eliminar — remover a ligação selecionada a partir da barra de ferramentas (é-lhe pedida confirmação).
  • Onde é utilizado… — listar os passos de fluxos de trabalho que referenciam a ligação, para que possa ver o impacto antes de a editar ou eliminar.

O mesmo se aplica através da API REST, do JSON-RPC e do assistente de IA ou MCP: alterar as definições de uma ligação exige que seja um dos seus proprietários, ou um administrador da área de trabalho no caso de uma ligação sem proprietário. Ativar, desativar, bloquear e desbloquear uma ligação exige um proprietário ou um administrador da área de trabalho. Um pedido que indique várias ligações só se aplica quando pode alterar todas elas.