Centro de suporte da Workiva

Em integrações dinâmicas, especialmente quando você usa conectores HTTP em fluxos de trabalho automatizados (como Cadeias), é fundamental lidar com a resposta de uma chamada de API de forma eficaz. Os parâmetros de saída permitem que os usuários capturem partes essenciais de dados retornados pela API, como o corpo da resposta, os cabeçalhos da resposta e o código de status, para que esses dados possam ser usados em etapas posteriores.

Qual é o problema que você resolve?

Os parâmetros de saída são cruciais para que você crie fluxos de trabalho responsivos e inteligentes.

• Fluxos de trabalho dinâmicos: Os parâmetros de saída permitem que você personalize o que acontece em seguida com base no que a API retorna - por exemplo, extrair um token, verificar se existe um registro ou confirmar uma operação bem-sucedida.
• Automação: Ao capturar valores automaticamente, os usuários evitam a entrada manual ou a codificação, permitindo que os fluxos de trabalho sejam dimensionados com menos manutenção.
• Integrações simplificadas: Ao conectar sistemas como servidores de autenticação, CRMs ou APIs personalizadas, você terá mais facilidade, pois o conector se adapta com base nos dados que recebe.

A quem isso afeta?

• Desenvolvedores e integradores: Aqueles que criam cadeias de automação ou integrações entre sistemas.
• Analistas de dados: Aqueles que dependem de fluxos de dados precisos e em tempo real para alimentar painéis ou relatórios.
• Administradores de sistemas: Para aqueles que mantêm e solucionam problemas de integração, ter acesso aos parâmetros de saída ajuda a identificar problemas rapidamente.

O que são parâmetros de saída?

Os parâmetros de saída em um conector HTTP são usados para definir as saídas esperadas de uma solicitação HTTP, como cabeçalhos de resposta, corpo de resposta ou código de resposta. Definem os resultados esperados de uma solicitação HTTP, que podem ser reutilizados em nós ou etapas lógicas subsequentes em uma cadeia.

Exemplo de parâmetros de saída:

• Cabeçalhos da resposta: Metadados como o tipo de conteúdo, o servidor ou o status do limite de taxa.
• Corpo da resposta: O conteúdo real retornado pela API, normalmente em formato JSON ou XML.
• Código de resposta: Indica que você obteve sucesso (200), erro do cliente (400), erro do servidor (500), etc.

Exemplo: Capturando um token de acesso

Suponha que uma API retorne um token como este:

{ "token_type": "Bearer", "expires_in": 600, "access_token": "<access_token_string>", "escopo": "graph:write graph_api|r permissões|w ..." }

Você pode definir access_token como um parâmetro de saída e, em seguida, passá-lo para a próxima etapa (por exemplo, para autenticar outra chamada de API).

Por que o corpo da resposta é necessário?

No Response Body (Corpo da resposta), você normalmente encontra as informações mais importantes da API. Você pode incluir, mas não está limitado a:

• IDs de registros recém-criados
• Tokens de autenticação
• Você pode consultar resultados de consultas ou cargas de dados.

Sem acessar o corpo da resposta, você fica limitado aos metadados, o que restringe o dinamismo do seu fluxo de trabalho. 

Agora você pode obter o access_token disponível na lista suspensa Response (Resposta).

Cenários comuns de tratamento de erros

Problemas típicos que você pode encontrar ao trabalhar com parâmetros de saída:

• Erro: parâmetro de saída indefinido

  Causa e correção: A estrutura do corpo da resposta foi alterada ou está aninhada. Confirme o caminho JSON correto para o campo.

• Erro: 401 Unauthorized (Não autorizado)

  Cause & Fix: Token ausente ou expirado. Verifique se o token foi capturado e passado corretamente.

• Erro: 500 Internal Server Error (Erro interno do servidor 500)

  Causa e correção: Problema no servidor ou carga inválida da solicitação. Verifique o corpo da resposta para obter mais contexto.

• Erro: JSON inválido

  Causa e correção: A API retorna uma resposta malformada. Você pode usar um bloco Try-Catch ou validar a saída antes de analisar.

O que é um token de portador e por que ele é necessário?

Um token de portador é um tipo de token de acesso usado na autenticação do OAuth 2.0. Ele autoriza um usuário ou aplicativo a acessar uma API. É chamado de "Bearer" porque você "carrega" o token no cabeçalho de sua solicitação HTTP.

Exemplo de cabeçalho:

Autorização: Bearer <access_token>

Esse token é mais seguro do que a autenticação básica porque:

• Ele expira, reduzindo o risco de vazamentos de tokens.
• Você pode carregar escopos e permissões.
• Ele separa a autenticação da autorização.

Por que não usar apenas a autenticação básica?

Embora a autenticação básica envie um nome de usuário e uma senha codificados em cada solicitação, ela:

• É menos segura - as credenciais podem ser reutilizadas ou interceptadas.
• Você não pode expirar ou acessar facilmente o escopo.
• Você não tem controle de permissões baseado em token.

Os tokens de portador suportam expiração de token, atualização e permissões granulares, o que os torna a melhor opção para APIs modernas e segurança de nível empresarial.