Comprendre les types d’identificateurs

Utilisateur Microsoft Teams

L’interface MicrosoftTeamsUserIdentifier représente un utilisateur Teams avec son ID d’objet utilisateur Microsoft Entra. Vous pouvez récupérer l’ID d’objet utilisateur Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph. Vous pouvez également trouver l’ID en tant que revendication oid dans un jeton Microsoft Entra ou un jeton d’accès Microsoft Entra une fois que votre utilisateur s’est connecté et a acquis un jeton.

Utilisation de 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" };

Informations de référence sur l'API

Numéro de téléphone

L’interface PhoneNumberIdentifier représente un numéro de téléphone. Le service part du principe que les numéros de téléphone sont mis en forme au format E.164.

Utilisation de base

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

Informations de référence sur l'API

Application Microsoft Teams

L’interface MicrosoftTeamsAppIdentifier représente un bot des applications Teams Voice comme File d’attente des appels et Standard automatique avec son ID d’objet bot Microsoft Entra. Les applications Teams doivent être configurées avec un compte de ressource. Vous pouvez récupérer l’ID d’objet bot Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph.

Utilisation de 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" };

Informations de référence sur l'API

Inconnu

L’interface UnknownIdentifier existe à des fins de pérennité. Vous pouvez la rencontrer lorsque vous utilisez une ancienne version du SDK et qu’un nouveau type d’identificateur a été récemment introduit. Tout identificateur inconnu du service est désérialisé en UnknownIdentifier dans le SDK.

Utilisation de base

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

Informations de référence sur l'API

Comment gérer l’interface de base `CommunicationIdentifier`

Quand vous construisez des identificateurs pour un type concret que vous passez dans le SDK, ce dernier retourne un CommunicationIdentifierKind, qui est une union discriminée. Il est facile de limiter votre choix à un type concret et nous suggérons une instruction switch-case avec des critères spéciaux :

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 "phoneNumber":
         // narrowed to PhoneNumberKind
        console.log(`Phone number: ${communicationIdentifier.phoneNumber}`);
        break;
    case "unknown":
         // narrowed to UnknownIdentifierKind
        console.log(`Unknown: ${communicationIdentifier.id}`);
        break;
    case "microsoftBot":
        // narrowed to MicrosoftBotIdentifier
        console.log(`Microsoft bot: ${communicationIdentifier.botId}`);
        break;
    default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Les interfaces d’identificateur ont été conçues de sorte que vous n’ayez pas à spécifier kind pour réduire la verbosité, et l’union discriminante avec la propriété kind n’est utilisée que lorsqu’elle est retournée par le SDK. Toutefois, si vous avez besoin de traduire un identificateur en type d’union discriminante correspondant, vous pouvez utiliser cette assistance :

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

Représentation d’ID brut

Parfois, vous devez sérialiser un identificateur en chaîne plate. C’est notamment le cas si vous souhaitez stocker l’identificateur dans une table de base de données ou si vous souhaitez l’utiliser comme paramètre d’URL.

À cette fin, les identificateurs ont une autre représentation appelée RawId. Un identificateur peut toujours être traduit en ID brut correspondant, et un ID brut valide peut toujours être converti en identificateur.

Depuis azure-communication-common@2.1.0, le SDK facilite la conversion :

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

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

Un ID brut non valide est simplement converti en UnknownIdentifier dans le SDK et toute validation se produit uniquement côté service.

Utilisateur de communication

CommunicationUserIdentifier représente une identité d’utilisateur créée avec l’API REST ou le SDK Identity. C’est le seul identificateur utilisé si votre application n’utilise pas les fonctionnalités d’interopérabilité ou de téléphonie Microsoft Teams.

Utilisation de 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);

Informations de référence sur l'API

Utilisateur Microsoft Teams

MicrosoftTeamsUserIdentifier représente un utilisateur Teams avec son ID d’objet utilisateur Microsoft Entra. Vous pouvez récupérer l’ID d’objet utilisateur Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph. Vous pouvez également trouver l’ID en tant que revendication oid dans un jeton Microsoft Entra ou un jeton d’accès Microsoft Entra une fois que votre utilisateur s’est connecté et a acquis un jeton.

Utilisation de 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);

Informations de référence sur l'API

Numéro de téléphone

PhoneNumberIdentifier représente un numéro de téléphone. Le service part du principe que les numéros de téléphone sont mis en forme au format E.164.

Utilisation de base

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

Informations de référence sur l'API

Application Microsoft Teams

