Informazioni sui tipi di identificatore

Utente di Microsoft Teams

L'interfaccia MicrosoftTeamsUserIdentifier rappresenta un utente di Teams con l'ID oggetto utente di Microsoft Entra. È possibile recuperare l'ID oggetto utente di Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK. In alternativa, è possibile trovare l'ID come oid attestazione in un token Microsoft Entra o un token di accesso di Microsoft Entra dopo che l'utente ha eseguito l'accesso e acquisito un token.

Utilizzo di base

// get the Teams user's ID from Graph APIs if only the email is known
const user = await graphClient.api("/users/bob@contoso.com").get();

// create an identifier
const teamsUser = { microsoftTeamsUserId: user.id };

// if you're not operating in the public cloud, you must also pass the right Cloud type.
const gcchTeamsUser = { microsoftTeamsUserId: userId, cloud: "gcch" };

Informazioni di riferimento sulle API

Numero di telefono

L'interfaccia PhoneNumberIdentifier rappresenta un numero di telefono. Il servizio presuppone che i numeri di telefono siano formattati in formato E.164.

Utilizzo di base

// create an identifier
const phoneNumber = { phoneNumber: "+112345556789" };

Informazioni di riferimento sulle API

Applicazione Microsoft Teams

L'interfaccia MicrosoftTeamsAppIdentifier rappresenta un bot delle applicazioni di Teams Voice, come ad esempio Coda delle chiamate e Operatore automatico con l'ID oggetto bot Microsoft Entra. Le applicazioni di Teams devono essere configurate con un account di risorsa. È possibile recuperare l'ID oggetto bot Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK.

Utilizzo di base

// Get the Microsoft Teams App's ID from Graph APIs
const users = await graphClient.api("/users")
                    .filter(filterConditions)
                    .select('displayName,id')
                    .get();
//Here we assume that you have a function getBotFromUsers that gets the bot from the returned response
const bot = getBotFromUsers(users);
// Create an identifier
const teamsAppIdentifier = { teamsAppId: bot.id };

// If you're not operating in the public cloud, you must also pass the right Cloud type.
const gcchTeamsAppIdentifier = { teamsAppId: id, cloud: "gcch" };

Informazioni di riferimento sulle API

Sconosciuto

L'interfaccia UnknownIdentifier esiste per la correzione futura e potrebbe essere presente in una versione precedente di SDK in cui sia stato recentemente introdotto un nuovo tipo di identificatore. Qualsiasi identificatore sconosciuto dal servizio verrà deserializzato in UnknownIdentifier in SDK.

Utilizzo di base

// create an identifier
const unknownId = { id: "a raw id that originated in the service" };

Informazioni di riferimento sulle API

Come gestire l'interfaccia `CommunicationIdentifier` di base

Mentre si costruiscono identificatori per un tipo concreto passato all'SDK, l'SDK restituisce un CommunicationIdentifierKind, che è un'unione discriminata. È facile restringersi a un tipo concreto e si suggerisce un'istruzione switch-case con criteri di ricerca:

