Integrar um plug-in de API com uma API protegida por uma chave
Uma das formas comuns de proteger as APIs é através da utilização de chaves de API. As chaves de API são cadeias arbitrárias que os proprietários de API emitem para lhe conceder acesso à API. Muitos serviços populares utilizam chaves de API para proteger o acesso às respetivas APIs. O fornecedor de API que emite chaves de API controla se uma chave lhe dá acesso a toda a superfície da API e a todos os recursos ou apenas a uma parte específica da mesma. O serviço também controla durante quanto tempo uma chave é válida.
As chaves de API são convenientes de utilizar graças à sua simplicidade. Para chamar uma API protegida com uma chave de API, tudo o que precisa de fazer é incluir a chave de API no pedido da API. Em seguida, a API valida a chave e processa o pedido ou rejeita-o com um erro de autenticação ou autorização. No entanto, esta simplicidade tem um custo. As chaves de API não autenticam o utilizador, o que significa que a API não pode agir em nome do utilizador. Todos os utilizadores que chamam a API com a mesma chave de API têm as mesmas permissões.
Cada fornecedor de API define como espera que transmita a chave de API com os seus pedidos. Por exemplo, uma API pode exigir que utilize um parâmetro de cadeia de consulta específico ou um cabeçalho de pedido.
Microsoft 365 Copilot suporta a transmissão de chaves de API como:
- JSON Web Token (JWT)
GET https://api.contoso.com/orders
Authorization: Bearer API_KEY
- Parâmetro da seqüência de consulta
GET https://api.contoso.com/orders?api_key=API_KEY
- Cabeçalho personalizado
GET https://api.contoso.com/orders
X-API-Key: API_KEY
Uma chave de API é um valor secreto que nunca deve partilhar publicamente. Quando cria um plug-in de API que se integra com uma API protegida por uma chave de API, armazena a chave de API numa localização de armazenamento segura no Microsoft 365, também conhecida como cofre. Em seguida, na sua aplicação, faz referência ao ID da entrada do cofre. No runtime, o agente declarativo carrega o plug-in (2) e resolve o ID de entrada para a chave de API real (3a) que utiliza para chamar a API (3b). O diagrama seguinte ilustra este processo.
Armazenar a chave de API no cofre permite-lhe gerir de forma segura a sua chave de API sem nunca a expor publicamente. Além disso, uma vez que a sua aplicação não referencia diretamente a chave de API, pode atualizá-la sem ter de atualizar a sua aplicação.
Durante o desenvolvimento, pode registar a sua chave de API de desenvolvimento no cofre manualmente ao aceder ao Portal do Programador do Teams e à secção Ferramentas ao abrir o registo da chave de API ou ao utilizar o Toolkit de Agentes do Microsoft 365. Em produção, normalmente, um administrador regista a chave de API e dá-lhe o ID da entrada do cofre a utilizar no plug-in da API.
