Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Dica
Recomendado: Comece com o Work IQ Dev Tools para cenários de agente declarativo e plug-in pro-código suportados. Consulte o guia de início rápido do WIQD. As instruções baseadas em toolkits permanecem disponíveis para projetos e fluxos de trabalho existentes que o exigem. Verifique o suporte à capacidade e à experiência de destino antes de escolher uma ferramenta: o WIQD não tem como alvo agentes de mecanismo personalizados.
Algumas APIs usam chaves de API para autorização. Uma chave de API é um segredo compartilhado que o cliente inclui nas solicitações de API para autenticar e obter acesso. Os plug-ins de API suportam o envio da chave de API de três maneiras:
- Como um token ao portador
Authorizationno cabeçalho - Como um valor num cabeçalho personalizado
- Como parâmetro de consulta
Observação
Para ações de agente declarativo, a autenticação de chave de API aplica-se a plug-ins de API criados a partir de um documento OpenAPI, não a plug-ins MCP. Para o plug-in MCP de um agente, use OAuth 2.0 (incluindo registro dinâmico de cliente) ou Microsoft Entra SSO. Uma conexão MCP remota no nível do pacote usa uma configuração diferente; Consulte Autenticação no manifesto do aplicativo.
Configure a autenticação da chave API em duas etapas: adicione a chave API ao documento OpenAPI e crie a configuração da autenticação da chave API.
Etapa 1: Adicionar a chave da API ao documento OpenAPI
Microsoft 365 Copilot determina como enviar a chave da API com base na securitySchemes entrada no documento OpenAPI.
Token ao portador
Se sua API aceitar a chave da API como um token de portador, habilite a autenticação do portador em seu documento OpenAPI. Para obter mais informações, consulte Autenticação do portador.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
Cabeçalho personalizado
Se sua API aceitar a chave da API em um cabeçalho personalizado, habilite a autenticação da chave da API no documento OpenAPI com a in propriedade definida como header e a name propriedade definida para o nome do cabeçalho. Para obter mais informações, consulte Chaves de API.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
Parâmetro de consulta
Se sua API aceitar a chave API em um parâmetro de consulta, habilite a autenticação de chave de API em seu documento OpenAPI definindo a in propriedade como query e a name propriedade para o nome do parâmetro de consulta. Para obter mais informações, consulte Chaves de API.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key
Etapa 2: criar a configuração de autenticação de chave de API
A autenticação de chave de API depende de uma configuração de autenticação (auth config) - um registro armazenado no armazenamento de tokens do Microsoft Enterprise que Microsoft 365 Copilot usa para enviar a chave de API quando seu plug-in chama a API. Comece com o WIQD para um projeto pro-code suportado. Os procedimentos do toolkit e do portal do programador do Microsoft Teams permanecem disponíveis como alternativas. A habilidade de desenvolvedor do agente declarativo não oferece suporte à autenticação por chave de API, pois cria plug-ins MCP.
Use Work IQ Dev Tools (recomendado)
Para um manifesto de plug-in de API existente, use wiqd agent add auth com --plugin-manifest, --auth-namee --auth-type api-key. Defina --api-key-in como header ou query e --api-key-name para o nome do seu esquema de segurança OpenAPI. Se a API aceitar sua chave como um token de portador, selecione --auth-type bearer-token.
Ao adicionar uma ação a partir de um documento OpenAPI, wiqd agent add action aceita --api-key para credenciais de chave de API ou portador. O comando documenta os espaços reservados do ambiente quando o valor é omitido. Siga a manipulação de credenciais do comando selecionado e conclua o fluxo de trabalho de provisionamento do projeto. Essas opções de chave de API não estabelecem suporte de chave de API para o plug-in MCP de um agente.
Utilizar o Microsoft 365 Agents Toolkit
Quando cria um plug-in API a partir de um documento OpenAPI existente no Microsoft 365 Agents Toolkit, o toolkit regista a chave API, cria a configuração de autenticação e atualiza o manifesto do plug-in por si. Você deve definir a securitySchemes propriedade em seu documento OpenAPI.
Utilizar o portal do programador do Teams
O registo no portal do programador do Teams é opcional se utilizar o Agents Toolkit. Use-o para criar a configuração de autenticação manualmente ou para gerenciar uma configuração de autenticação que o Agents Toolkit já criou.
Abra o portal do programador do Teams. Selecione Ferramentas ->registro de chave API.
Se você não tiver registros existentes, selecione Criar uma chave de API. Se você tiver registros existentes, selecione Nova chave de API.
Selecione Adicionar segredo e insira a chave API.
Preencha os seguintes campos.
- Nome da chave API: um nome amigável para o seu registro.
-
URL base: o URL base da sua API. Esse valor deve corresponder a uma entrada na
serversmatriz em seu documento OpenAPI. - Inquilino alvo: limite o acesso à API ao seu inquilino principal ou permita qualquer inquilino.
- Aplicação Target Teams: selecione Qualquer aplicação Teams se não souber o ID final da aplicação. Depois de publicar seu aplicativo, vincule esse registro com seu ID de aplicativo publicado.
Selecione Salvar.
Concluir o registo gera um ID de configuração de autenticação (atualmente denominado ID de registo da chave API no portal do programador do Teams).
Adicione o ID de configuração de autenticação ao manifesto do plug-in
Quando cria manualmente a configuração da autenticação no portal do programador do Teams, defina a type propriedade do objeto de autenticação de tempo de execução como ApiKeyPluginVault, e o reference_id ID de configuração da autenticação. O Agents Toolkit faz isso por você.
"auth": {
"type": "ApiKeyPluginVault",
"reference_id": "auth config ID"
},