switch (communicationIdentifier.kind)
{
    case "communicationUser":
        // TypeScript has narrowed communicationIdentifier to be a CommunicationUserKind
        console.log(`Communication user: ${communicationIdentifier.communicationUserId}`);
        break;
    case "microsoftTeamsUser":
        // narrowed to MicrosoftTeamsUserKind
        console.log(`Teams user: ${communicationIdentifier.microsoftTeamsUserId}`);
        break;
    case "microsoftTeamsApp":
        // narrowed to MicrosoftTeamsAppIdentifier
        console.log(`Teams app: ${communicationIdentifier.teamsAppId}`);
        break;
    case "phoneNumber":
         // narrowed to PhoneNumberKind
        console.log(`Phone number: ${communicationIdentifier.phoneNumber}`);
        break;
    case "unknown":
         // narrowed to UnknownIdentifierKind
        console.log(`Unknown: ${communicationIdentifier.id}`);
        break;
    default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Le interfacce dell'identificatore sono state progettate in modo da non dover specificare kind per ridurre il livello di dettaglio e l'unione discriminante con la proprietà kind viene usata solo quando viene restituita da SDK. Tuttavia, se si ha la necessità di tradurre un identificatore nel tipo di unione discriminante corrispondente, è possibile usare questo helper:

const identifierKind = getIdentifierKind(identifier); // now you can switch-case on the kind

Rappresentazione dell'ID non elaborato

In alcuni casi è necessario serializzare un identificatore in una stringa flat. Ad esempio, se si vuole archiviare l'identificatore in una tabella di database o se lo si vuole usare come parametro URL.

A tale scopo, gli identificatori hanno un'altra rappresentazione denominata RawId. Un identificatore può sempre essere convertito nell'ID non elaborato corrispondente e un ID non elaborato valido può sempre essere convertito in un identificatore.

Poiché azure-communication-common@2.1.0 l'SDK consente la conversione:

// get an identifier's raw Id
const rawId = getIdentifierRawId(communicationIdentifier);

// create an identifier from a given raw Id
const identifier = createIdentifierFromRawId(rawId);

Un ID non elaborato non valido verrà semplicemente convertito in un UnknownIdentifier nell'SDK e qualsiasi convalida avviene solo sul lato servizio.

Utente di comunicazione

CommunicationUserIdentifier rappresenta un'identità utente creata usando Identity SDK o l'API REST. È l'unico identificatore usato se l'applicazione non usa l'interoperabilità di Microsoft Teams o le funzionalità di telefonia.

Utilizzo di base

// at some point you will have created a new user identity in your trusted service
CommunicationUserIdentifier newUser = await identityClient.CreateUser();

// and then send newUser.Id down to your client application
// where you can again create an identifier for the user
var sameUser = new CommunicationUserIdentifier(newUserId);

Informazioni di riferimento sulle API

Utente di Microsoft Teams

MicrosoftTeamsUserIdentifier rappresenta un utente di Teams con l'ID oggetto utente di Microsoft Entra. È possibile recuperare l'ID oggetto utente di Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK. In alternativa, è possibile trovare l'ID come oid attestazione in un token Microsoft Entra o un token di accesso di Microsoft Entra dopo che l'utente ha eseguito l'accesso e acquisito un token.

Utilizzo di base

// get the Teams user's ID from Graph APIs if only the email is known
var user = await graphClient.Users["bob@contoso.com"]
    .Request()
    .GetAsync();

// create an identifier
var teamsUser = new MicrosoftTeamsUserIdentifier(user.Id);

// if you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId: userId, cloud: CommunicationCloudEnvironment.Gcch);

Informazioni di riferimento sulle API

Numero di telefono

PhoneNumberIdentifier rappresenta un numero di telefono. Il servizio presuppone che i numeri di telefono siano formattati in formato E.164.

Utilizzo di base

// create an identifier
var phoneNumber = new PhoneNumberIdentifier("+112345556789");

Informazioni di riferimento sulle API

Applicazione Microsoft Teams

L'interfaccia MicrosoftTeamsAppIdentifier rappresenta un bot delle applicazioni di Teams Voice, come ad esempio Coda delle chiamate e Operatore automatico con l'ID oggetto bot Microsoft Entra. Le applicazioni di Teams devono essere configurate con un account di risorsa. È possibile recuperare l'ID oggetto bot Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK.

Utilizzo di base

// Get the Microsoft Teams App's ID from Graph APIs
var users = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","id" };
	requestConfiguration.QueryParameters.Filter = filterConditions;
});

// Here we assume that you have a function GetBotFromUsers that gets the bot from the returned response
var bot = GetBotFromUsers(users);

// Create an identifier
var teamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.Id);

// If you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.Id, CommunicationCloudEnvironment.Gcch);

Informazioni di riferimento sulle API

Sconosciuto

UnknownIdentifier esiste per la correzione futura e potrebbe essere presente in una versione precedente di SDK in cui sia stato recentemente introdotto un nuovo tipo di identificatore. Qualsiasi identificatore sconosciuto dal servizio verrà deserializzato in UnknownIdentifier in SDK.

Utilizzo di base

// create an identifier
var unknown = new UnknownIdentifier("a raw id that originated in the service");

Informazioni di riferimento sulle API

Come gestire la `CommunicationIdentifier` classe base

