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.
Importante
I plug-in MCP e API forniscono azioni all'interno di agenti dichiarativi. Non sono pacchetti di plugin installabili autonomamente: solo l'agente contenitore può accedere alle loro funzioni e ai loro strumenti. Per informazioni sulla relazione tra pacchetto e manifesto dell'azione, vedere Plug-in e azioni dichiarative dell'agente.
I plug-in API possono usare modelli di risposta con scheda adattiva per migliorare la risposta generata da Microsoft 365 Copilot in base alla risposta ricevuta dall'API. La scheda adattiva esegue il rendering delle citazioni all'interno della risposta generata.
I plug-in API possono definire un modello di risposta Adaptive Card in due modi: come modello statico definito nel manifesto del plug-in o come modello dinamico restituito come parte della risposta API. Gli sviluppatori di plug-in definiscono i modelli utilizzando lo schema Adaptive Card in combinazione con il linguaggio dei modelli Schede adattive.
Modelli di risposta statici
I modelli di risposta statici sono una buona scelta se l'API restituisce sempre elementi dello stesso tipo e se il formato della scheda adattiva non deve cambiare spesso. Definisci un modello statico static_template nella proprietà dell'oggetto response_semantics nel manifesto del plug-in, come illustrato nell'esempio seguente.
"functions": [
{
"name": "GetBudgets",
"description": "Returns details including name and available funds of budgets, optionally filtered by budget name",
"capabilities": {
"response_semantics": {
"data_path": "$",
"properties": {
"title": "$.name",
"subtitle": "$.availableFunds"
},
"static_template": {
"type": "AdaptiveCard",
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
{
"type": "Container",
"$data": "${$root}",
"items": [
{
"type": "TextBlock",
"text": "Name: ${if(name, name, 'N/A')}",
"wrap": true
},
{
"type": "TextBlock",
"text": "Available funds: ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}",
"wrap": true
}
]
}
]
}
}
}
},
]
- Impostare la
response_semantics.data_pathproprietà su. This value is a [JSONPath query](https://www.rfc-editor.org/rfc/rfc9535) that indicates that the root of the JSON response contains the relevant data. Thestatic_template.body["$data"]property value is${$root}, which is Adaptive Card template language syntax to override any prior data scoping and break back to the root. Setting this value isn't strictly needed, since thedata_path' è già impostato sulla radice. - La
textproprietà del primoTextBlockutilizza la sintassi${if(name, name, 'N/A')}del modello Adaptive Card. Questo fa riferimento allanameproprietà nella risposta dell'API. Laiffunzione specifica che senameha un valore, usare tale valore, altrimenti usareN/A. - La
textproprietà del secondoTextBlockutilizza la sintassi${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}del modello Adaptive Card. Questo fa riferimento allaavailableFundsproprietà nella risposta dell'API. LaformatNumberfunzione esegue il rendering del numero in una stringa con due posizioni decimali.
Si consideri questo modello statico e la risposta dell'API seguente.
[
{
"name": "Fourth Coffee lobby renovation",
"availableFunds": 12000
}
]
Questa combinazione si traduce nella seguente scheda adattiva.
Modelli di risposta dinamica
I modelli di risposta dinamica sono una buona scelta se l'API restituisce più tipi. Con i modelli dinamici, puoi assegnare un modello di risposta a ogni elemento restituito. Uno o più modelli dinamici vengono restituiti come parte della risposta API e gli elementi di dati nella risposta indicano quale modello usare.
Per usare i modelli dinamici, indicare quale proprietà sugli elementi di dati specifica il response_semantics.properties.template_selector modello nella proprietà nel manifesto del plug-in API, come illustrato in questo esempio.
{
"name": "GetTransactions",
"description": "Returns details of transactions identified from filters like budget name or category. Multiple filters can be used in combination to refine the list of transactions returned",
"capabilities": {
"response_semantics": {
"data_path": "$.transactions",
"properties": {
"template_selector": "$.displayTemplate"
}
}
}
}
In questo esempio la data_path proprietà è impostata su $.transactions, a indicare che i dati per le schede si trovano nella transactions proprietà alla radice della risposta API. La template_selector proprietà è impostata su $.displayTemplate, a indicare che la proprietà di ogni elemento della matrice che specifica il transactions modello da usare è la displayTemplate proprietà.
La proprietà indicata dalla template_selector proprietà contiene una query JSONPath per individuare il modello per l'elemento all'interno della risposta.
Considera questo modello e la seguente risposta dell'API.
{
"transactions": [
{
"budgetName": "Fourth Coffee lobby renovation",
"amount": -2000,
"description": "Property survey for permit application",
"expenseCategory": "permits",
"displayTemplate": "$.templates.debit"
},
{
"budgetName": "Fourth Coffee lobby renovation",
"amount": -7200,
"description": "Lumber and drywall for lobby",
"expenseCategory": "materials",
"displayTemplate": "$.templates.debit"
},
{
"budgetName": "Fourth Coffee lobby renovation",
"amount": 5000,
"description": "Additional funds to cover cost overruns",
"expenseCategory": null,
"displayTemplate": "$.templates.credit"
}
],
"templates": {
"debit": {
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"size": "medium",
"weight": "bolder",
"color": "attention",
"text": "Debit"
},
{
"type": "FactSet",
"facts": [
{
"title": "Budget",
"value": "${budgetName}"
},
{
"title": "Amount",
"value": "${formatNumber(amount, 2)}"
},
{
"title": "Category",
"value": "${if(expenseCategory, expenseCategory, 'N/A')}"
},
{
"title": "Description",
"value": "${if(description, description, 'N/A')}"
}
]
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
},
"credit": {
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"size": "medium",
"weight": "bolder",
"color": "good",
"text": "Credit"
},
{
"type": "FactSet",
"facts": [
{
"title": "Budget",
"value": "${budgetName}"
},
{
"title": "Amount",
"value": "${formatNumber(amount, 2)}"
},
{
"title": "Description",
"value": "${if(description, description, 'N/A')}"
}
]
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
}
}
}
- La
transactionsproprietà nella risposta contiene una matrice di elementi. - La
templatesproprietà è un oggetto, con ogni proprietà in tale oggetto contenente un modello di scheda adattiva. - Il
displayTemplatevalore su ogni oggetto nellatransactionsmatrice è impostato su o$.templates.debit$.templates.credit.
La combinazione di questo manifesto del plug-in e della risposta dell'API si traduce nelle seguenti schede adattive.
Evita che le schede adattive vuote vengano create quando un array nella risposta dell'API è vuoto
Le schede adattive possono essere rese vuote quando una proprietà di matrice nella risposta dell'API è vuota e il modello non include la logica condizionale per gestire tale scenario.
L'esempio seguente mostra una risposta API in cui l'array recommendations non contiene elementi:
{"answer":"","recommendations":[],"followUpMessage":""}
In questo caso:
- La matrice di consigli non contiene elementi.
- Il modello Scheda adattiva tenta di eseguire l'iterazione sulla matrice senza verificare se i dati sono disponibili.
Per impedire il rendering di una scheda vuota, associa il modello alla proprietà della matrice corretta e aggiungi una logica condizionale per controllare il rendering.
Eseguire l'associazione alla matrice usando data_path:
"data_path": "$.recommendations"
Eseguire l'iterazione sugli oggetti solo quando i dati esistono:
{ "type": "ColumnSet", "$data": "${$root}", "$when": "${title != null && title != ''}" }
Facoltativamente, fornisci il testo di fallback quando la matrice è vuota:
{ "type": "TextBlock", "text": "No recommendations available", "$when": "${length($root) == 0}" }
Suggerimento
Convalida data_path e includi $when sempre le condizioni per gli array vuoti per impedire l'uso di schede adattive vuote.
Uso combinato di modelli statici e dinamici
I plug-in possono combinare l'uso di modelli statici e dinamici. In questo scenario, il modello statico funge da modello predefinito da usare se l'elemento non ha la template_selector proprietà presente o se il suo valore non viene risolto in un modello nella risposta dell'API.
Aggiungere domini al manifesto dell'app
Aggiungi tutti i domini utilizzati dalla scheda adattiva alla sezione validDomains del manifesto dell'app.
- Quando utilizzi
Action.OpenUrl, assicurati di includere ilvalidDomainsdominio dell'URL di destinazione nella proprietà. Se il dominio non è elencato, Teams visualizza il messaggio L'URL potrebbe condurre a contenuto non attendibile. - Gli URL delle immagini restituiti dal plug-in API o dall'agente dichiarativo in una risposta Adaptive Card devono avere il
validDomainsdominio elencato nella proprietà. Se il dominio non è elencato, Microsoft 365 Copilot non esegue il rendering dell'immagine.
Garantire schede adattive reattive negli hub Microsoft 365 Copilot
Le schede adattive devono essere progettate per essere reattive su superfici di varie dimensioni. Questo design garantisce un'esperienza utente senza interruzioni, indipendentemente dal dispositivo o dalla piattaforma utilizzata. Per raggiungere questo obiettivo, convalidare le schede adattive in diversi hub di Microsoft 365 Copilot, tra cui Teams, Word e PowerPoint. Inoltre, puoi convalidare le varie larghezze del riquadro di visualizzazione contraendo ed espandendo l'interfaccia utente di Copilot. Questo processo garantisce che le schede adattive funzionino in modo ottimale e offrano un'esperienza coerente su tutte le piattaforme. Applicare le procedure consigliate seguenti:
- Evitare di usare layout a più colonne quando possibile. I layout a colonna singola tendono a essere visualizzati correttamente anche con le larghezze di visualizzazione più strette.
- Evitare di inserire elementi di testo e immagine nella stessa riga, a meno che l'immagine non sia una piccola icona o un avatar.
- Evita di assegnare una larghezza fissa agli elementi all'interno della scheda adattiva; invece, consenti loro di ridimensionarsi in base alla larghezza della vista. È tuttavia possibile assegnare una larghezza fissa a immagini di piccole dimensioni, ad esempio icone e avatar.
Contenuti correlati
- Adaptive Card Designer per progettare e testare le schede adattive in uno strumento visivo.
- Documentazione della scheda adattiva
- Informazioni di riferimento sul manifesto del plug-in