Modello di azione universale

Articolo
01/18/2024

Contesto

Le schede adattive sono frammenti indipendenti dalla piattaforma dell'interfaccia utente, creati usando un formato JSON leggero, che le app e i servizi possono condividere. Le schede adattive non solo si adattano all'aspetto dell'host, ma offrono anche funzionalità di interazione avanzate. Per altre informazioni sulle schede adattive, visitare adaptivecards.io.

Man mano che le schede adattive sono cresciute in popolarità, diversi host hanno iniziato a supportare modelli di azione diversi e questo ha portato alla frammentazione. Per risolvere questo problema, i team teams, outlook e schede adattive hanno lavorato alla creazione di un nuovo modello di azione bot universale compatibile tra gli host. Questo sforzo ha portato ai seguenti:

La generalizzazione dei bot e di Bot Framework come modo per implementare scenari basati su schede adattive per Teams (bot) e Outlook (messaggio interattivo)
Action.Execute come sostituzione per entrambi Action.Submit (attualmente usati dai bot) e Action.Http (attualmente usati dai messaggi interattivi)
Funzionalità comuni supportate solo dai messaggi interattivi resi disponibili per i bot, ovvero:
- Possibilità di aggiornare una scheda al momento della visualizzazione
- Possibilità per Action.Execute le azioni di restituire una scheda aggiornata da visualizzare immediatamente nel client

Per altre informazioni sui messaggi interattivi in Outlook, vedere la documentazione relativa ai messaggi interattivi

Per informazioni dettagliate sui vari scenari possibili con le azioni universali in Teams, vedere le informazioni di riferimento sulle schede di Teams.

Prima `Action.Execute`	Con `Action.Execute`

Origine: schede adattive @ Microsoft Build 2020

Il resto di questo documento è incentrato sulla documentazione del modello di azione bot universale nel contesto di Teams e Outlook. Se si usano già schede adattive in Teams con bot, è possibile usare lo stesso bot con alcune modifiche per supportare Action.Execute. Se si usano messaggi interattivi in Outlook, sarà necessario sviluppare un bot che supporti Action.Execute. Attualmente il supporto per i client Outlook per il modello di azione Universal Bot è in fase di sviluppo attivo.

Schema

IMPORTANTE

Il modello di azione universal Bot è stato introdotto nello schema delle schede adattive versione 1.4. Per usare queste nuove funzionalità, la version proprietà della scheda adattiva deve essere impostata su 1.4 o versione successiva, come illustrato negli esempi seguenti. Si noti che in questo modo la scheda adattiva non sarà compatibile con i client meno recenti (Outlook o Teams) che non supportano il modello di azione del bot universale.

Se si usa la refresh proprietà e/o Action.Execute e si specifica una scheda versione < 1.4, si verificherà quanto segue:

Client Comportamento

Outlook La scheda NON funzionerà. refresh non verrà rispettato e Action.Execute non verrà eseguito il rendering. La carta potrebbe anche essere rifiutata completamente.

Teams La scheda POTREBBE NON funzionare (il refresh potrebbe non essere rispettato e le Action.Execute azioni potrebbero non essere visualizzate) a seconda della versione del client Teams.

Per garantire la massima compatibilità in Teams, è consigliabile definire le Action.Execute azioni con un'azione Action.Submit nella fallback proprietà .

Per altre informazioni, vedere la sezione Compatibilità con le versioni precedenti di seguito.

Client	Comportamento
Outlook	La scheda NON funzionerà. `refresh` non verrà rispettato e `Action.Execute` non verrà eseguito il rendering. La carta potrebbe anche essere rifiutata completamente.
Teams	La scheda POTREBBE NON funzionare (il `refresh` potrebbe non essere rispettato e le `Action.Execute` azioni potrebbero non essere visualizzate) a seconda della versione del client Teams. Per garantire la massima compatibilità in Teams, è consigliabile definire le `Action.Execute` azioni con un'azione `Action.Submit` nella `fallback` proprietà .

Action.Execute

Quando si creano schede adattive, usare Action.Execute al posto di entrambi Action.Submit e Action.Http. Lo schema per Action.Execute è molto simile a quello di Action.Submit.