Mentre si costruiscono identificatori per un tipo concreto passato all'SDK, l'SDK restituisce un CommunicationIdentifier protocollo. È facile eseguire il down-cast a un tipo concreto e si consiglia un'istruzione switch-case con criteri di ricerca:

switch (communicationIdentifier)
{
    case CommunicationUserIdentifier communicationUser:
        Console.WriteLine($"Communication user: {communicationUser.Id}");
        break;
    case MicrosoftTeamsUserIdentifier teamsUser:
        Console.WriteLine($"Teams user: {teamsUser.UserId}");
        break;
    case MicrosoftTeamsAppIdentifier teamsApp:
        Console.WriteLine($"Teams app: {teamsApp.AppId}");
        break;
    case PhoneNumberIdentifier phoneNumber:
        Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}");
        break;
    case UnknownIdentifier unknown:
        Console.WriteLine($"Unknown: {unknown.Id}");
        break;
    default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Rappresentazione dell'ID non elaborato

In alcuni casi è necessario serializzare un identificatore in una stringa flat. Ad esempio, se si vuole archiviare l'identificatore in una tabella di database o se lo si vuole usare come parametro URL.

A tale scopo, gli identificatori hanno un'altra rappresentazione denominata RawId. Un identificatore può sempre essere convertito nell'ID non elaborato corrispondente e un ID non elaborato valido può sempre essere convertito in un identificatore.

Poiché Azure.Communication.Common 1.2.0 l'SDK consente la conversione:

// get an identifier's raw Id
string rawId = communicationIdentifier.RawId;

// create an identifier from a given raw Id
CommunicationIdentifier identifier = CommunicationIdentifier.FromRawId(rawId);

Un ID non elaborato non valido verrà semplicemente convertito in un UnknownIdentifier nell'SDK e qualsiasi convalida avviene solo sul lato servizio.

Utente di comunicazione

CommunicationUserIdentifier rappresenta un'identità utente creata usando Identity SDK o l'API REST. È l'unico identificatore usato se l'applicazione non usa l'interoperabilità di Microsoft Teams o le funzionalità di telefonia.

Utilizzo di base

# at some point you will have created a new user identity in your trusted service
new_user = identity_client.create_user()

# and then send new_user.properties['id'] down to your client application
# where you can again create an identifier for the user
same_user = CommunicationUserIdentifier(new_user_id)

Informazioni di riferimento sulle API

Utente di Microsoft Teams

MicrosoftTeamsUserIdentifier rappresenta un utente di Teams con l'ID oggetto utente di Microsoft Entra. È possibile recuperare l'ID oggetto utente di Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK. In alternativa, è possibile trovare l'ID come oid attestazione in un token Microsoft Entra o un token di accesso di Microsoft Entra dopo che l'utente ha eseguito l'accesso e acquisito un token.

Utilizzo di base

# get the Teams user's ID from Graph APIs if only the email is known
user_id = graph_client.get("/users/bob@contoso.com").json().get("id");

# create an identifier
teams_user = MicrosoftTeamsUserIdentifier(user_id)

# if you're not operating in the public cloud, you must also pass the right Cloud type.
gcch_teams_user = MicrosoftTeamsUserIdentifier(user_id, cloud=CommunicationCloudEnvironment.GCCH)

Informazioni di riferimento sulle API

Numero di telefono

PhoneNumberIdentifier rappresenta un numero di telefono. Il servizio presuppone che i numeri di telefono siano formattati in formato E.164.

Utilizzo di base

# create an identifier
phone_number = PhoneNumberIdentifier("+112345556789")

Informazioni di riferimento sulle API

Applicazione Microsoft Teams

L'interfaccia MicrosoftTeamsAppIdentifier rappresenta un bot delle applicazioni di Teams Voice, come ad esempio Coda delle chiamate e Operatore automatico con l'ID oggetto bot Microsoft Entra. Le applicazioni di Teams devono essere configurate con un account di risorsa. È possibile recuperare l'ID oggetto bot Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK.

Utilizzo di base

# Get the Microsoft Teams App's ID from Graph APIs
users = graph_client.get("/users").json()

