Conector Personalizado do Copilot Studio Retorna 401 Não Autorizado: Correção

Ao criar um conector personalizado no Copilot Studio, você pode ver um erro 401 Não Autorizado quando o conector tenta chamar uma API externa. Esse erro significa que a API rejeitou a requisição porque nenhuma credencial de autenticação válida foi fornecida. A causa raiz é quase sempre uma incompatibilidade entre o método de autenticação configurado no conector e o que a API espera. Este artigo explica por que o erro 401 ocorre e fornece correções passo a passo para os cenários de autenticação mais comuns.

Por que o Erro 401 Não Autorizado Ocorre

O erro 401 Não Autorizado é um código de status HTTP que significa que o servidor da API recebeu sua requisição, mas não a processará porque a autenticação está ausente, inválida ou expirada. Em conectores personalizados do Copilot Studio, isso acontece quando a configuração de autenticação não corresponde ao que a API externa espera.

Existem três causas raiz comuns:

Tipo de Autenticação Errado

Cada API suporta um método de autenticação específico. Se você selecionar Chave de API no conector, mas a API esperar OAuth 2.0, o servidor rejeitará a requisição com um erro 401. O conector deve usar o método exato definido na documentação da API.

Credenciais ou Token Incorretos

Mesmo com o tipo de autenticação correto, as credenciais reais devem ser válidas. Uma chave de API pode ter expirado, um token OAuth pode ter sido revogado ou uma combinação de usuário e senha pode estar errada. O Copilot Studio não valida credenciais até que o conector seja testado ou usado em uma conversa.

Parâmetros Ausentes ou com Nome Incorreto

Para autenticação por Chave de API, o conector deve enviar a chave no cabeçalho ou parâmetro de consulta correto. Por exemplo, se a API espera a chave em um cabeçalho chamado X-API-Key, mas o conector a envia em Authorization, a API retorna 401. O mesmo se aplica a escopos OAuth, tipos de concessão e endpoints de token.

Passos para Corrigir o Erro 401 Não Autorizado

Siga estes passos em ordem. Cada passo aborda uma das causas raiz acima.

Passo 1: Verifique os Requisitos de Autenticação da API

1. Abra a documentação da API
   Localize a documentação oficial da API à qual você está se conectando. Procure pela seção de Autenticação. Anote o tipo de autenticação exato — Chave de API, OAuth 2.0, Autenticação Básica ou outro método.
2. Registre os nomes exatos dos parâmetros
   Para Chave de API, anote o nome do cabeçalho ou do parâmetro de consulta. Para OAuth 2.0, anote a URL de autorização, URL do token, ID do cliente, segredo do cliente, escopos e tipo de concessão. Para Autenticação Básica, observe que a API espera uma string usuário:senha codificada em Base64 enviada no cabeçalho Authorization.

Passo 2: Verifique a Configuração de Autenticação do Conector

1. Entre no Copilot Studio
   Acesse https://copilotstudio.microsoft.com e abra seu copiloto.
2. Navegue até Conectores personalizados
   Selecione Configurações no canto superior direito e escolha Conectores personalizados. Encontre o conector que está retornando o erro 401 e clique em Editar.
3. Revise a guia Autenticação
   Clique na guia Autenticação. Compare o tipo de autenticação selecionado com a documentação da API. Se não corresponderem, altere o tipo de autenticação para o correto.
4. Atualize os parâmetros
   Para Chave de API, insira o nome exato do cabeçalho ou parâmetro de consulta da documentação. Para OAuth 2.0, insira a URL de autorização, URL do token, ID do cliente, segredo do cliente e escopos exatamente como especificado. Para Autenticação Básica, insira o usuário e a senha.

Passo 3: Teste o Conector com uma Operação Simples

1. Crie uma operação de teste
   No editor do conector, vá para a guia Definição e adicione uma nova operação que faça uma requisição GET simples a um endpoint público da API que exija o mínimo de dados.
2. Clique em Testar operação
   Selecione a operação de teste e clique em Testar operação na barra de ferramentas. Uma caixa de diálogo aparece mostrando a requisição e a resposta. Se a resposta for 200 OK, a autenticação está configurada corretamente. Se você ainda vir 401, prossiga para o próximo passo.

