Pular para o conteúdo

Criar e gerenciar uma conexão

Uma conexão é uma configuração salva que permite ao PlaidCloud acessar um sistema externo — um banco de dados, data lake, ERP, API REST, serviço de nuvem ou provedor de Git. As etapas de fluxo de trabalho referenciam a conexão pelo nome, de modo que os detalhes do endpoint e as credenciais ficam em um só lugar e são reutilizados em todas as etapas e projetos que precisam deles.

As conexões são gerenciadas em Tools > Connections.

  1. Abra Tools > Connections
  2. Clique em New Connection na barra de ferramentas e escolha no menu o sistema ao qual você deseja se conectar
  3. Preencha o formulário da conexão (as guias e os campos variam conforme o tipo — consulte Formulário da conexão abaixo)
  4. Clique em Create para salvar

A nova conexão aparece na lista, com você como proprietário.

As conexões do Acumatica, Bill.com, Dynamics, Eclipse, HFM/FCCS, NetSuite, Workday e Workday Financials são salvas como conexões REST, e a coluna Tipo da lista mostra o tipo do próprio serviço. Cada uma abre em um formulário próprio para criar, editar e escolher em etapas. Os cabeçalhos, a autenticação e a paginação ficam em Edit REST settings, que você acessa pelo menu de clique com o botão direito (consulte Editar uma conexão).

A maioria das conexões abre um formulário com várias guias. As guias exatas dependem do tipo, mas normalmente você verá:

  • Configuração da conexão (ou Detalhes da conexão para REST) — o Name da conexão, um Memo opcional, o host/porta/banco de dados (ou host/tipo de autenticação para REST), a alternância Usage (Active) e o Security Model. Em uma conexão de banco de dados, as credenciais ficam aqui, em um grupo Credenciais de autenticação; em uma conexão REST, elas têm a própria guia Autenticação.
  • Configuração de SSL — Use SSL mais o modo SSL e certificados opcionais de cliente/raiz para uma conexão criptografada.
  • Configuração de SSH — Use SSH mais o host bastião, a porta, o usuário e a chave para tunelar a conexão por um host de salto SSH.

Os campos de senha, token e outras credenciais são somente de gravação: aparecem em branco quando você reabre uma conexão salva, e deixá-los em branco ao salvar mantém o segredo armazenado. Digite um valor novamente somente quando quiser alterá-lo. Isso vale para a chave de API, o segredo do cliente OAuth e o token de atualização OAuth de uma conexã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, uma URL de webhook de entrada do Slack ou do Teams — são somente de gravação da mesma forma e ficam mascaradas enquanto você as digita ou cola. Uma substituição composta apenas de espaços é recusada em vez de ser salva sobre a credencial armazenada; limpe o campo para manter o valor salvo. A chave de cliente SSL e a chave privada SSH de uma conexão SQL ou Git também são somente de gravação, mas permanecem visíveis enquanto você as digita. Todos os outros campos mostram o valor real salvo em todos os lugares em que a conexão é exibida, no editor e pela API, inclusive campos que parecem sensíveis pelo nome (o sinalizador somente leitura de um banco de dados, um identificador de conta, um esquema, um nome de host) — somente uma credencial de verdade é mascarada ou ocultada.

Pela API REST e pelo MCP, um campo de credencial segue a mesma regra do editor: envie uma string vazia e o PlaidCloud mantém o valor armazenado; envie null para limpá-lo. Todo campo que não seja de credencial ainda é limpo quando você o envia em branco.

Os campos obrigatórios são validados ao salvar; se algo estiver faltando, o formulário muda para a guia que contém o primeiro campo inválido e o sinaliza.

O Security Model de uma conexão controla quem no espaço de trabalho pode usá-la:

Opção Quem pode usar a conexão
Privada (somente proprietários) Apenas os proprietários.
Somente membros específicos Os proprietários mais uma lista explícita de membros.
Somente grupos de segurança específicos Os proprietários mais os membros de grupos de segurança nomeados.
Todos os membros do espaço de trabalho Todos no espaço de trabalho.

