Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Suggerimento
Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.
Alcune API usano chiavi API per l'autorizzazione. Una chiave API è un segreto condiviso che il client include nelle richieste API per l'autenticazione e l'accesso. I plug-in API supportano l'invio della chiave API in tre modi:
- Come token di connessione nell'intestazione
Authorization - Come valore in un'intestazione personalizzata
- Come parametro di query
Nota
Per le azioni dell'agente dichiarativo, l'autenticazione della chiave API si applica ai plug-in API creati da un documento OpenAPI, non ai plug-in MCP. Per il plug-in MCP di un agente usare OAuth 2.0 (inclusa la registrazione dinamica del client) o Microsoft Entra SSO. Una connessione MCP remota a livello di pacchetto utilizza una configurazione diversa; Vedere Autenticazione nel manifesto dell'app.
Configura l'autenticazione della chiave API in due passaggi: aggiungi la chiave API al documento OpenAPI e crea la configurazione dell'autenticazione della chiave API.
Passaggio 1: aggiungere la chiave API al documento OpenAPI
Microsoft 365 Copilot determina come securitySchemes inviare la chiave API in base alla voce nel documento OpenAPI.
Token di connessione
Se l'API accetta la chiave API come token di connessione, abilitare l'autenticazione del portatore nel documento OpenAPI. Per ulteriori informazioni, consulta Autenticazione del portatore.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
Intestazione personalizzata
Se l'API accetta la chiave API in un'intestazione personalizzata, abilitare l'autenticazione della chiave API nel documento OpenAPI con la in proprietà impostata su header e la name proprietà impostata sul nome dell'intestazione. Per ulteriori informazioni, consulta Chiavi API.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
Parametro di query
Se l'API accetta la chiave API in un parametro di query, abilitare l'autenticazione della chiave API nel documento OpenAPI impostando la in proprietà e query la name proprietà sul nome del parametro di query. Per ulteriori informazioni, consulta Chiavi API.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key
Passaggio 2: creare la configurazione di autenticazione della chiave API
L'autenticazione della chiave API si basa su una configurazione di autenticazione (auth config), un record archiviato nell'archivio token Microsoft Enterprise usato da Microsoft 365 Copilot per inviare la chiave API quando il plug-in chiama l'API. Iniziare con WIQD per un progetto pro-code supportato. Le procedure Toolkit e del portale per sviluppatori di Microsoft Teams rimangono disponibili come alternative. La competenza per sviluppatori di agenti dichiarativi non supporta l'autenticazione con chiave API, perché crea plug-in MCP.
Usa gli strumenti di sviluppo di Work IQ (scelta consigliata)
Per un manifesto di plug-in API esistente, utilizzare wiqd agent add auth con --plugin-manifest, --auth-namee --auth-type api-key. Impostare --api-key-in to header o query e e --api-key-name il nome dello schema di sicurezza di OpenAPI. Se invece l'API accetta la chiave come token di connessione, selezionare --auth-type bearer-token.
Quando si aggiunge un'azione da un documento OpenAPI, wiqd agent add action accetta --api-key per la chiave API o le credenziali del portatore. Il comando documenta i segnaposto di ambiente quando il valore viene omesso. Segui la gestione delle credenziali del comando selezionato e completa il flusso di lavoro di provisioning del progetto. Queste opzioni della chiave API non stabiliscono il supporto della chiave API per il plug-in MCP di un agente.
Usare Microsoft 365 Agents Toolkit
Quando crei un plug-in API da un documento OpenAPI esistente in Microsoft 365 Agents Toolkit, il toolkit registra la chiave API, crea la configurazione di autenticazione e aggiorna automaticamente il manifesto del plug-in. È necessario definire la securitySchemes proprietà nel documento OpenAPI.
Usare il portale per sviluppatori di Teams
La registrazione al portale per sviluppatori di Teams è facoltativa se si usa Agents Toolkit. Utilizzalo per creare manualmente la configurazione di autenticazione o per gestire una configurazione di autenticazione già creata da Agents Toolkit.
Aprire il portale per sviluppatori di Teams. Seleziona Strumenti ->Registrazione della chiave API.
Se non hai registrazioni esistenti, seleziona Crea una chiave API. Se hai registrazioni esistenti, seleziona Nuova chiave API.
Selezionare Aggiungi segreto e immettere la chiave API.
Compila i seguenti campi.
- Nome chiave API: un nome descrittivo per la registrazione.
-
URL di base: URL di base dell'API. Questo valore deve corrispondere a una voce nell'array
serversnel documento OpenAPI. - Tenant di destinazione: limita l'accesso all'API al tenant principale o consenti qualsiasi tenant.
- App di Teams di destinazione: selezionare un'app di Teams se non si conosce l'ID app finale. Dopo aver pubblicato l'app, associa questa registrazione all'ID app pubblicato.
Selezionare Salva.
Il completamento della registrazione genera un ID di configurazione dell'autenticazione (attualmente denominato ID di registrazione della chiave API nel portale per sviluppatori di Teams).
Aggiungere l'ID di configurazione dell'autenticazione al manifesto del plug-in
Quando si crea manualmente la configurazione dell'autenticazione nel portale per sviluppatori di Teams, impostare la type proprietà dell'oggetto di autenticazione di runtime su ApiKeyPluginVaulte quindi reference_id sull'ID di configurazione dell'autenticazione. Agents Toolkit fa tutto questo per te.
"auth": {
"type": "ApiKeyPluginVault",
"reference_id": "auth config ID"
},