Passo 4: Valide as Credenciais Fora do Copilot Studio

1. Use uma ferramenta como Postman ou curl
   Envie a mesma requisição para a API usando o mesmo método de autenticação e credenciais. Se você obtiver uma resposta 200, as credenciais são válidas e o problema está na configuração do conector. Se obtiver 401, as credenciais estão erradas ou expiradas.
2. Renove ou substitua as credenciais
   Se as credenciais forem inválidas, gere uma nova chave de API, atualize o token OAuth ou redefina a senha. Em seguida, atualize o conector com as novas credenciais.

Passo 5: Verifique Restrições de Política ou Escopo

1. Revise as políticas de acesso da API
   Algumas APIs restringem o acesso com base no endereço IP, agente do usuário ou frequência de requisições. Certifique-se de que as requisições do conector do Copilot Studio não sejam bloqueadas por tais políticas.
2. Verifique os escopos do OAuth
   Para OAuth 2.0, o token deve incluir os escopos exigidos pelo endpoint da API. Adicione os escopos ausentes na guia Autenticação do conector e regenere o token.

Se o Erro 401 Persistir Após a Correção Principal

Às vezes, o erro continua mesmo depois de você verificar o tipo de autenticação e as credenciais. Os problemas a seguir são menos comuns, mas igualmente importantes de verificar.

O Conector Personalizado Usa uma Referência de Conexão Compartilhada

Se o seu conector usa uma referência de conexão compartilhada entre vários ambientes, as credenciais armazenadas nessa referência podem estar desatualizadas. Vá para o centro de administração do Power Platform, encontre a referência de conexão e atualize as credenciais. Em seguida, teste novamente o conector no Copilot Studio.

Gateway de API ou Proxy Adiciona Autenticação

Algumas APIs ficam atrás de um gateway que exige sua própria autenticação, como o Azure API Management. Nesse caso, o conector personalizado deve incluir tanto a autenticação do gateway quanto a autenticação da API de back-end. Configure o conector para enviar as credenciais do gateway no cabeçalho da requisição e as credenciais do back-end no corpo ou em um cabeçalho separado.

Token OAuth Expira Durante uma Conversa

Se o conector funciona durante o teste, mas retorna 401 após alguns minutos em um copiloto ativo, o token OAuth pode ter expirado. Configure o conector para usar um token de atualização se a API suportar. Na guia Autenticação, ative a opção de token de atualização e forneça a URL do token de atualização e quaisquer parâmetros necessários.

Métodos de Autenticação do Conector Personalizado do Copilot Studio: Comparação

Item	Chave de API	OAuth 2.0	Autenticação Básica
Descrição	Uma chave estática enviada em um cabeçalho ou parâmetro de consulta	Delegação baseada em token usando endpoints de autorização e token	Usuário e senha enviados como uma string codificada em Base64
Caso de uso comum	APIs públicas simples, serviços meteorológicos, gateways de pagamento	Microsoft Graph, Salesforce, APIs do Google, APIs de mídias sociais	APIs legadas, APIs corporativas internas com segurança básica
Expiração da credencial	Geralmente estática, mas pode ser rotacionada	Token expira em minutos a horas; token de atualização pode estender	Estática até que a senha seja alterada
Configuração no Copilot Studio	Selecione Chave de API, insira o nome do cabeçalho e o valor da chave	Selecione OAuth 2.0, insira todas as URLs de endpoint, ID do cliente, segredo, escopos	Selecione Autenticação Básica, insira usuário e senha
Abordagem de teste	Teste com uma requisição GET usando a chave	Teste com uma requisição GET; o token deve ser válido e com escopo	Teste com uma requisição GET; as credenciais devem estar corretas

Agora você pode identificar e corrigir o erro 401 Não Autorizado no seu conector personalizado do Copilot Studio. Comece verificando os requisitos de autenticação da API e comparando-os com a guia Autenticação do conector. Após atualizar a configuração, sempre teste com uma operação simples para confirmar a correção. Para conectores OAuth 2.0, considere ativar tokens de atualização para evitar a expiração do token durante conversas prolongadas.