# Here we assume that you have a function get_bot_from_users that gets the bot from the returned response
bot = get_bot_from_users(users);

# Create an identifier
teams_app_identifier = MicrosoftTeamsAppIdentifier(app_id=bot.get("id"))

# If you're not operating in the public cloud, you must also pass the right Cloud type.
gcch_teams_app_identifier = MicrosoftTeamsAppIdentifier(
            app_id=bot.get("id"),
            cloud=CommunicationCloudEnvironment.GCCH
        )

Informazioni di riferimento sulle API

Sconosciuto

UnknownIdentifier esiste per la correzione futura e potrebbe essere presente in una versione precedente di SDK in cui sia stato recentemente introdotto un nuovo tipo di identificatore. Qualsiasi identificatore sconosciuto dal servizio verrà deserializzato in UnknownIdentifier in SDK.

Utilizzo di base

# create an identifier
unknown = UnknownIdentifier("a raw id that originated in the service")

Informazioni di riferimento sulle API

Come gestire la `CommunicationIdentifier` classe base

Mentre si costruiscono identificatori per un tipo concreto passato all'SDK, l'SDK restituisce un CommunicationIdentifier protocollo. Le classi di identificatori concreti sono solo il protocollo CommunicationIdentifier insieme a un dizionario tipizzato denominato properties. È quindi possibile usare criteri di ricerca per la variabile di istanza del kind protocollo per eseguire la conversione nel tipo concreto:

match communication_identifier.kind:
    case CommunicationIdentifierKind.COMMUNICATION_USER:
        print(f"Communication user: {communication_identifier.properties['id']}")
    case CommunicationIdentifierKind.MICROSOFT_TEAMS_USER:
        print(f"Teams user: {communication_identifier.properties['user_id']}")
    case CommunicationIdentifierKind.MICROSOFT_TEAMS_APP:
        print(f"Teams app: {communication_identifier.properties['app_id']}")
    case CommunicationIdentifierKind.PHONE_NUMBER:
        print(f"Phone number: {communication_identifier.properties['value']}")
    case CommunicationIdentifierKind.UNKNOWN:
        print(f"Unknown: {communication_identifier.raw_id}")
    case _:
        # be careful here whether you want to throw because a new SDK version
        # can introduce new identifier types

Rappresentazione dell'ID non elaborato

In alcuni casi è necessario serializzare un identificatore in una stringa flat. Ad esempio, se si vuole archiviare l'identificatore in una tabella di database o se lo si vuole usare come parametro URL.

A tale scopo, gli identificatori hanno un'altra rappresentazione denominata RawId. Un identificatore può sempre essere convertito nell'ID non elaborato corrispondente e un ID non elaborato valido può sempre essere convertito in un identificatore.

L'SDK consente la conversione:

# get an identifier's raw Id
raw_id = communication_identifier.raw_id

# create an identifier from a given raw Id
identifier = identifier_from_raw_id(raw_id)

Un ID non elaborato non valido verrà semplicemente convertito in un UnknownIdentifier nell'SDK e qualsiasi convalida avviene solo sul lato servizio.

Utente di comunicazione

CommunicationUserIdentifier rappresenta un'identità utente creata usando Identity SDK o l'API REST. È l'unico identificatore usato se l'applicazione non usa l'interoperabilità di Microsoft Teams o le funzionalità di telefonia.

Utilizzo di base

// at some point you will have created a new user identity in your trusted service
CommunicationUserIdentifier newUser = identityClient.CreateUser();

// and then send newUser.getId() down to your client application
// where you can again create an identifier for the user
var sameUser = new CommunicationUserIdentifier(newUserId);

Informazioni di riferimento sulle API

Utente di Microsoft Teams

MicrosoftTeamsUserIdentifier rappresenta un utente di Teams con l'ID oggetto utente di Microsoft Entra. È possibile recuperare l'ID oggetto utente di Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK. In alternativa, è possibile trovare l'ID come oid attestazione in un token Microsoft Entra o un token di accesso di Microsoft Entra dopo che l'utente ha eseguito l'accesso e acquisito un token.

Utilizzo di base

// get the Teams user's ID from Graph APIs if only the email is known
var user = graphClient.users("bob@contoso.com")
    .buildRequest()
    .get();

