Exercício - Integrar um plug-in de API com uma API protegida com uma chave

9 minutos

Os plug-ins de API para o Microsoft 365 Copilot permitem a integração com APIs protegidas por uma chave. Para manter a chave de API segura, registre-a no cofre do Teams. Em tempo de execução, o Microsoft 365 Copilot executa o plug-in, recupera a chave de API do cofre e a usa para chamar a API. Seguindo esse processo, a chave de API permanece segura e nunca é exposta ao cliente.

Criar um novo projeto

Comece criando um novo plug-in de API para o Microsoft 365 Copilot. Abra o Visual Studio Code.

No Visual Studio Code:

Na Barra de Atividades (barra lateral), ative a extensão Microsoft 365 Agents Toolkit.
No painel de extensão Microsoft 365 Agents Toolkit , escolha Criar um novo aplicativo.
Na lista de modelos de projeto, escolha Copilot Agent.
Na lista de recursos do aplicativo, escolha Declarative Agent.
Escolha a opção Adicionar plug-in .
Escolha a opção Iniciar com uma nova API .
Na lista de tipos de autenticação, escolha Chave de API (Autenticação de Token de Portador).
Como linguagem de programação, escolha TypeScript.
Escolha uma pasta para armazenar o projeto.
Nomeie seu projeto da-repairs-key.

O Microsoft 365 Agents Toolkit cria um novo projeto que inclui um agente declarativo, um plug-in de API e uma API protegida por uma chave.

Examinar a configuração de autenticação de chave de API

Antes de continuar, examine a configuração de autenticação de chave de API no projeto gerado.

Examinar a definição de API

Primeiro, veja como a autenticação de chave de API é definida na definição de API.

No Visual Studio Code:

Abra o arquivo appPackage/apiSpecificationFile/repair.yml . Este arquivo contém a definição de OpenAPI para a API.
Na seção components.securitySchemes , observe a propriedade apiKey :
```
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
```
A propriedade define um esquema de segurança que usa a chave de API como um token de portador no cabeçalho da solicitação de autorização.

Localize a propriedade paths./repairs.get.security . Observe que ele faz referência ao esquema de segurança apiKey .

[...]
paths:
  /repairs:
    get:
      operationId: listRepairs
      [...]
      security:
        - apiKey: []
[...]

Examine a implementação da API

Em seguida, veja como a API valida a chave de API em cada solicitação.

No Visual Studio Code:

Abra o arquivo src/functions/repairs.ts .
Na função de manipulador de reparos , localize a seguinte linha que rejeita todas as solicitações não autorizadas:
```
if (!isApiKeyValid(req)) {
  // Return 401 Unauthorized response.
  return {
    status: 401,
  };
} 
```
A função isApiKeyValid é implementada ainda mais no arquivo repairs.ts:
```
function isApiKeyValid(req: HttpRequest): boolean {
  const apiKey = req.headers.get("Authorization")?.replace("Bearer ", "").trim();
  return apiKey === process.env.API_KEY;
}
```
A função verifica se o cabeçalho de autorização contém um token de portador e o compara com a chave de API definida na variável de ambiente API_KEY .

Este código mostra uma implementação simplista da segurança de chave de API, mas ilustra como a segurança de chave de API funciona na prática.

Examinar a configuração da tarefa do cofre

Neste projeto, você usará o Microsoft 365 Agents Toolkit para adicionar a chave de API ao cofre. O Microsoft 365 Agents Toolkit registra a chave de API no cofre usando uma tarefa especial na configuração do projeto.

No Visual Studio Code:

Abra o arquivo ./teampsapp.local.yml .
Na seção provisionar , localize a tarefa apiKey/register .
```
# Register API KEY
- uses: apiKey/register
  with:
    # Name of the API Key
    name: apiKey
    # Value of the API Key
    primaryClientSecret: ${{SECRET_API_KEY}}
    # Teams app ID
    appId: ${{TEAMS_APP_ID}}
    # Path to OpenAPI description document
    apiSpecPath: ./appPackage/apiSpecificationFile/repair.yml
  # Write the registration information of API Key into environment file for
  # the specified environment variable(s).
  writeToEnvironmentFile:
    registrationId: APIKEY_REGISTRATION_ID
```
A tarefa pega o valor da variável de projeto SECRET_API_KEY , armazenada no arquivo r env/.env.local.usee a registra no cofre. Em seguida, ele pega a ID de entrada do cofre e a grava no arquivo de ambiente env/.env.local. O resultado dessa tarefa é uma variável de ambiente chamada APIKEY_REGISTRATION_ID. O Microsoft 365 Agents Toolkit grava o valor dessa variável no arquivo appPackages/ai-plugin.json que contém a definição do plug-in. Em tempo de execução, o agente declarativo que carrega o plug-in da API usa essa ID para recuperar a chave de API do cofre e chamar a API com segurança.

Configurar chave de API para desenvolvimento local

Antes de testar o projeto, você precisa definir uma chave de API para sua API. Em seguida, armazene a chave de API no cofre e registre a ID de entrada do cofre em seu plug-in de API. Para desenvolvimento local, armazene a chave de API em seu projeto e use o Microsoft 365 Agents Toolkit para registrá-la no cofre para você.

No Visual Studio Code:

Abra o painel Terminal .
Em uma linha de comando:
1. Restaure as dependências do projeto, executando npm installo .
2. Gere uma nova chave de API executando: npm run keygen.
3. Copie a chave gerada para a área de transferência.
Abra o arquivo env/.env.local.user .
Atualize a propriedade SECRET_API_KEY para a chave de API recém-gerada. A propriedade atualizada tem a seguinte aparência:
```
SECRET_API_KEY=your_key
```
Salve suas alterações.

Sempre que você constrói o projeto, o Microsoft 365 Agents Toolkit atualiza automaticamente a chave de API no cofre e atualiza seu projeto com a ID de entrada do cofre.

Teste o agente declarativo com o plug-in de API no Microsoft 365 Copilot

A etapa final é testar o agente declarativo com o plug-in de API no Microsoft 365 Copilot.

No Visual Studio Code:

Na Barra de Atividades, ative a extensão Microsoft 365 Agents Toolkit .
No painel de extensão do Kit de Ferramentas de Agentes do Microsoft 365 , na seção Contas , verifique se você está conectado ao seu locatário do Microsoft 365 com o Copilot habilitado.
Na Barra de Atividades, alterne para o modo de exibição Executar e Depurar.
Na lista de configurações, escolha Depurar no Copilot (Edge) e pressione o botão de reprodução para iniciar a depuração.

O Visual Studio Code abre um novo navegador da Web com o Microsoft 365 Copilot. Se receber a solicitação, entre com sua conta do Microsoft 365.

No navegador da Web:

No painel lateral, selecione o agente da-repairs-keylocal .
Na caixa de texto do prompt, digite What repairs are assigned to Karin? e envie o prompt.
Confirme que deseja enviar dados para o plug-in da API usando o botão Sempre permitir .
Aguarde a resposta do agente.

Interrompa a sessão de depuração no Visual Studio Code quando terminar de testar.

Comentários

Esta página foi útil?