Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você 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.
O TypeSpec for Microsoft 365 Copilot suporta vários métodos de autenticação para proteger plug-ins de API e integrar com serviços externos. Os tipos de autenticação suportados incluem:
- Sem autenticação para pontos finais públicos
- Autenticação de chave de API para acesso simples baseado em tokens
- Fluxo de código de autorização OAuth2 para integrações seguras que não sejam da Microsoft
- Microsoft Entra autenticação de início de sessão único (SSO) para integração de identidade do Microsoft 365
Observação
Esta documentação abrange cenários de autenticação específicos Microsoft 365 Copilot. Para obter documentação abrangente de autenticação TypeSpec, incluindo todos os decoradores e padrões de autenticação nativos, consulte a documentação TypeSpec sobre autenticação.
Sem autenticação (anónimo)
Pontos finais públicos que não requerem credenciais de autenticação. A API não requer nada específico. Sem @useAuth decoradores, todas as APIs são consideradas anônimas.
Exemplo
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
namespace API {
// Endpoints
}
Autenticação de chave de API
Autenticação usando chaves de API ou tokens de acesso pessoal aplicados a namespaces inteiros. Use o nativo ApiKeyAuth de TypeSpec.
Exemplo
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">)
namespace API {
// Endpoints
}
O Microsoft 365 Agents Toolkit pode registar automaticamente a sua chave API e também adiciona a apiKey/register ação para m365agents.yml no seu projeto Agents Toolkit.
# m365agents.yml
# After the typespec/compile step
- uses: apiKey/register
with:
name: ApiKeyAuth
appId: ${{TEAMS_APP_ID}}
apiSpecPath: ./appPackage/.generated/api-openapi.yml
writeToEnvironmentFile:
registrationId: APIKEYAUTH_REGISTRATION_ID
O exemplo Gerenciar reparos usando Microsoft 365 Copilot mostra o uso da autenticação por chave de API.
Fluxo de código de autorização OAuth2
Permissões delegadas pelo utilizador para aceder aos dados do utilizador a partir de um serviço protegido por OAuth 2.0. Use o nativo OAuth2Auth de TypeSpec. Atualize o authorizationUrl, tokenUrl, refreshUrle scopes com base na API específica com a qual está a integrar.
Saiba como criar automaticamente o registro do aplicativo Microsoft Entra usando o Agents Toolkit e atualizar o registro do aplicativo Microsoft Entra quando o registro for concluído.
Exemplo
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(OAuth2Auth<[{
type: OAuth2FlowType.authorizationCode;
authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
tokenUrl: "https://contoso.com/oauth2/v2.0/token";
refreshUrl: "https://contoso.com/oauth2/v2.0/token";
scopes: ["scope-1", "scope-2"];
}]>)
namespace API {
// Endpoints
}
O Agents Toolkit pode registrar automaticamente sua configuração OAuth2 e também adiciona a oauth/register ação para m365agents.yml em seu projeto do Agents Toolkit.
# m365agents.yml
# After the typespec/compile step
- uses: oauth/register
with:
name: OAuth2Auth
appId: ${{TEAMS_APP_ID}}
clientId: ${{AAD_APP_CLIENT_ID}}
clientSecret: ${{SECRET_AAD_APP_CLIENT_SECRET}}
apiSpecPath: ./appPackage/.generated/api-openapi.yml
flow: authorizationCode
writeToEnvironmentFile:
configurationId: OAUTH2AUTH_REGISTRATION_ID
O Agente de Tarefas usando TypeSpec para Microsoft 365 Copilot que se conecta ao exemplo de APIs do Microsoft Graph destaca o uso de OAuth2 com fluxo de código de autorização.
Microsoft Entra autenticação SSO
Autenticação que aplica a sessão do Microsoft 365 existente do utilizador para cenários de integração nativa. Para concluir o registro SSO, use o fluxo regular OAuth2Auth e execute as etapas manuais.
Usando configurações de autenticação registradas
Em cenários de produção, registe e faça a gestão das credenciais de autenticação através do Portal do Programador do Microsoft Teams, em vez de as incorporar diretamente no código TypeSpec. Utilize o @authReferenceId decorador para referenciar configurações de autenticação pré-registadas através dos respetivos identificadores exclusivos. Essa abordagem fornece uma maneira segura de lidar com credenciais sem expor informações confidenciais em sua base de código.
Ao usar @authReferenceIdo , especifique a ID de registro dos registros de cliente OAuth ou registros de chave de API configurados no Portal do Desenvolvedor. Esta abordagem separa a configuração da autenticação do código, permitindo melhores práticas de segurança e uma gestão de credenciais mais fácil em diferentes ambientes.
Exemplo
// Reference to OAuth2 client registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
// Endpoints
}
@authReferenceId("NzFmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IyM5NzQ5Njc3Yi04NDk2LTRlODYtOTdmZS1kNDUzODllZjUxYjM=")
model Auth is OAuth2Auth<[{
type: OAuth2FlowType.authorizationCode;
authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
tokenUrl: "https://contoso.com/oauth2/v2.0/token";
refreshUrl: "https://contoso.com/oauth2/v2.0/token";
scopes: ["scope-1", "scope-2"];
}]>
// Reference to API key registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
// Endpoints
}
@authReferenceId("5f701b3e-bf18-40fb-badd-9ad0b60b31c0")
model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">