Comprendre les types d’identificateurs
Les SDK Communication Services et les API REST utilisent le type identificateur pour identifier qui communique avec qui. Par exemple, les identificateurs spécifient qui appeler ou qui a envoyé un message de conversation.
Selon le contexte, les identificateurs sont wrappés avec des propriétés supplémentaires, comme à l’intérieur de ChatParticipant
dans le SDK Chat ou à l’intérieur de RemoteParticipant
dans le SDK Calling.
Dans cet article, vous allez découvrir différents types d’identificateurs et voir à quoi ils ressemblent dans plusieurs langages de programmation. Vous obtiendrez également des conseils sur la façon de les utiliser.
Type CommunicationIdentifier
Il existe deux types d’identités : les identités utilisateur que vous créez vous-même et les identités externes. Les utilisateurs et numéros de téléphone Microsoft Teams sont des identités externes qui entrent en jeu dans les scénarios d’interopérabilité. Chacun de ces différents types d’identité est représenté par un identificateur correspondant. Un identificateur est un type structuré qui offre une sécurité de type et fonctionne bien avec la complétion de code de votre éditeur.
Utilisateur de communication
L’interface 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
const newUser = await identityClient.createUser();
// and then send newUser.communicationUserId down to your client application
// where you can again create an identifier for the user
const sameUser = { communicationUserId: newUserId };
Informations de référence sur l'API
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 "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;
}
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 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;
}
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.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
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 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("Unknown 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 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;
}
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
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) {
Log.i(tag, "Communication user: " + ((CommunicationUserIdentifier)communicationIdentifier).getId());
}
else if (communicationIdentifier instanceof MicrosoftTeamsUserIdentifier) {
Log.i(tag, "Teams user: " + ((MicrosoftTeamsUserIdentifier)communicationIdentifier).getUserId());
}
else if (communicationIdentifier instanceof MicrosoftTeamsAppIdentifier) {
Log.i(tag, "Teams app: " + (( MicrosoftTeamsAppIdentifier)communicationIdentifier).getAppId());
}
else if (communicationIdentifier instanceof PhoneNumberIdentifier) {
Log.i(tag, "Phone number: " + ((PhoneNumberIdentifier)communicationIdentifier).getPhoneNumber());
}
else if (communicationIdentifier instanceof UnknownIdentifier) {
Log.i(tag, "Unknown 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.1.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.
Dans les API REST, l’identificateur est un type polymorphe : vous construisez un objet JSON et une propriété mappée à un sous-type d’identificateur concret. Pour des raisons pratiques et de compatibilité descendante, les propriétés kind
et rawId
sont facultatives dans les demandes, mais sont renseignées dans les réponses de service.
Utilisateur de communication
CommunicationUserIdentifierModel
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
// you can specify an identifier with the id of the new user in a request
{
"communicationUser": {
"id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
}
}
// the corresponding serialization in a response
{
"kind": "communicationUser",
"rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715",
"communicationUser": {
"id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
}
}
Vous pouvez trouver un exemple de demande qui inclut un identificateur dans l’API REST de Chat pour ajouter un participant, et un exemple de réponse avec un identificateur sous Obtenir un message de conversation.
Informations de référence sur l'API
CommunicationUserIdentifierModel
Utilisateur Microsoft Teams
MicrosoftTeamsUserIdentifierModel
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
// request
{
"microsoftTeamsUser": {
"userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}
}
// response
{
"kind": "microsoftTeamsUser",
"rawId": "8:orgid:00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"microsoftTeamsUser": {
"userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}
}
// if you're not operating in the public cloud, you must also pass the right Cloud type in a request
{
"microsoftTeamsUser": {
"userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"cloud": "gcch"
}
}
// response
{
"kind": "microsoftTeamsUser",
"rawId": "8:gcch:00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"microsoftTeamsUser": {
"userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"isAnonymous": false,
"cloud": "gcch"
}
}
Informations de référence sur l'API
MicrosoftTeamsUserIdentifierModel
Numéro de téléphone
PhoneNumberIdentifierModel
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
// request
{
"phoneNumber": {
"value": "+112345556789"
}
}
// response
{
"kind": "phoneNumber",
"rawId": "4:+112345556789",
"phoneNumber": {
"value": "+112345556789"
}
}
Informations de référence sur l'API
Application Microsoft Teams
MicrosoftTeamsAppIdentifierModel
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
// request
{
"microsoftTeamsApp": {
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444"
}
}
// response
{
"kind": "microsoftTeamsApp",
"rawId": "28:orgid:00001111-aaaa-2222-bbbb-3333cccc4444",
"microsoftTeamsApp": {
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444"
}
}
// if you're not operating in the public cloud, you must also pass the right Cloud type in a request
{
"microsoftTeamsApp": {
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"cloud": "gcch"
}
}
// response
{
"kind": "microsoftTeamsApp",
"rawId": "28:gcch:00001111-aaaa-2222-bbbb-3333cccc4444",
"microsoftTeamsApp": {
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"cloud": "gcch"
}
}
Informations de référence sur l'API
MicrosoftTeamsAppIdentifierModel
Inconnu
Si un nouvel identificateur est introduit dans un service, il est rétrogradé en CommunicationIdentifierModel
si vous utilisez une ancienne version de l’API.
Utilisation de base
// request
{
"rawId": "a raw id that originated in the service"
}
// response
{
"kind": "unknown",
"rawId": "a raw id that originated in the service"
}
Informations de référence sur l'API
Comment gérer CommunicationIdentifierModel
dans les réponses
Les versions récentes de l’API renseignent une propriété kind
que vous pouvez utiliser à des fins de discrimination :
switch (communicationIdentifier.kind)
{
case "communicationUser":
console.log(`Communication user: ${communicationIdentifier.communicationUser.id}`);
break;
case "microsoftTeamsUser":
console.log(`Teams user: ${communicationIdentifier.microsoftTeamsUser.userId}`);
break;
case "microsoftTeamsApp":
console.log(`Teams user: ${communicationIdentifier.microsoftTeamsApp.appId}`);
break;
case "phoneNumber":
console.log(`Phone number: ${communicationIdentifier.phoneNumber.value}`);
break;
case "unknown":
console.log(`Unknown: ${communicationIdentifier.rawId}`);
break;
default:
// this case should not be hit because adding a new identifier type requires a new API version
// if it does get hit, please file an issue on https://github.com/Azure/azure-rest-api-specs/issues
break;
}
Sur les anciennes versions d’API, la propriété kind
est manquante et vous devez vérifier l’existence de la sous-propriété appropriée :
if (communicationIdentifier.communicationUser) {
console.log(`Communication user: ${communicationIdentifier.communicationUser.id}`);
} else if (communicationIdentifier.microsoftTeamsUser) {
console.log(`Teams user: ${communicationIdentifier.microsoftTeamsUser.userId}`);
} else if (communicationIdentifier.microsoftTeamsApp) {
console.log(`Teams app: ${communicationIdentifier.microsoftTeamsApp.appId}`);
} else if (communicationIdentifier.phoneNumber) {
console.log(`Phone number: ${communicationIdentifier.phoneNumber.value}`);
} else {
console.log(`Unknown: ${communicationIdentifier.rawId}`);
}
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.
Si vous utilisez le SDK Azure, il vous aidera à effectuer la conversion. Si vous utilisez directement l’API REST, vous devez construire l’ID brut manuellement, comme décrit ci-dessous.
Utilisateur de communication
Identificateur :
{
"communicationUser": {
"id": "[communicationUserId]"
}
}
ID brut :
[communicationUserId]
L’ID brut est le même que communicationUser.id
.
Utilisateur Microsoft Teams
Identificateur :
{
"microsoftTeamsUser": {
"userId": "[entraUserId]"
}
}
ID brut :
8:orgid:[entraUserId]
L’ID brut est l’ID d’objet utilisateur Microsoft Entra avec le préfixe 8:orgid:
.
Identificateur :
{
"microsoftTeamsUser": {
"userId": "[entraUserId]",
"cloud": "gcch"
}
}
ID brut :
8:gcch:[entraUserId]
L’ID brut est l’ID d’objet utilisateur Microsoft Entra avec le préfixe 8:gcch:
ou 8:dod:
en fonction de l’environnement cloud.
Identificateur :
{
"microsoftTeamsUser": {
"userId": "[visitorUserId]",
"isAnonymous": true
}
}
ID brut :
8:teamsvisitor:[visitorUserId]
L’ID brut est l’ID de visiteur Teams préfixé par 8:teamsvisitor:
. L’ID de visiteur Teams est un ID temporaire généré par Teams pour permettre l’accès aux réunions.
Numéro de téléphone
Identificateur :
{
"phoneNumber": {
"value": "+1123455567"
}
}
ID brut :
4:+1123455567
L’ID brut est le numéro de téléphone au format E.164 avec le préfixe 4:
.
Application Microsoft Teams
Identificateur :
{
"microsoftTeamsApp": {
"appId": "[entraUserId]"
}
}
ID brut :
28:orgid:[entraUserId]
L’identifiant brut est l’identifiant de l’objet utilisateur Entra de l’application, préfixé par 28:orgid:
.
Identificateur :
{
"microsoftTeamsUser": {
"userId": "[entraUserId]",
"cloud": "gcch"
}
}
ID brut :
28:gcch:[entraUserId]
L’identifiant brut est l’identifiant de l’objet utilisateur Entra de l’application, préfixé par 28:gcch:
ou 28:dod:
en fonction de l’environnement cloud.
Inconnu
Identificateur :
{
"rawId": "[unknown identifier id]"
}
ID brut :
[unknown identifier id]
Si un ID brut n’est pas valide, le service fait échouer la demande.
Étapes suivantes
- Pour une présentation des identités de communication, consultez Modèle d’identité.
- Pour savoir comment créer rapidement des identités à des fins de test, consultez le démarrage rapide de création rapide d’identité.
- Pour savoir comment utiliser Communication Services avec Microsoft Teams, consultez Interopérabilité de Teams.
- Pour savoir comment utiliser un ID brut, consultez Cas d’usage pour les identificateurs de chaîne dans les SDK Communication.