L’interface MicrosoftTeamsAppIdentifier représente un bot des applications Teams Voice comme File d’attente des appels et Standard automatique avec son ID d’objet bot Microsoft Entra. Les applications Teams doivent être configurées avec un compte de ressource. Vous pouvez récupérer l’ID d’objet bot Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph.

Utilisation de 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);

Informations de référence sur l'API

Inconnu

UnknownIdentifier existe à des fins de pérennité. Vous pouvez le rencontrer lorsque vous utilisez une ancienne version du SDK et qu’un nouveau type d’identificateur a été récemment introduit. Tout identificateur inconnu du service est désérialisé en UnknownIdentifier dans le SDK.

Utilisation de base

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

Informations de référence sur l'API

Comment gérer la classe de base `CommunicationIdentifier`

Quand vous construisez des identificateurs pour un type concret que vous passez dans le SDK, ce dernier retourne le protocole CommunicationIdentifier. Il est facile d’effectuer un down-cast vers un type concret et nous suggérons une instruction switch-case avec des critères spéciaux :

switch (communicationIdentifier)
{
    case CommunicationUserIdentifier communicationUser:
        Console.WriteLine($"Communication user: {communicationUser.Id}");
        break;
    case MicrosoftTeamsUserIdentifier teamsUser:
        Console.WriteLine($"Teams user: {teamsUser.UserId}");
        break;
    case PhoneNumberIdentifier phoneNumber:
        Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}");
        break;
    case MicrosoftBotIdentifier bot:
        Console.WriteLine($"Microsoft bot: {bot.BotId}");
        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;
}

Représentation d’ID brut

Parfois, vous devez sérialiser un identificateur en chaîne plate. C’est notamment le cas si vous souhaitez stocker l’identificateur dans une table de base de données ou si vous souhaitez l’utiliser comme paramètre d’URL.

À cette fin, les identificateurs ont une autre représentation appelée RawId. Un identificateur peut toujours être traduit en ID brut correspondant, et un ID brut valide peut toujours être converti en identificateur.

Depuis Azure.Communication.Common 1.2.0, le SDK facilite la conversion :

// 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 brut non valide est simplement converti en UnknownIdentifier dans le SDK et toute validation se produit uniquement côté service.

Utilisateur de communication

CommunicationUserIdentifier représente une identité d’utilisateur créée avec l’API REST ou le SDK Identity. C’est le seul identificateur utilisé si votre application n’utilise pas les fonctionnalités d’interopérabilité ou de téléphonie Microsoft Teams.

Utilisation de 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)

Informations de référence sur l'API

Utilisateur Microsoft Teams

MicrosoftTeamsUserIdentifier représente un utilisateur Teams avec son ID d’objet utilisateur Microsoft Entra. Vous pouvez récupérer l’ID d’objet utilisateur Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph. Vous pouvez également trouver l’ID en tant que revendication oid dans un jeton Microsoft Entra ou un jeton d’accès Microsoft Entra une fois que votre utilisateur s’est connecté et a acquis un jeton.

Utilisation de 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)

Informations de référence sur l'API

Numéro de téléphone

PhoneNumberIdentifier représente un numéro de téléphone. Le service part du principe que les numéros de téléphone sont mis en forme au format E.164.

Utilisation de base

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

Informations de référence sur l'API

Application Microsoft Teams

L’interface MicrosoftTeamsAppIdentifier représente un bot des applications Teams Voice comme File d’attente des appels et Standard automatique avec son ID d’objet bot Microsoft Entra. Les applications Teams doivent être configurées avec un compte de ressource. Vous pouvez récupérer l’ID d’objet bot Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph.

Utilisation de 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
        )

Informations de référence sur l'API

Inconnu

UnknownIdentifier existe à des fins de pérennité. Vous pouvez le rencontrer lorsque vous utilisez une ancienne version du SDK et qu’un nouveau type d’identificateur a été récemment introduit. Tout identificateur inconnu du service est désérialisé en UnknownIdentifier dans le SDK.

Utilisation de base

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

Informations de référence sur l'API

Comment gérer la classe de base `CommunicationIdentifier`

Quand vous construisez des identificateurs pour un type concret que vous passez dans le SDK, ce dernier retourne le protocole CommunicationIdentifier. Les classes d’identificateurs concrets sont simplement le protocole CommunicationIdentifier avec un dictionnaire typé appelé properties. Vous pouvez donc utiliser des critères spéciaux sur la variable d’instance kind du protocole pour la traduire en type concret :

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.PHONE_NUMBER:
        print(f"Phone number: {communication_identifier.properties['value']}")
    case CommunicationIdentifierKind.MICROSOFT_BOT:
        print(f"Microsoft bot: {communication_identifier.properties['bot_id']}")
    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