Json di esempio

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Proprietà

Proprietà	Type	Obbligatorio	Descrizione
type	`"Action.Execute"`	Sì	Deve essere `"Action.Execute"`.
Verbo	string	No	Stringa di praticità che può essere usata dallo sviluppatore per identificare l'azione
data	`string`, `object`	No	I dati iniziali con cui i campi di input verranno combinati. Si tratta essenzialmente di proprietà "nascoste".
title	`string`	No	Etichetta per il pulsante o il collegamento che rappresenta questa azione.
iconUrl	`uri`	No	Icona facoltativa da visualizzare nell'azione insieme al titolo. Supporta l'URI dati nelle schede adattive versione 1.2+
style	`ActionStyle`	No	Controlla lo stile di un'azione, che influenza la modalità di visualizzazione, parlato e così via dell'azione.
Fallback	`<action object>`, `"drop"`	No	Descrive le operazioni da eseguire quando Action.Execute non è supportato dal client che visualizza la scheda.
Richiede	`Dictionary<string>`	No	Serie di coppie chiave/valore che indicano le funzionalità richieste dall'elemento con la versione minima corrispondente. Quando una funzionalità è mancante o di versione insufficiente, viene attivato il fallback.

Meccanismo di aggiornamento

Accanto Action.Executea , è ora supportato un nuovo meccanismo di aggiornamento, che consente di creare schede adattive che vengono aggiornate automaticamente al momento della visualizzazione. Ciò garantisce che gli utenti visualizzino sempre i dati aggiornati. Un tipico caso d'uso di aggiornamento è una richiesta di approvazione: una volta approvata, è preferibile che gli utenti non vengano presentati con una scheda che richiede di approvare quando è già stato fatto, ma fornisce invece informazioni sul momento in cui la richiesta è stata approvata e da chi.

Per consentire l'aggiornamento automatico di una scheda adattiva, definirne la refresh proprietà, che incorpora un action oggetto di tipo Action.Execute e una userIds matrice.

Proprietà	Type	Obbligatorio	Descrizione
azione	`"Action.Execute"`	Sì	Deve essere un'istanza di azione di tipo `"Action.Execute"`.
userIds	`Array<string>`	Sì	Matrice di `MRI`utenti per i quali è necessario abilitare l'aggiornamento automatico. IMPORTANTE: se la `userIds` proprietà elenco non è inclusa nella `refresh` sezione della scheda, la scheda NON verrà aggiornata automaticamente sulla visualizzazione. Verrà invece presentato un pulsante all'utente per consentire l'aggiornamento manuale. Il motivo è che chat/canali in Teams possono includere un numero elevato di membri; se molti membri visualizzano tutti il canale contemporaneamente, un aggiornamento automatico incondizionato genererà molte chiamate simultanee al bot, che non si ridimensionano. Per risolvere il potenziale problema di scalabilità, la `userIds` proprietà deve essere sempre inclusa per identificare gli utenti che devono ottenere un aggiornamento automatico, con un massimo di 60 ID utente attualmente consentiti. Per altri dettagli, vedere userIds nell'aggiornamento . Si noti che la `userIds` proprietà viene ignorata in Outlook e la `refresh` proprietà viene sempre rispettata automaticamente. Non esiste alcun problema di scalabilità in Outlook perché gli utenti visualizzano in genere la scheda in momenti diversi.

