O criador de integrações oferece suporte a tipos de autorização padrão, incluindo chaves de API, tokens do portador, nome de usuário e senha e OAuth 2.0. No entanto, dependendo das necessidades e fluxos de trabalho da sua organização, a autorização padrão pode não ser suficiente. É por isso que o criador de integrações também oferece suporte a um tipo de integração apenas para autenticação personalizada, que funciona com as soluções de autenticação e autorização da sua organização.
Este artigo contém os seguintes tópicos:
- Sobre a autorização personalizada
- Configuração da autorização personalizada
- Criação da integração de dados
- Teste da autorização personalizada
Sobre a autorização personalizada
A integração apenas para autenticação personalizada faz uma solicitação de token e sua expiração, que são então repassadas para a integração de dados ou principal para autorização, a qual, por sua vez, faz a solicitação dos dados.
Em resumo, o fluxo de autorização personalizada é o seguinte:
- Solicitação de autorização. A integração configurada somente para autenticação envia uma solicitação ao servidor, pedindo permissão para recuperar um token de acesso. Se o servidor autenticar a solicitação (proveniente de agentes de IA), ele autoriza a recuperação do token de acesso e, se disponível, sua expiração.
- Gerenciamento do token. Após o servidor responder com o token de acesso, a integração armazena duas informações essenciais: o próprio parâmetro do token e seu parâmetro expiresIn, que determina por quanto tempo o token é válido.
- Transferência do token para a integração de dados. Esses dois parâmetros (token e expiresIn) são passados para a próxima etapa, que é a integração de dados. O token é usado para autenticar solicitações subsequentes feitas pela integração de dados. O token é definido e gerenciado internamente, e nunca é exposto aos dados da sessão ou da conversa.
- Solicitação de autorização personalizada para dados. Com o token de acesso inserido, a integração de dados está agora autorizada a recuperar os dados necessários, que são utilizados para enriquecer a conversa.
O fluxograma abaixo ilustra o fluxo da autorização personalizada.
Configuração da autorização personalizada
Configure a autorização personalizada como parte do processo normal de criar uma integração no criador de integrações.
Como configurar a autorização personalizada no criador de integrações
- No menu principal, clique em Integrações de API.
- No canto superior direito, clique em Adicionar integração.
- Na janela Adicionar integração:
- No campo Nome da integração, dê um nome descritivo à sua integração.
- (Opcional) No campo Descrição, insira uma descrição da integração que o ajude a lembrar para que ela serve.
- Selecione Configurar como uma integração "apenas autenticação".
- Clique em Salvar.
- Em Cenários, na barra lateral esquerda passe o cursor sobre Falha, selecione o menu de opções (
) e selecione Apagar. Você só precisa de cenários de Sucesso para autorização personalizada. Não é possível apagar cenários Fallback.
- Na página de cenários Sucesso, crie dois parâmetros de sessão (clicando no botão +) com os seguintes detalhes:
- token
- Chave: token (deve ser escrito exatamente assim)
- Consulta: Insira um valor que defina o token. Por exemplo: data.access_token
- expiresIn
- Chave: expiresIn (deve ser escrito exatamente assim)
-
Consulta: Insira um valor que defina a expiração do token. Por exemplo: data.expires_in
A expiração do token pode não estar incluída na sua resposta de dados. Nesse caso, defina um valor fixo (em segundos) de sua escolha. Por exemplo: 3600
Recomendamos a definição de uma expiração para o token. Se você encontrar um erro durante o teste, esse é o tempo que você precisará esperar até que um novo token seja emitido. Sem a expiração, o token é definido indefinidamente, o que significa que você não poderá emitir um novo durante a resolução de problemas.
- token
- Clique em Salvar.
Criação da integração de dados
Em seguida, crie a integração de dados que usará a integração de autenticação personalizada que você criou nas etapas anteriores. Faça isso como você normalmente faria ao criar uma nova integração. Para obter ajuda, consulte Criador de integrações explicado.
Como criar a integração de dados
- Na barra lateral esquerda, em Ambientes, selecione um ambiente (como Production).
- Na aba Autorização, no campo de lista suspensa Tipo de autorização, selecione Personalizado.
- No campo de lista suspensa Integração de autorização da API, selecione a integração somente para autenticação personalizada que você criou acima.
- Selecione a aba Cabeçalhos e clique em Adicionar cabeçalho.
- Preencha os seguintes campos:
- Chave: Authorization
-
Valor: Bearer {{apiToken}} (deve ser escrito exatamente assim)
- Clique em Salvar.
Teste da autorização personalizada
Teste a integração de autenticação personalizada após a configuração. Para obter ajuda, consulte Funcionalidade de teste.
Solução de problemas statusCode: null
Além disso, ao testar sua integração, você pode encontrar uma mensagem "statusCode: null", como mostrado na imagem abaixo:
Primeiro, verifique novamente se sua integração de autenticação personalizada foi configurada corretamente de acordo com as etapas anteriores.
Em seguida, observe onde o erro está ocorrendo. Se o problema estiver na integração de autenticação, provavelmente algo não está configurado corretamente ou a URL para a qual você está fazendo a solicitação pode estar incorreta. Nesse caso, recomendamos que você consulte os engenheiros da sua empresa, pois eles poderão fornecer mais informações sobre o problema.
Se você seguiu as etapas anteriores e ainda está encontrando esse erro, espere até que o token expire e tente novamente.
Se você já tentou todas essas etapas de solução de problemas e a integração ainda não está funcionando, entre em contato com seu CSM para obter assistência adicional.