Représentation d’ID brut

Parfois, vous devez sérialiser un identificateur en chaîne plate. C’est notamment le cas si vous souhaitez stocker l’identificateur dans une table de base de données ou si vous souhaitez l’utiliser comme paramètre d’URL.

À cette fin, les identificateurs ont une autre représentation appelée RawId. Un identificateur peut toujours être traduit en ID brut correspondant, et un ID brut valide peut toujours être converti en identificateur.

Le SDK facilite la conversion :

# 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 brut non valide est simplement converti en UnknownIdentifier dans le SDK et toute validation se produit uniquement côté service.

Utilisateur de communication

CommunicationUserIdentifier représente une identité d’utilisateur créée avec l’API REST ou le SDK Identity. C’est le seul identificateur utilisé si votre application n’utilise pas les fonctionnalités d’interopérabilité ou de téléphonie Microsoft Teams.

Utilisation de 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);

Informations de référence sur l'API

Utilisateur Microsoft Teams

MicrosoftTeamsUserIdentifier représente un utilisateur Teams avec son ID d’objet utilisateur Microsoft Entra. Vous pouvez récupérer l’ID d’objet utilisateur Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph. Vous pouvez également trouver l’ID en tant que revendication oid dans un jeton Microsoft Entra ou un jeton d’accès Microsoft Entra une fois que votre utilisateur s’est connecté et a acquis un jeton.

Utilisation de 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);

Informations de référence sur l'API

Numéro de téléphone

PhoneNumberIdentifier représente un numéro de téléphone. Le service part du principe que les numéros de téléphone sont mis en forme au format E.164.

Utilisation de base

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

Informations de référence sur l'API

Application Microsoft Teams

L’interface MicrosoftTeamsAppIdentifier représente un bot des applications Teams Voice comme File d’attente des appels et Standard automatique avec son ID d’objet bot Microsoft Entra. Les applications Teams doivent être configurées avec un compte de ressource. Vous pouvez récupérer l’ID d’objet bot Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph.

Utilisation de 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);

Informations de référence sur l'API

Inconnu

UnknownIdentifier existe à des fins de pérennité. Vous pouvez le rencontrer lorsque vous utilisez une ancienne version du SDK et qu’un nouveau type d’identificateur a été récemment introduit. Tout identificateur inconnu du service est désérialisé en UnknownIdentifier dans le SDK.

Utilisation de base

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

Informations de référence sur l'API

Comment gérer la classe de base `CommunicationIdentifier`

Quand vous construisez des identificateurs pour un type concret que vous passez dans le SDK, ce dernier retourne le type abstract CommunicationIdentifier. Vous pouvez effectuer un down-cast pour revenir à un type concret :

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 PhoneNumberIdentifier) {
    System.out.println("Phone number: " + ((PhoneNumberIdentifier)communicationIdentifier).getPhoneNumber());
}
else if (communicationIdentifier instanceof MicrosoftBotIdentifier) {
    Log.i(tag, "Microsoft bot: " + ((MicrosoftBotIdentifier)communicationIdentifier).getBotId());
}
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
}

Représentation d’ID brut

Parfois, vous devez sérialiser un identificateur en chaîne plate. C’est notamment le cas si vous souhaitez stocker l’identificateur dans une table de base de données ou si vous souhaitez l’utiliser comme paramètre d’URL.

À cette fin, les identificateurs ont une autre représentation appelée RawId. Un identificateur peut toujours être traduit en ID brut correspondant, et un ID brut valide peut toujours être converti en identificateur.

Depuis azure-communication-common 1.2.0, le SDK facilite la conversion :

// 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 brut non valide est simplement converti en UnknownIdentifier dans le SDK et toute validation se produit uniquement côté service.

Utilisateur de communication

CommunicationUserIdentifier représente une identité d’utilisateur créée avec l’API REST ou le SDK Identity. C’est le seul identificateur utilisé si votre application n’utilise pas les fonctionnalités d’interopérabilité ou de téléphonie Microsoft Teams.

Utilisation de 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)

Informations de référence sur l'API

Utilisateur Microsoft Teams

MicrosoftTeamsUserIdentifier représente un utilisateur Teams avec son ID d’objet utilisateur Microsoft Entra. Vous pouvez récupérer l’ID d’objet utilisateur Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph. Vous pouvez également trouver l’ID en tant que revendication oid dans un jeton d’ID ou un jeton d’accès Microsoft Entra une fois que votre utilisateur s’est connecté et a acquis un jeton.