Json di esempio

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
  "version": "1.4",
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Submit",
      "verb": "personalDetailsCardRefresh"
    },
    "userIds": []
  },
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    { 
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Nota importante per gli sviluppatori di messaggi interattivi di Outlook

Quando si sviluppano scenari di messaggi interattivi di Outlook, è necessario specificare la proprietà della originator scheda adattiva. originator è un GUID (Global Unique Identified) generato al momento in cui un bot sottoscrive il canale di Outlook. Viene usato da Outlook per verificare che la scheda adattiva sia stata inviata da un bot autorizzato. Il rendering della scheda adattiva non verrà eseguito in Outlook se originator è assente. originator viene ignorato in Teams.

`adaptiveCard/action` Richiamare l'attività

Quando un oggetto Action.Execute viene eseguito nel client (sia l'azione di aggiornamento o un'azione eseguita in modo esplicito da un utente facendo clic su un pulsante), viene eseguito un nuovo tipo di attività Invoke - adaptiveCard/action - per il bot. Una tipica adaptiveCard/action richiesta di attività Invoke sarà simile alla seguente:

Formato richiesta

{ 
  "type": "invoke",
  "name": "adaptiveCard/action",

  // ... other properties omitted for brevity

  "value": { 
    "action": { 
      "type": "Action.Execute", 
      "id": "abc", 
      "verb": "def",
      "data": { ... } 
    },
    "trigger": "automatic | manual" 
  }
}

Campo	Descrizione
value.action	Copia dell'azione definita nella scheda adattiva. Come con `Action.Submit`, la `data` proprietà dell'azione include i valori dei vari input nella scheda, se presenti
value.trigger	Indica se l'azione è stata attivata in modo esplicito (facendo clic su un pulsante) o in modo implicito (tramite l'aggiornamento automatico)

Formato risposta

Se il bot ha elaborato un'attività Invoke in ingresso adaptiveCard/action (ad esempio, se il codice del bot è stato coinvolto in tutto l'elaborazione della richiesta), il codice di stato della risposta HTTP restituito dal bot deve essere uguale a 200 e il corpo della risposta HTTP deve essere formattato come segue:

{ 
    "statusCode": <number (200 – 599)>, 
    "type": "<string>", 
    "value": "<object>"
}

Campo	Descrizione
statusCode	Un codice di stato della risposta HTTP 200 non significa necessariamente che il bot sia stato in grado di elaborare correttamente la richiesta. Un'applicazione client DEVE sempre esaminare la `statucCode` proprietà nel corpo della risposta per sapere come il bot ha elaborato la richiesta. `statusCode` è un numero compreso tra 200 e 599 che rispecchia i valori del codice di stato HTTP ed è destinato a essere uno stato secondario per il risultato dell'elaborazione del bot di Invoke. Un valore mancante, null o non definito per `statusCode` implica un valore 200 (Operazione riuscita).
type	Set di costanti stringa note che descrivono la forma prevista della proprietà value
value	Oggetto specifico del tipo di corpo della risposta

Codici di stato supportati

La tabella seguente elenca i valori consentiti per statusCode, typee value nel corpo della risposta del bot:

Codice di stato	Type	Schema valore	Note
200	`application/vnd.microsoft.card.adaptive`	`Adaptive Card`	La richiesta è stata elaborata correttamente e la risposta include una scheda adattiva che il client deve visualizzare al posto di quello corrente.
200	`application/vnd.microsoft.activity.message`	`string`	La richiesta è stata elaborata correttamente e la risposta include un messaggio che il client deve visualizzare.
400	`application/vnd.microsoft.error`	Oggetto Error (TODO: needs link)	La richiesta in ingresso non è valida.
401	`application/vnd.microsoft.activity.loginRequest`	OAuthCard (TODO: collegamento necessario)	Il client deve richiedere all'utente di eseguire l'autenticazione.
401	`application/vnd.microsoft.error.inccorectAuthCode`	Null	Lo stato di autenticazione passato dal client non è corretto e l'autenticazione non è riuscita.
412	`application/vnd.microsoft.error.preconditionFailed`	Oggetto Error (TODO: needs link)	Il flusso di autenticazione SSO non è riuscito.
500	`application/vnd.microsoft.error`	Oggetto Error (TODO: needs link)	Errore imprevisto.

Riepilogo: come sfruttare il modello di azione bot universale