// create an identifier
var teamsUser = new MicrosoftTeamsUserIdentifier(user.id);

// if you're not operating in the public cloud, you must also set the right Cloud type.
var gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);

Informazioni di riferimento sulle API

Numero di telefono

PhoneNumberIdentifier rappresenta un numero di telefono. Il servizio presuppone che i numeri di telefono siano formattati in formato E.164.

Utilizzo di base

// create an identifier
var phoneNumber = new PhoneNumberIdentifier("+112345556789");

Informazioni di riferimento sulle API

Applicazione Microsoft Teams

L'interfaccia MicrosoftTeamsAppIdentifier rappresenta un bot delle applicazioni di Teams Voice, come ad esempio Coda delle chiamate e Operatore automatico con l'ID oggetto bot Microsoft Entra. Le applicazioni di Teams devono essere configurate con un account di risorsa. È possibile recuperare l'ID oggetto bot Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK.

Utilizzo di base

// Get the Microsoft Teams App's ID from Graph APIs
var user = graphClient.users()
	.buildRequest()
	.filter(filterConditions)
	.select("displayName,id")
	.get();

//Here we assume that you have a function getBotFromUsers that gets the bot from the returned response
var bot = getBotFromUsers(users);

// Create an identifier
var teamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id);

// If you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id, CommunicationCloudEnvironment.GCCH);

Informazioni di riferimento sulle API

Sconosciuto

UnknownIdentifier esiste per la correzione futura e potrebbe essere presente in una versione precedente di SDK in cui sia stato recentemente introdotto un nuovo tipo di identificatore. Qualsiasi identificatore sconosciuto dal servizio verrà deserializzato in UnknownIdentifier in SDK.

Utilizzo di base

// create an identifier
var unknown = new UnknownIdentifier("a raw id that originated in the service");

Informazioni di riferimento sulle API

Come gestire la `CommunicationIdentifier` classe base

Mentre si costruiscono identificatori per un tipo concreto passato all'SDK, l'SDK restituisce un sunto CommunicationIdentifier. È possibile eseguire nuovamente il down-cast a un tipo concreto:

if (communicationIdentifier instanceof CommunicationUserIdentifier) {
    System.out.println("Communication user: " + ((CommunicationUserIdentifier)communicationIdentifier).getId());
}
else if (communicationIdentifier instanceof MicrosoftTeamsUserIdentifier) {
    System.out.println("Teams user: " + ((MicrosoftTeamsUserIdentifier)communicationIdentifier).getUserId());
}
else if (communicationIdentifier instanceof  MicrosoftTeamsAppIdentifier) {
    Log.i(tag, "Teams app: " + (( MicrosoftTeamsAppIdentifier)communicationIdentifier).getAppId());
}
else if (communicationIdentifier instanceof PhoneNumberIdentifier) {
    System.out.println("Phone number: " + ((PhoneNumberIdentifier)communicationIdentifier).getPhoneNumber());
}
else if (communicationIdentifier instanceof UnknownIdentifier) {
    System.out.println("Unkown user: " + ((UnknownIdentifier)communicationIdentifier).getId());
}
else {
    // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
}

Rappresentazione dell'ID non elaborato

In alcuni casi è necessario serializzare un identificatore in una stringa flat. Ad esempio, se si vuole archiviare l'identificatore in una tabella di database o se lo si vuole usare come parametro URL.

A tale scopo, gli identificatori hanno un'altra rappresentazione denominata RawId. Un identificatore può sempre essere convertito nell'ID non elaborato corrispondente e un ID non elaborato valido può sempre essere convertito in un identificatore.

Poiché azure-communication-common 1.2.0 l'SDK consente la conversione:

// get an identifier's raw Id
String rawId = communicationIdentifier.getRawId();

// create an identifier from a given raw Id
CommunicationIdentifier identifier = CommunicationIdentifier.fromRawId(rawId);

Un ID non elaborato non valido verrà semplicemente convertito in un UnknownIdentifier nell'SDK e qualsiasi convalida avviene solo sul lato servizio.

Utente di comunicazione