Utilisation de 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)

Informations de référence sur l'API

Numéro de téléphone

PhoneNumberIdentifier représente un numéro de téléphone. Le service part du principe que les numéros de téléphone sont mis en forme au format E.164.

Utilisation de base

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

Informations de référence sur l'API

Application Microsoft Teams

L’interface MicrosoftTeamsAppIdentifier représente un bot des applications Teams Voice comme File d’attente des appels et Standard automatique avec son ID d’objet bot Microsoft Entra. Les applications Teams doivent être configurées avec un compte de ressource. Vous pouvez récupérer l’ID d’objet bot Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph.

Utilisation de 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)

Informations de référence sur l'API

Inconnu

UnknownIdentifier existe à des fins de pérennité. Vous pouvez le rencontrer lorsque vous utilisez une ancienne version du SDK et qu’un nouveau type d’identificateur a été récemment introduit. Tout identificateur inconnu du service est désérialisé en UnknownIdentifier dans le SDK.

Utilisation de base

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

Informations de référence sur l'API

`CommunicationIdentifier`

Quand vous construisez des identificateurs pour un type concret que vous passez dans le SDK, ce dernier retourne le protocole CommunicationIdentifier. Il est facile d’effectuer un down-cast pour revenir à un type concret et nous suggérons une instruction switch-case avec des critères spéciaux :

switch (communicationIdentifier)
{
    case let communicationUser as CommunicationUserIdentifier:
        print(#"Communication user: \(communicationUser.id)"#)
    case let teamsUser as MicrosoftTeamsUserIdentifier:
        print(#"Teams user: \(teamsUser.UserId)"#)
    case let phoneNumber as PhoneNumberIdentifier:
        print(#"Phone number: \(phoneNumber.PhoneNumber)"#)
    case let bot as MicrosoftBotIdentifier:
        print(#"Microsoft bot: \(bot.botId)"#)
    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;
}

Représentation d’ID brut

Parfois, vous devez sérialiser un identificateur en chaîne plate. C’est notamment le cas si vous souhaitez stocker l’identificateur dans une table de base de données ou si vous souhaitez l’utiliser comme paramètre d’URL.

À cette fin, les identificateurs ont une autre représentation appelée RawId. Un identificateur peut toujours être traduit en ID brut correspondant, et un ID brut valide peut toujours être converti en identificateur.

Depuis Azure.Communication.Common 1.1.0, le SDK facilite la conversion :

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 brut non valide est simplement converti en UnknownIdentifier dans le SDK et toute validation se produit uniquement côté service.

Utilisateur de communication

CommunicationUserIdentifier représente une identité d’utilisateur créée avec l’API REST ou le SDK Identity. C’est le seul identificateur utilisé si votre application n’utilise pas les fonctionnalités d’interopérabilité ou de téléphonie Microsoft Teams.

Utilisation de 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);

Informations de référence sur l'API

Utilisateur Microsoft Teams

MicrosoftTeamsUserIdentifier représente un utilisateur Teams avec son ID d’objet utilisateur Microsoft Entra. Vous pouvez récupérer l’ID d’objet utilisateur Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph. Vous pouvez également trouver l’ID en tant que revendication oid dans un jeton d’ID ou un jeton d’accès Microsoft Entra une fois que votre utilisateur s’est connecté et a acquis un jeton.

Utilisation de 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);

Informations de référence sur l'API

Numéro de téléphone

PhoneNumberIdentifier représente un numéro de téléphone. Le service part du principe que les numéros de téléphone sont mis en forme au format E.164.

Utilisation de base

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

Informations de référence sur l'API

Application Microsoft Teams

L’interface MicrosoftTeamsAppIdentifier représente un bot des applications Teams Voice comme File d’attente des appels et Standard automatique avec son ID d’objet bot Microsoft Entra. Les applications Teams doivent être configurées avec un compte de ressource. Vous pouvez récupérer l’ID d’objet bot Microsoft Entra via le point de terminaison /users de l’API REST Microsoft Graph dans la propriété id de la réponse. Pour plus d’informations sur l’utilisation de Microsoft Graph, essayez l’Afficheur Graph et examinez le SDK Graph.

Utilisation de 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);

Informations de référence sur l'API

Inconnu

UnknownIdentifier existe à des fins de pérennité. Vous pouvez le rencontrer lorsque vous utilisez une ancienne version du SDK et qu’un nouveau type d’identificateur a été récemment introduit. Tout identificateur inconnu du service est désérialisé en UnknownIdentifier dans le SDK.

Utilisation de base

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

Informations de référence sur l'API