Entità e tipi di attività

SI APPLICA A: SDK v4

Le entità fanno parte di un'attività e forniscono informazioni aggiuntive sull'attività o la conversazione.

Nota

Diverse parti dell'SDK definiscono classi di entità o elementi separati.

Entità

La proprietà entities di un messaggio è una matrice di oggetti schema.org aperti, che consente lo scambio di metadati contestuali comuni tra il canale e il bot.

Entità mention

Molti canali supportano la possibilità per un bot o un utente di "menzionare" qualcuno nel contesto di una conversazione. Per menzionare un utente in un messaggio, popolare la proprietà Entities del messaggio con un oggetto mention. L'oggetto mention contiene queste proprietà:

Proprietà	Descrizione
Tipo	Tipo dell'entità ("menzione")
Con menzione	Oggetto account canale che indica quale utente è stato menzionato
Testo	Testo all'interno della proprietà activity.text che rappresenta la menzione stessa (può essere vuota o null)

Questo esempio di codice illustra come aggiungere un'entità mention alla raccolta di entità.

C#

var entity = new Entity();
entity.SetAs(new Mention()
{
    Text = "@johndoe",
    Mentioned = new ChannelAccount()
    {
        Name = "John Doe",
        Id = "UV341235"
    }
});
entities.Add(entity);

Suggerimento

Quando si tenta di determinare la finalità dell'utente, il bot può voler ignorare quella parte del messaggio in cui è menzionata. Chiamare il metodo GetMentions e valutare gli oggetti Mention restituiti nella risposta.

JavaScript

var entity = context.activity.entities;

const mention = {
    type: "Mention",
    text: "@johndoe",
    mentioned: {
        name: "John Doe",
        id: "UV341235"
    }
}

entity = [mention];

Posizionare gli oggetti

Le informazioni relative alla posizione possono essere trasferite all'interno di un messaggio popolando la proprietà Entities del messaggio con un oggetto Place o GeoCoordinates.

L'oggetto Place contiene queste proprietà:

Proprietà	Descrizione
Tipo	Tipo dell'entità ("Place")
Indirizzo	Descrizione o oggetto indirizzo postale (futuro)
Area geografica	GeoCoordinates
HasMap	URL di una mappa o un oggetto map (futuro)
Nome	Nome del luogo

L'oggetto geoCoordinates contiene queste proprietà:

Proprietà	Descrizione
Tipo	Tipo dell'entità ("GeoCoordinates")
Nome	Nome del luogo
Longitude	Longitudine della posizione (WGS 84)
Latitudine	Latitudine della posizione (WGS 84)
Elevazione	Elevazione della posizione (WGS 84)

Questo esempio di codice illustra come aggiungere un'entità Place alla raccolta di entità:

C#

var entity = new Entity();
entity.SetAs(new Place()
{
    Geo = new GeoCoordinates()
    {
        Latitude = 32.4141,
        Longitude = 43.1123123,
    }
});
entities.Add(entity);

JavaScript

var entity = context.activity.entities;

const place = {
    elavation: 100,
    type: "GeoCoordinates",
    name : "myPlace",
    latitude: 123,
    longitude: 234
};

entity = [place];

Usare le entità

C#

Per utilizzare le entità, usare la dynamic parola chiave o le classi fortemente tipate.

Questo esempio di codice illustra come usare la parola chiave dynamic per elaborare un'entità all'interno della proprietà Entities di un messaggio:

if (entity.Type == "Place")
{
    dynamic place = entity.Properties;
    if (place.geo.latitude > 34)
        // do something
}

Questo esempio di codice illustra come usare una classe fortemente tipizzata per elaborare un'entità all'interno della Entities proprietà di un messaggio:

if (entity.Type == "Place")
{
    Place place = entity.GetAs<Place>();
    GeoCoordinates geo = place.Geo.ToObject<GeoCoordinates>();
    if (geo.Latitude > 34)
        // do something
}

JavaScript

Questo esempio di codice illustra come elaborare un'entità all'interno della proprietà entity di un messaggio:

if (entity[0].type === "GeoCoordinates" && entity[0].latitude > 34) {
    // do something
}

Tipi di impegno

Le attività possono essere di diversi tipi, oltre al tipo message più comune. Le spiegazioni e altre informazioni sui diversi tipi di attività sono disponibili nello schema delle attività di Bot Framework.