Usare Action.Execute invece di Action.Submit. Per aggiornare uno scenario esistente nei team, sostituire tutte le istanze di Action.Submit con Action.Execute. Per aggiornare uno scenario esistente in Outlook, vedere la sezione relativa alla compatibilità con le versioni precedenti di seguito.
Per visualizzare le schede in outlook, aggiungere il originator campo. Fare riferimento al codice JSON di esempio precedente.
Aggiungere una refresh clausola alla scheda adattiva se si vuole sfruttare il meccanismo di aggiornamento automatico o se lo scenario richiede visualizzazioni specifiche dell'utente. Assicurarsi di specificare la userIds proprietà per identificare quali utenti (massimo 60) otterranno gli aggiornamenti automatici.
Gestire adaptiveCard/action le richieste invoke nel bot
Ogni volta che il bot deve restituire una nuova scheda in seguito all'elaborazione di un Action.Executeoggetto , è possibile usare il contesto della richiesta Invoke per generare schede create specificamente per un determinato utente. Assicurarsi che la risposta sia conforme allo schema di risposta definito in precedenza.

Compatibilità con le versioni precedenti

Outlook

Il nuovo Action.Execute modello di azione universale è una partenza dal Action.Http modello di azione attualmente utilizzato dai messaggi interattivi di Outlook, in cui le azioni vengono codificate nella scheda adattiva come chiamate HTTP esplicite. Il Action.Execute modello consente agli sviluppatori di implementare scenari che "funzionano" sia in Outlook che in Teams. Gli scenari di messaggi interattivi possono usare il Action.Http modello o il nuovo Action.Execute modello, ma non entrambi. Gli scenari che usano il modello universale Action.Execute devono essere implementati come bot e sottoscrivere il Outlook Actionable Messages canale.

Note importanti

Gli scenari implementati con il modello universale Action.Execute non saranno compatibili con le versioni precedenti di Outlook

Il lavoro è in corso per consentire agli scenari di messaggi interattivi esistenti di eseguire facilmente la migrazione al modello universale Action.Execute

Teams

Affinché le schede siano compatibili con le versioni precedenti e funzionino per gli utenti con versioni precedenti di Teams, le Action.Execute azioni devono includere una fallback proprietà definita come Action.Submit. Il bot deve essere codificato in modo che possa elaborare sia Action.Execute che Action.Submit. Si noti che non è possibile che il bot restituisca una nuova scheda durante l'elaborazione di un Action.Submit, quindi il comportamento di fallback tramite Action.Submit fornirà un'esperienza danneggiata per l'utente finale.

Nota importante

Alcuni client di Teams meno recenti non supportano la proprietà di fallback quando non viene eseguito il wrapping in un oggetto ActionSet. Per evitare interruzioni su tali client, è consigliabile eseguire il wrapping di tutto Action.Execute in ActionSet. Vedere l'esempio seguente su come eseguire il wrapping Action.Execute in ActionSet.

Nell'esempio seguente si noti che la version proprietà della scheda è impostata su 1.2 e l'oggetto Action.Execute viene definito con come Action.Submit .fallback Quando viene eseguito il rendering in un client teams che supporta le schede adattive 1.4, eseguirà il Action.Execute rendering e funzionerà come previsto. Nei client di Teams che non supportano le schede adattive 1.4, il Action.Submit rendering verrà eseguito al posto di Action.Execute.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": {
            "type": "Action.Submit",
            "title": "Submit"
          }  
        }
      ]
    }
  ]
}

Condividi tramite

Modello di azione universale

Contesto

Schema

IMPORTANTE

Action.Execute

Meccanismo di aggiornamento

Nota importante per gli sviluppatori di messaggi interattivi di Outlook

`adaptiveCard/action` Richiamare l'attività

Formato richiesta

Formato risposta

Riepilogo: come sfruttare il modello di azione bot universale

Compatibilità con le versioni precedenti

Outlook

Note importanti

Teams

Nota importante

Riferimenti

Risorse aggiuntive

Condividi tramite

Modello di azione universale

Contesto

Schema

IMPORTANTE

Action.Execute

Meccanismo di aggiornamento

Nota importante per gli sviluppatori di messaggi interattivi di Outlook

adaptiveCard/action Richiamare l'attività

Formato richiesta

Formato risposta

Riepilogo: come sfruttare il modello di azione bot universale

Compatibilità con le versioni precedenti

Outlook

Note importanti

Teams

Nota importante

Riferimenti

Risorse aggiuntive

`adaptiveCard/action` Richiamare l'attività