Ao escolher Specific Members Only ou Specific Security Groups Only, conceda o acesso pelo menu Actions da lista — Members para Specific Members Only ou Groups para Specific Security Groups Only, mais Agents e Owners, cada um abre uma lista de verificação filtrável em que você marca quem tem acesso (consulte Atribuir com o seletor). Somente um proprietário da conexão ou um administrador do espaço de trabalho pode alterar o acesso ali. Qualquer outra pessoa que possa editar conexões pode abri-las para ver quem tem acesso, em uma lista somente leitura das pessoas já atribuídas. Um administrador do espaço de trabalho pode alterar o acesso a uma conexão da qual não é proprietário, para repassá-la quando seus proprietários saíram.

Qualquer pessoa que possa usar uma conexão pode abri-la e ver suas configurações, além de navegar pelos repositórios, branches e arquivos de uma conexão Git. As senhas, tokens e chaves de uma conexão nunca são retornados a uma pessoa, quaisquer que sejam as permissões dela: pela API REST e pelo MCP eles voltam mascarados, como __redacted__ na REST e <redacted> no MCP. Somente contas de serviço os recebem: os agentes do PlaidLink e a conta de serviço do próprio projeto, que o executor de fluxos de trabalho e o código executado por um fluxo de trabalho, como uma função definida pelo usuário, usam. O login de uma pessoa nunca os recebe. Enviar __redacted__ de volta sem alteração mantém o valor armazenado.

Alterar para onde uma conexão envia as credenciais, como o host ou a URL do token, exige que essas credenciais sejam digitadas novamente. Caso contrário, salvar a alteração é interrompido com uma mensagem que nomeia as credenciais a digitar novamente, e um teste das configurações alteradas é recusado da mesma forma.

Ao navegar por uma conexão Git com uma URL de servidor diferente da salva, informe um token para esse servidor.

Uma conexão pode ter uma configuração diferente por ambiente (por exemplo, um host de desenvolvimento e um host de produção sob um mesmo nome de conexão). O seletor de ambiente na barra de ferramentas escolhe de qual ambiente você está visualizando e editando a configuração.

  • New Environment — adiciona um ambiente de conexão
  • Edit Environment — renomeia o ambiente selecionado
  • Delete Environment — remove o ambiente selecionado, quando nenhum projeto o usa, nenhuma etapa o tem como ambiente fixo e nenhum agente o atende. Caso contrário, a mensagem informa o que ainda o usa. O ambiente padrão não pode ser excluído.

A coluna Available da lista mostra se a conexão selecionada está configurada para o ambiente escolhido.

Os ambientes são compartilhados com os agentes do PlaidLink, de modo que o ambiente de um projeto pode alternar o agente que executa suas etapas remotas, além das conexões que ele lê. Consulte Ambientes de agentes.

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

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

A forma de testar depende do tipo:

  • As conexões de banco de dados — Databricks, Snowflake, PostgreSQL e Redshift — têm um botão Testar conexão no editor. Ele abre a conexão com as credenciais que você informou e relata o sucesso (com a versão do servidor que foi alcançada) ou o motivo da falha, sem fechar o editor, para que você possa corrigir e tentar novamente no mesmo lugar.
  • As conexões de banco de dados com SSH também oferecem um teste do túnel SSH na guia SSH Config.
  • A Conexão REST genérica tem uma guia Testing que dispara uma solicitação ad hoc pela conexão salva.

Salve a conexão antes de testar — os testes são executados na configuração armazenada.

Uma conexão não pode apontar para um endereço de loopback, link-local ou de metadados de nuvem. O PlaidCloud verifica o endereço para o qual um nome de host é resolvido quando você testa a conexão e quando uma etapa a usa, e um endereço que não se qualifica falha com um erro que nomeia o host e o endereço para o qual ele foi resolvido. Os endereços da sua rede privada não são afetados.

  • Clonar — duplica a configuração de uma conexão como base para uma nova. Consulte Clonar uma conexão.
  • Excluir — remove a conexão selecionada pela barra de ferramentas (você precisa confirmar).
  • Onde é usado… — lista as etapas de fluxo de trabalho que referenciam a conexão, para que você veja o impacto antes de editá-la ou excluí-la.

O mesmo vale pela API REST, pelo JSON-RPC e pelo assistente de IA ou MCP: alterar as configurações de uma conexão exige que você seja um de seus proprietários, ou um administrador do espaço de trabalho no caso de uma conexão sem proprietário. Ativar, desativar, bloquear e desbloquear uma conexão exigem um proprietário ou um administrador do espaço de trabalho. Uma solicitação que nomeia várias conexões só é aplicada quando você pode alterar todas elas.