Skip to content

Commit 227bdd7

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #209047 from DominikMe/communication-identifiers
Communication Services: Explaining identifiers
2 parents 0e163ac + d5a342d commit 227bdd7

File tree

10 files changed

+1144
-0
lines changed

10 files changed

+1144
-0
lines changed

‎articles/communication-services/concepts/identifiers.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: Communication Identifier types
3+
titleSuffix: An Azure Communication Services concept
4+
description: Understand identifier types and their usage
5+
author: DominikMe
6+
manager: RezaJooyandeh
7+
services: azure-communication-services
8+
9+
ms.author: domessin
10+
ms.date: 08/30/2022
11+
ms.topic: conceptual
12+
ms.service: azure-communication-services
13+
ms.subservice: identity
14+
zone_pivot_groups: acs-js-csharp-java-python-ios-android-rest
15+
---
16+
17+
# Understand Identifier types
18+
19+
Communication Services SDKs and REST APIs use the *identifier* type to identify who is communicating with whom. For example, identifiers specify who to call, or who has sent a chat message.
20+
21+
Depending on context, identifiers get wrapped with extra properties, like inside the `ChatParticipant` in the Chat SDK or inside the `RemoteParticipant` in the Calling SDK.
22+
23+
In this article, you'll learn about different types of identifiers and how they look across programming languages. You'll also get tips on how to use them.
24+
25+
26+
## The CommunicationIdentifier type
27+
28+
There are user identities that you create yourself and there are external identities. Microsoft Teams users and phone numbers are external identities that come to play in interop scenarios. Each of these different identity types has a corresponding identifier that represents it. An identifier is a structured type that offers type-safety and works well with your editor's code completion.
29+
30+
::: zone pivot="programming-language-javascript"
31+
[!INCLUDE [Identifiers in the JavaScript SDK](./includes/identifiers/identifiers-js.md)]
32+
::: zone-end
33+
34+
::: zone pivot="programming-language-csharp"
35+
[!INCLUDE [Identifiers in the .NET SDK](./includes/identifiers/identifiers-net.md)]
36+
::: zone-end
37+
38+
::: zone pivot="programming-language-python"
39+
[!INCLUDE [Identifiers in the Python SDK](./includes/identifiers/identifiers-python.md)]
40+
::: zone-end
41+
42+
::: zone pivot="programming-language-java"
43+
[!INCLUDE [Identifiers in the Java SDK](./includes/identifiers/identifiers-java.md)]
44+
::: zone-end
45+
46+
::: zone pivot="programming-language-ios"
47+
[!INCLUDE [Identifiers in the iOS SDK](./includes/identifiers/identifiers-ios.md)]
48+
::: zone-end
49+
50+
::: zone pivot="programming-language-android"
51+
[!INCLUDE [Identifiers in the Android SDK](./includes/identifiers/identifiers-android.md)]
52+
::: zone-end
53+
54+
::: zone pivot="programming-language-rest"
55+
[!INCLUDE [Identifiers in the REST API](./includes/identifiers/identifiers-rest.md)]
56+
::: zone-end
57+
58+
59+
## Next steps
60+
61+
* For an introduction to communication identities, see [Identity model](./identity-model.md).
62+
* To learn how to quickly create identities for testing, see the [quick-create identity quickstart](../quickstarts/identity/quick-create-identity.md).
63+
* To learn how to use Communication Services together with Microsoft Teams, see [Teams interoperability](./teams-interop.md).