CommunicationUserIdentifier rappresenta un'identità utente creata usando Identity SDK o l'API REST. È l'unico identificatore usato se l'applicazione non usa l'interoperabilità di Microsoft Teams o le funzionalità di telefonia.

Utilizzo di base

// at some point you will have created a new user identity in your trusted service
// and send the new user id down to your client application
// where you can create an identifier for the user
let user = CommunicationUserIdentifier(newUserId)

Informazioni di riferimento sulle API

Utente di Microsoft Teams

MicrosoftTeamsUserIdentifier rappresenta un utente di Teams con l'ID oggetto utente di Microsoft Entra. È possibile recuperare l'ID oggetto utente di Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK. In alternativa, è possibile trovare l'ID come oid attestazione in un ID token o un token di accesso di Microsoft Entra dopo che l'utente ha eseguito l'accesso e acquisito un token.

Utilizzo di base

// get the Teams user's ID if only the email is known, assuming a helper method for the Graph API
let userId = await getUserIdFromGraph("bob@contoso.com")

// create an identifier
let teamsUser = MicrosoftTeamsUserIdentifier(userId: userId)

// if you're not operating in the public cloud, you must also pass the right Cloud type.
let gcchTeamsUser = MicrosoftTeamsUserIdentifier(userId: userId, cloud: CommunicationCloudEnvironment.Gcch)

Informazioni di riferimento sulle API

Numero di telefono

PhoneNumberIdentifier rappresenta un numero di telefono. Il servizio presuppone che i numeri di telefono siano formattati in formato E.164.

Utilizzo di base

// create an identifier
let phoneNumber = PhoneNumberIdentifier(phoneNumber: "+112345556789")

Informazioni di riferimento sulle API

Applicazione Microsoft Teams

L'interfaccia MicrosoftTeamsAppIdentifier rappresenta un bot delle applicazioni di Teams Voice, come ad esempio Coda delle chiamate e Operatore automatico con l'ID oggetto bot Microsoft Entra. Le applicazioni di Teams devono essere configurate con un account di risorsa. È possibile recuperare l'ID oggetto bot Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK.

Utilizzo di base

// Get the Microsoft Teams App's ID from Graph APIs, assuming a helper method for the Graph API
let botId = await getBotIdFromGraph()

// Create an identifier
let teamsAppIdentifier = MicrosoftTeamsAppIdentifier(appId: botId)

// If you're not operating in the public cloud, you must also pass the right Cloud type.
let gcchTeamsAppIdentifier = MicrosoftTeamsAppIdentifier(appId: botId, cloudEnvironment: CommunicationCloudEnvironment.Gcch)

Informazioni di riferimento sulle API

Sconosciuto

UnknownIdentifier esiste per la correzione futura e potrebbe essere presente in una versione precedente di SDK in cui sia stato recentemente introdotto un nuovo tipo di identificatore. Qualsiasi identificatore sconosciuto dal servizio verrà deserializzato in UnknownIdentifier in SDK.

Utilizzo di base

// create an identifier
let unknown = UnknownIdentifier("a raw id that originated in the service")

Informazioni di riferimento sulle API

Come gestire il `CommunicationIdentifier` protocollo di base

Mentre si costruiscono identificatori per un tipo concreto passato all'SDK, l'SDK restituisce un CommunicationIdentifier protocollo. È facile eseguire nuovamente il down-cast a un tipo concreto ed è consigliabile usare un'istruzione switch-case con criteri di ricerca:

switch (communicationIdentifier)
{
    case let communicationUser as CommunicationUserIdentifier:
        print(#"Communication user: \(communicationUser.id)"#)
    case let teamsUser as MicrosoftTeamsUserIdentifier:
        print(#"Teams user: \(teamsUser.UserId)"#)
    case let teamsApp as MicrosoftTeamsAppIdentifier:
        print(#"Teams app: \(teamsApp.appId)"#)
    case let phoneNumber as PhoneNumberIdentifier:
        print(#"Phone number: \(phoneNumber.PhoneNumber)"#)
    case let unknown as UnknownIdentifier:
        print(#"Unknown: \(unknown.Id)"#)
    @unknown default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Rappresentazione dell'ID non elaborato

In alcuni casi è necessario serializzare un identificatore in una stringa flat. Ad esempio, se si vuole archiviare l'identificatore in una tabella di database o se lo si vuole usare come parametro URL.

A tale scopo, gli identificatori hanno un'altra rappresentazione denominata RawId. Un identificatore può sempre essere convertito nell'ID non elaborato corrispondente e un ID non elaborato valido può sempre essere convertito in un identificatore.

Poiché Azure.Communication.Common 1.1.0 l'SDK consente la conversione:

Swift

// get an identifier's raw Id
let rawId = communicationIdentifier.rawId;

// create an identifier from a given raw Id
let identifier = createCommunicationIdentifier(fromRawId: rawId);

Un ID non elaborato non valido verrà semplicemente convertito in un UnknownIdentifier nell'SDK e qualsiasi convalida avviene solo sul lato servizio.

Utente di comunicazione

CommunicationUserIdentifier rappresenta un'identità utente creata usando Identity SDK o l'API REST. È l'unico identificatore usato se l'applicazione non usa l'interoperabilità di Microsoft Teams o le funzionalità di telefonia.

Utilizzo di base

// at some point you will have created a new user identity in your trusted service
CommunicationUserIdentifier newUser = identityClient.CreateUser();

// and then send newUser.getId() down to your client application
// where you can again create an identifier for the user
CommunicationUserIdentifier sameUser = new CommunicationUserIdentifier(newUserId);

Informazioni di riferimento sulle API

Utente di Microsoft Teams

MicrosoftTeamsUserIdentifier rappresenta un utente di Teams con l'ID oggetto utente di Microsoft Entra. È possibile recuperare l'ID oggetto utente di Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK. In alternativa, è possibile trovare l'ID come oid attestazione in un ID token o un token di accesso di Microsoft Entra dopo che l'utente ha eseguito l'accesso e acquisito un token.

Utilizzo di base

// get the Teams user's ID from Graph APIs if only the email is known
User user = graphClient.users("bob@contoso.com")
    .buildRequest()
    .get();

// create an identifier
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(user.id);

// if you're not operating in the public cloud, you must also set the right Cloud type.
MicrosoftTeamsUserIdentifier gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);

Informazioni di riferimento sulle API

Numero di telefono

PhoneNumberIdentifier rappresenta un numero di telefono. Il servizio presuppone che i numeri di telefono siano formattati in formato E.164.

Utilizzo di base

// create an identifier
PhoneNumberIdentifier phoneNumber = new PhoneNumberIdentifier("+112345556789");

Informazioni di riferimento sulle API

Applicazione Microsoft Teams

L'interfaccia MicrosoftTeamsAppIdentifier rappresenta un bot delle applicazioni di Teams Voice, come ad esempio Coda delle chiamate e Operatore automatico con l'ID oggetto bot Microsoft Entra. Le applicazioni di Teams devono essere configurate con un account di risorsa. È possibile recuperare l'ID oggetto bot Microsoft Entra tramite l'endpoint REST API /utente di Microsoft Graph dalla idproprietà nella risposta. Per altre informazioni su come usare Microsoft Graph, provare Graph Explorer ed esaminare Graph SDK.

Utilizzo di base

// Get the Microsoft Teams App's ID from Graph APIs
UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter(filterConditions)
	.select("displayName,id")
	.get();

//Here we assume that you have a function getBotFromUsers that gets the bot from the returned response
User bot = getBotFromUsers(users);

// Create an identifier
MicrosoftTeamsAppIdentifier teamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id);

// If you're not operating in the public cloud, you must also pass the right Cloud type.
MicrosoftTeamsAppIdentifier gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id, CommunicationCloudEnvironment.GCCH);

Informazioni di riferimento sulle API

Sconosciuto

UnknownIdentifier esiste per la correzione futura e potrebbe essere presente in una versione precedente di SDK in cui sia stato recentemente introdotto un nuovo tipo di identificatore. Qualsiasi identificatore sconosciuto dal servizio verrà deserializzato in UnknownIdentifier in SDK.

Utilizzo di base

// create an identifier
UnknownIdentifier unknown = new UnknownIdentifier("a raw id that originated in the service");

Informazioni di riferimento sulle API