‎articles/communication-services/concepts/includes/identifiers/identifiers-android.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: azure-communication-services
5+
author: DominikMe
6+
manager: RezaJooyandeh
7+
8+
ms.service: azure-communication-services
9+
ms.subservice: azure-communication-services
10+
ms.date: 08/30/2022
11+
ms.topic: include
12+
ms.custom: include file
13+
ms.author: domessin
14+
---
15+
16+
### Communication User identifier
17+
18+
The `CommunicationUserIdentifier` represents a user identity that was created using the [Identity SDK or REST API](../../../quickstarts/access-tokens.md). It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.
19+
20+
21+
#### Basic usage
22+
23+
```java
24+
// at some point you will have created a new user identity in your trusted service
25+
CommunicationUserIdentifier newUser = identityClient.CreateUser();
26+
27+
// and then send newUser.getId() down to your client application
28+
// where you can again create an identifier for the user
29+
var sameUser = new CommunicationUserIdentifier(newUserId);
30+
```
31+
32+
#### API reference
33+
34+
[CommunicationUserIdentifier](https://azure.github.io/azure-sdk-for-android/azure-communication-common/com/azure/android/communication/common/CommunicationUserIdentifier.html)
35+
36+
### Microsoft Teams User identifier
37+
38+
The `MicrosoftTeamsUserIdentifier` represents a Teams user with its Azure AD user object ID. You can retrieve the Azure AD user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response. For more information on how to work with Microsoft Graph, try the [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer?request=users%2F%7Buser-mail%7D&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com) and look into the [Graph SDK](/graph/sdks/sdks-overview). Alternatively, you can find the ID as the `oid` claim in an [Azure AD ID token](/azure/active-directory/develop/id-tokens#payload-claims) or [Azure AD access token](/azure/active-directory/develop/access-tokens#payload-claims) after your user has signed in and acquired a token.
39+
40+
#### Basic usage
41+
42+
```java
43+
// get the Teams user's ID from Graph APIs if only the email is known
44+
var user = await graphClient.users("[email protected]")
45+
.buildRequest()
46+
.get();
47+
48+
// create an identifier
49+
var teamsUser = new MicrosoftTeamsUserIdentifier(user.id);
50+
51+
// if you're not operating in the public cloud, you must also set the right Cloud type.
52+
var gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);
53+
```
54+
55+
#### API reference
56+
57+
[MicrosoftTeamsUserIdentifier](https://azure.github.io/azure-sdk-for-android/azure-communication-common/com/azure/android/communication/common/MicrosoftTeamsUserIdentifier.html)
58+
59+
### Phone Number identifier
60+
61+
The `PhoneNumberIdentifier` represents a phone number. The service assumes that phone numbers are formatted in E.164 format.
62+
63+
#### Basic usage
64+
65+
```java
66+
// create an identifier
67+
var phoneNumber = new PhoneNumberIdentifier("+112345556789");
68+
```
69+
70+
#### API reference
71+
72+
[PhoneNumberIdentifier](https://azure.github.io/azure-sdk-for-android/azure-communication-common/com/azure/android/communication/common/PhoneNumberIdentifier.html)
73+
74+
### Unknown identifier
75+
76+
The `UnknownIdentifier` exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type has been introduced recently. Any unknown identifier from the service will be deserialized to the `UnknownIdentifier` in the SDK.
77+
78+
#### Basic usage
79+
80+
```java
81+
// create an identifier
82+
var unknown = new UnknownIdentifier("a raw id that originated in the service");
83+
```
84+
85+
#### API reference
86+
87+
[UnknownIdentifier](https://azure.github.io/azure-sdk-for-android/azure-communication-common/com/azure/android/communication/common/UnknownIdentifier.html)
88+
89+
### How to handle the `CommunicationIdentifier` base class
90+
91+
While you construct identifiers for a concrete type that you pass *into* the SDK, the SDK returns the abstract `CommunicationIdentifier`. You can down-cast back to a concrete type:
92+
93+
```java
94+
if (communicationIdentifier instanceof CommunicationUserIdentifier) {
95+
Log.i(tag, "Communication user: " + ((CommunicationUserIdentifier)communicationIdentifier).getId());
96+
}
97+
else if (communicationIdentifier instanceof MicrosoftTeamsUserIdentifier) {
98+
Log.i(tag, "Teams user: " + ((MicrosoftTeamsUserIdentifier)communicationIdentifier).getUserId());
99+
}
100+
else if (communicationIdentifier instanceof PhoneNumberIdentifier) {
101+
Log.i(tag, "Phone number: " + ((PhoneNumberIdentifier)communicationIdentifier).getPhoneNumber());
102+
}
103+
else if (communicationIdentifier instanceof UnknownIdentifier) {
104+
Log.i(tag, "Unkown user: " + ((UnknownIdentifier)communicationIdentifier).getId());
105+
}
106+
else {
107+
// be careful here whether you want to throw because a new SDK version
108+
// can introduce new identifier types
109+
}
110+
```
111+
112+
## Raw ID representation
113+
114+
Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.
115+
116+
For that purpose, identifiers have another representation called `RawId`. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.
117+
118+
Since `azure-communication-common 1.1.0` the SDK helps with the conversion:
119+
120+
```java
121+
// get an identifier's raw Id
122+
String rawId = communicationIdentifier.getRawId();
123+
124+
// create an identifier from a given raw Id
125+
CommunicationIdentifier identifier = CommunicationIdentifier.fromRawId(rawId);
126+
```
127+
128+
An invalid raw ID will just convert to an `UnknownIdentifier` in the SDK and any validation only happens service-side.

‎articles/communication-services/concepts/includes/identifiers/identifiers-ios.md

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: azure-communication-services
5+
author: DominikMe
6+
manager: RezaJooyandeh
7+
8+
ms.service: azure-communication-services
9+
ms.subservice: azure-communication-services
10+
ms.date: 08/30/2022
11+
ms.topic: include
12+
ms.custom: include file
13+
ms.author: domessin
14+
---
15+
16+
### Communication User identifier
17+
18+
The `CommunicationUserIdentifier` represents a user identity that was created using the [Identity SDK or REST API](../../../quickstarts/access-tokens.md). It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.
19+
20+
21+
#### Basic usage
22+
23+
```swift
24+
// at some point you will have created a new user identity in your trusted service
25+
// and send the new user id down to your client application
26+
// where you can create an identifier for the user
27+
let user = CommunicationUserIdentifier(newUserId)
28+
```
29+
30+
#### API reference
31+
32+
[CommunicationUserIdentifier](https://azure.github.io/azure-sdk-for-ios/AzureCommunicationCommon/Classes/CommunicationUserIdentifier.html)
33+
34+
### Microsoft Teams User identifier
35+
36+
The `MicrosoftTeamsUserIdentifier` represents a Teams user with its Azure AD user object ID. You can retrieve the Azure AD user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response. For more information on how to work with Microsoft Graph, try the [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer?request=users%2F%7Buser-mail%7D&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com) and look into the [Graph SDK](/graph/sdks/sdks-overview). Alternatively, you can find the ID as the `oid` claim in an [Azure AD ID token](/azure/active-directory/develop/id-tokens#payload-claims) or [Azure AD access token](/azure/active-directory/develop/access-tokens#payload-claims) after your user has signed in and acquired a token.
37+
38+
#### Basic usage
39+
40+
```swift
41+
// get the Teams user's ID if only the email is known, assuming a helper method for the Graph API
42+
let userId = await getUserIdFromGraph("[email protected]")
43+
44+
// create an identifier
45+
let teamsUser = MicrosoftTeamsUserIdentifier(userId: userId)
46+
47+
// if you're not operating in the public cloud, you must also pass the right Cloud type.
48+
gcchTeamsUser = MicrosoftTeamsUserIdentifier(userId: userId, cloud: CommunicationCloudEnvironment.Gcch)
49+
```
50+
51+
#### API reference
52+
53+
[MicrosoftTeamsUserIdentifier](https://azure.github.io/azure-sdk-for-ios/AzureCommunicationCommon/Classes/MicrosoftTeamsUserIdentifier.html)
54+
55+
### Phone Number identifier
56+
57+
The `PhoneNumberIdentifier` represents a phone number. The service assumes that phone numbers are formatted in E.164 format.
58+
59+
#### Basic usage
60+
61+
```swift
62+
// create an identifier
63+
let phoneNumber = PhoneNumberIdentifier(phoneNumber: "+112345556789")
64+
```
65+
66+
#### API reference
67+
68+
[PhoneNumberIdentifier](https://azure.github.io/azure-sdk-for-ios/AzureCommunicationCommon/Classes/PhoneNumberIdentifier.html)
69+
70+
### Unknown identifier
71+
72+
The `UnknownIdentifier` exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type has been introduced recently. Any unknown identifier from the service will be deserialized to the `UnknownIdentifier` in the SDK.
73+
74+
#### Basic usage
75+
76+
```swift
77+
// create an identifier
78+
let unknown = UnknownIdentifier("a raw id that originated in the service")
79+
```
80+
81+
#### API reference
82+
83+
[UnknownIdentifier](https://azure.github.io/azure-sdk-for-ios/AzureCommunicationCommon/Classes/UnknownIdentifier.html)
84+
85+
### How to handle the `CommunicationIdentifier` base protocol
86+
87+
While you construct identifiers for a concrete type that you pass *into* the SDK, the SDK returns the `CommunicationIdentifier` protocol. It's easy to down-cast back to a concrete type and we suggest a switch-case statement with pattern matching:
88+
89+
```swift
90+
switch (communicationIdentifier)
91+
{
92+
case let communicationUser as CommunicationUserIdentifier:
93+
print(#"Communication user: \(communicationUser.id)"#)
94+
case let teamsUser as MicrosoftTeamsUserIdentifier:
95+
print(#"Teams user: \(teamsUser.UserId)"#)
96+
case let phoneNumber as PhoneNumberIdentifier:
97+
print(#"Phone number: \(phoneNumber.PhoneNumber)"#)
98+
case let unknown as UnknownIdentifier:
99+
print(#"Unknown: \(unknown.Id)"#)
100+
@unknown default:
101+
// be careful here whether you want to throw because a new SDK version
102+
// can introduce new identifier types
103+
break;
104+
}
105+
```
106+
107+
## Raw ID representation
108+
109+
Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.
110+
111+
For that purpose, identifiers have another representation called `RawId`. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.
112+
113+
Since `Azure.Communication.Common 1.1.0` the SDK helps with the conversion:
114+
115+
*Swift*
116+
```swift
117+
// get an identifier's raw Id
118+
let rawId = communicationIdentifier.rawId;
119+
120+
// create an identifier from a given raw Id
121+
let identifier = createCommunicationIdentifier(fromRawId: rawId);
122+
```
123+
124+
An invalid raw ID will just convert to an `UnknownIdentifier` in the SDK and any validation only happens service-side.

0 commit comments

Comments
 (0)