Skip to content

Commit e9f79b0

Browse files
prmerger-automator[bot]prmerger-automator[bot]
authored
Merge pull request #302357 from cemateia/update-understand-identifiers
Update understand identifiers
2 parents 4aa8a31 + 8e51992 commit e9f79b0

File tree

7 files changed

+243
-0
lines changed

7 files changed

+243
-0
lines changed

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,39 @@ MicrosoftTeamsAppIdentifier gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdenti
9898

9999
[MicrosoftTeamsAppIdentifier](https://azure.github.io/azure-sdk-for-android/azure-communication-common/com/azure/android/communication/common/MicrosoftTeamsAppIdentifier.html)
100100

101+
### Teams Extension user
102+
103+
The `TeamsExtensionUserIdentifier` interface represents a Teams user enabled for Teams Phone Extensibility. A `TeamsExtensionUserIdentifier` requires the Microsoft Entra user object ID of the Teams user, the Microsoft Entra tenant ID where the user resides and the Azure Communication Services resource ID. You can retrieve the Microsoft Entra user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response and the Microsoft Entra tenant ID via the [Microsoft Graph REST API /organization](/graph/api/organization-get) endpoint from the `id` property in the response. For more information about working with Microsoft Graph, see [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).
104+
Alternatively, you can find the object ID as the `oid` claim and the tenant ID as the `tid` claim in an [Microsoft Entra token](/entra/identity-platform/id-token-claims-reference#payload-claims) or [Microsoft Entra access token](/entra/identity-platform/access-token-claims-reference#payload-claims) after your user signed in and acquired a token.
105+
106+
#### Basic usage
107+
108+
```java
109+
// get the Teams user's ID from Graph APIs if only the email is known
110+
User user = graphClient.users("[email protected]")
111+
.buildRequest()
112+
.get();
113+
114+
// get the tenantId from Graph API
115+
OrganizationCollectionPage organizations = graphClient.organization()
116+
.buildRequest()
117+
.get();
118+
String tenantId = organizations.getCurrentPage().get(0).id;
119+
120+
// Communication Services Resource ID
121+
var resourceId = "<resource-id-guid>";
122+
123+
// create an identifier
124+
var teamsExtensionUser = new TeamsExtensionUserIdentifier(user.id, tenantId, resourceId);
125+
126+
// if you're not operating in the public cloud, you must also set the right Cloud type.
127+
var gcchTeamsExtensionUser = new TeamsExtensionUserIdentifier(user.id, tenantId, resourceId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);
128+
```
129+
130+
#### API reference
131+
132+
[TeamsExtensionUserIdentifier](https://azure.github.io/azure-sdk-for-android/azure-communication-common/com/azure/android/communication/common/TeamsExtensionUserIdentifier.html)
133+
101134
### Unknown
102135

103136
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 is recently introduced. Any unknown identifier from the service deserializes to `UnknownIdentifier` in the SDK.

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,34 @@ let gcchTeamsAppIdentifier = MicrosoftTeamsAppIdentifier(appId: botId, cloudEnvi
8888

8989
[MicrosoftTeamsAppIdentifier](https://azure.github.io/azure-sdk-for-ios/AzureCommunicationCommon/Classes/MicrosoftTeamsAppIdentifier.html)
9090

91+
### Teams Extension user
92+
93+
The `TeamsExtensionUserIdentifier` interface represents a Teams user enabled for Teams Phone Extensibility. A `TeamsExtensionUserIdentifier` requires the Microsoft Entra user object ID of the Teams user, the Microsoft Entra tenant ID where the user resides and the Azure Communication Services resource ID. You can retrieve the Microsoft Entra user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response and the Microsoft Entra tenant ID via the [Microsoft Graph REST API /organization](/graph/api/organization-get) endpoint from the `id` property in the response. For more information about working with Microsoft Graph, see [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).
94+
Alternatively, you can find the object ID as the `oid` claim and the tenant ID as the `tid` claim in an [Microsoft Entra token](/entra/identity-platform/id-token-claims-reference#payload-claims) or [Microsoft Entra access token](/entra/identity-platform/access-token-claims-reference#payload-claims) after your user signed in and acquired a token.
95+
96+
#### Basic usage
97+
98+
```swift
99+
// get the Teams user's ID if only the email is known, assuming a helper method for the Graph API
100+
let userId = await getUserIdFromGraph("[email protected]")
101+
102+
// get the tenantId from Graph API
103+
let tenantId = await getTenantIdFromGraph()
104+
105+
// Communication Services Resource ID
106+
let resourceId = "<resource-id-guid>"
107+
108+
// create an identifier
109+
let teamsExtensionUser = TeamsExtensionUserIdentifier(userId: userId, tenantId: tenantId, resourceId: resourceId)
110+
111+
// if you're not operating in the public cloud, you must also pass the right Cloud type.
112+
let gcchTeamsExtensionUser = TeamsExtensionUserIdentifier(userId: userId, tenantId: tenantId, resourceId: resourceId, cloudEnvironment: CommunicationCloudEnvironment.Gcch)
113+
```
114+
115+
#### API reference
116+
117+
[TeamsExtensionUserIdentifier](https://azure.github.io/azure-sdk-for-ios/AzureCommunicationCommon/Classes/TeamsExtensionUserIdentifier.html)
118+
91119
### Unknown
92120

93121
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 is recently introduced. Any unknown identifier from the service deserializes to `UnknownIdentifier` in the SDK.

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,39 @@ var gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id, Communicati
9999

100100
[MicrosoftTeamsAppIdentifier](/java/api/com.azure.communication.common.microsoftteamsappidentifier)
101101

102+
### Teams Extension user
103+
104+
The `TeamsExtensionUserIdentifier` interface represents a Teams user enabled for Teams Phone Extensibility. A `TeamsExtensionUserIdentifier` requires the Microsoft Entra user object ID of the Teams user, the Microsoft Entra tenant ID where the user resides and the Azure Communication Services resource ID. You can retrieve the Microsoft Entra user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response and the Microsoft Entra tenant ID via the [Microsoft Graph REST API /organization](/graph/api/organization-get) endpoint from the `id` property in the response. For more information about working with Microsoft Graph, see [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).
105+
Alternatively, you can find the object ID as the `oid` claim and the tenant ID as the `tid` claim in an [Microsoft Entra token](/entra/identity-platform/id-token-claims-reference#payload-claims) or [Microsoft Entra access token](/entra/identity-platform/access-token-claims-reference#payload-claims) after your user signed in and acquired a token.
106+
107+
#### Basic usage
108+
109+
```java
110+
// get the Teams user's ID from Graph APIs if only the email is known
111+
var user = graphClient.users("[email protected]")
112+
.buildRequest()
113+
.get();
114+
115+
// get the tenantId from Graph API
116+
OrganizationCollectionPage organizations = graphClient.organization()
117+
.buildRequest()
118+
.get();
119+
String tenantId = organizations.getCurrentPage().get(0).id;
120+
121+
// Communication Services Resource ID
122+
var resourceId = "<resource-id-guid>";
123+
124+
// create an identifier
125+
var teamsExtensionUser = new TeamsExtensionUserIdentifier(user.id, tenantId, resourceId);
126+
127+
// if you're not operating in the public cloud, you must also set the right Cloud type.
128+
var gcchTeamsExtensionUser = new TeamsExtensionUserIdentifier(user.id, tenantId, resourceId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);
129+
```
130+
131+
#### API reference
132+
133+
[TeamsExtensionUserIdentifier](/java/api/com.azure.communication.common.teamsextensionuseridentifier)
134+
102135
### Unknown
103136

104137
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 is recently introduced. Any unknown identifier from the service deserializes to `UnknownIdentifier` in the SDK.

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,35 @@ const gcchTeamsAppIdentifier = { teamsAppId: id, cloud: "gcch" };
9494

9595
[MicrosoftTeamsAppIdentifier](/javascript/api/@azure/communication-common/microsoftteamsappidentifier)
9696

97+
### Teams Extension user
98+
99+
The `TeamsExtensionUserIdentifier` interface represents a Teams user enabled for Teams Phone Extensibility. A `TeamsExtensionUserIdentifier` requires the Microsoft Entra user object ID of the Teams user, the Microsoft Entra tenant ID where the user resides and the Azure Communication Services resource ID. You can retrieve the Microsoft Entra user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response and the Microsoft Entra tenant ID via the [Microsoft Graph REST API /organization](/graph/api/organization-get) endpoint from the `id` property in the response. For more information about working with Microsoft Graph, see [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).
100+
Alternatively, you can find the object ID as the `oid` claim and the tenant ID as the `tid` claim in an [Microsoft Entra token](/entra/identity-platform/id-token-claims-reference#payload-claims) or [Microsoft Entra access token](/entra/identity-platform/access-token-claims-reference#payload-claims) after your user signed in and acquired a token.
101+
102+
#### Basic usage
103+
104+
```javascript
105+
// get the Teams user's ID from Graph APIs if only the email is known
106+
const user = await graphClient.api("/users/[email protected]").get();
107+
108+
// Get the tenantId from Graph API
109+
const org = await graphClient.api("/organization").get();
110+
const tenantId = org.value[0].id;
111+
112+
//Communication Services Resource ID
113+
const resourceId = "<resource-id-guid>";
114+
115+
// create an identifier
116+
const teamsExtensionUser = { userId: user.id, tenantId: tenantId, resourceId: resourceId };
117+
118+
// if you're not operating in the public cloud, you must also pass the right Cloud type.
119+
const gcchTeamsExtensionUser = { userId: user.id, tenantId: tenantId, resourceId: resourceId, cloud: "gcch" };
120+
```
121+
122+
#### API reference
123+
124+
[TeamsExtensionUserIdentifier](/javascript/api/@azure/communication-common/teamsextensionuseridentifier)
125+
97126
### Unknown
98127

99128
The `UnknownIdentifier` interface exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type is recently introduced. Any unknown identifier from the service deserializes to `UnknownIdentifier` in the SDK.

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,40 @@ var gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.Id, Communicati
9999

100100
[MicrosoftTeamsAppIdentifier](/dotnet/api/azure.communication.microsoftteamsappidentifier)
101101

102+
### Teams Extension user
103+
104+
The `TeamsExtensionUserIdentifier` interface represents a Teams user enabled for Teams Phone Extensibility. A `TeamsExtensionUserIdentifier` requires the Microsoft Entra user object ID of the Teams user, the Microsoft Entra tenant ID where the user resides and the Azure Communication Services resource ID. You can retrieve the Microsoft Entra user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response and the Microsoft Entra tenant ID via the [Microsoft Graph REST API /organization](/graph/api/organization-get) endpoint from the `id` property in the response. For more information about working with Microsoft Graph, see [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).
105+
Alternatively, you can find the object ID as the `oid` claim and the tenant ID as the `tid` claim in an [Microsoft Entra token](/entra/identity-platform/id-token-claims-reference#payload-claims) or [Microsoft Entra access token](/entra/identity-platform/access-token-claims-reference#payload-claims) after your user signed in and acquired a token.
106+
107+
#### Basic usage
108+
109+
```csharp
110+
// get the Teams user's ID from Graph APIs if only the email is known
111+
var user = await graphClient.Users["[email protected]"]
112+
.Request()
113+
.GetAsync();
114+
115+
// Get the tenantId from Graph API
116+
var organization = await graphClient.Organization
117+
.Request()
118+
.GetAsync();
119+
120+
string tenantId = organization.CurrentPage.FirstOrDefault()?.Id;
121+
122+
//Communication Services Resource ID
123+
var resourceId = "<resource-id-guid>";
124+
125+
// create an identifier
126+
var teamsExtensionUser = new TeamsExtensionUserIdentifier(user.Id, tenantId, resourceId);
127+
128+
// if you're not operating in the public cloud, you must also pass the right Cloud type.
129+
var gcchTeamsExtensionUser = new TeamsExtensionUserIdentifier(userId: user.Id, tenantId: tenantId, resourceId: resourceId, cloud: CommunicationCloudEnvironment.Gcch);
130+
```
131+
132+
#### API reference
133+
134+
[TeamsExtensionUserIdentifier](/dotnet/api/azure.communication.teamsextensionuseridentifier)
135+
102136
### Unknown
103137

104138
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 is recently introduced. Any unknown identifier from the service deserializes to `UnknownIdentifier` in the SDK.

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,35 @@ gcch_teams_app_identifier = MicrosoftTeamsAppIdentifier(
9696

9797
[MicrosoftTeamsAppIdentifier](/python/api/azure-communication-identity/azure.communication.identity.microsoftteamsappidentifier)
9898

99+
### Teams Extension user
100+
101+
The `TeamsExtensionUserIdentifier` interface represents a Teams user enabled for Teams Phone Extensibility. A `TeamsExtensionUserIdentifier` requires the Microsoft Entra user object ID of the Teams user, the Microsoft Entra tenant ID where the user resides and the Azure Communication Services resource ID. You can retrieve the Microsoft Entra user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response and the Microsoft Entra tenant ID via the [Microsoft Graph REST API /organization](/graph/api/organization-get) endpoint from the `id` property in the response. For more information about working with Microsoft Graph, see [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).
102+
Alternatively, you can find the object ID as the `oid` claim and the tenant ID as the `tid` claim in an [Microsoft Entra token](/entra/identity-platform/id-token-claims-reference#payload-claims) or [Microsoft Entra access token](/entra/identity-platform/access-token-claims-reference#payload-claims) after your user signed in and acquired a token.
103+
104+
105+
#### Basic usage
106+
107+
```python
108+
# get the Teams user's ID from Graph APIs if only the email is known
109+
user_id = graph_client.get("/users/[email protected]").json().get("id");
110+
111+
# get the tenantId from Graph API
112+
tenant_id = graph_client.get("/organization").json()["value"][0]["id"]
113+
114+
# Communication Services Resource ID
115+
resourceId = "<resource-id-guid>"
116+
117+
# create an identifier
118+
teams_user = TeamsExtensionUserIdentifier(user_id, tenant_id, resource_id)
119+
120+
# if you're not operating in the public cloud, you must also pass the right Cloud type
121+
gcch_teams_user = TeamsExtensionUserIdentifier(user_id, tenant_id, resource_id, cloud=CommunicationCloudEnvironment.GCCH)
122+
```
123+
124+
#### API reference
125+
126+
[TeamsExtensionUserIdentifier](/python/api/azure-communication-chat/azure.communication.chat.teamsextensionuseridentifier)
127+
99128
### Unknown
100129

101130
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 is recently introduced. Any unknown identifier from the service deserializes to the `UnknownIdentifier` in the SDK.

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,63 @@ The `MicrosoftTeamsAppIdentifierModel` represents a bot of the Teams Voice appli
171171

172172
[MicrosoftTeamsAppIdentifierModel](https://github.com/Azure/azure-rest-api-specs/blob/ea28180c6ce9027df36568307f235868d581144c/specification/communication/data-plane/Common/stable/2023-11-15/common.json#L165C6-L165C38)
173173

174+
### Teams Extension user
175+
176+
The `TeamsExtensionUserIdentifier` interface represents a Teams user enabled for Teams Phone Extensibility. A `TeamsExtensionUserIdentifier` requires the Microsoft Entra user object ID of the Teams user, the Microsoft Entra tenant ID where the user resides and the Azure Communication Services resource ID. You can retrieve the Microsoft Entra user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response and the Microsoft Entra tenant ID via the [Microsoft Graph REST API /organization](/graph/api/organization-get) endpoint from the `id` property in the response. For more information about working with Microsoft Graph, see [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).
177+
Alternatively, you can find the object ID as the `oid` claim and the tenant ID as the `tid` claim in an [Microsoft Entra token](/entra/identity-platform/id-token-claims-reference#payload-claims) or [Microsoft Entra access token](/entra/identity-platform/access-token-claims-reference#payload-claims) after your user signed in and acquired a token.
178+
179+
#### Basic usage
180+
181+
```json
182+
// request
183+
{
184+
"teamsExtensionUser": {
185+
"userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
186+
"tenantId": "d4f5a8c3-2c49-4b9e-a5c6-3c85e80a7f4d",
187+
"resourceId": "f7e1e3c6-3a1d-4415-8b7d-9e1d4bda2d45"
188+
}
189+
}
190+
191+
// response
192+
{
193+
"kind": "teamsExtensionUser",
194+
"rawId": "8:acs:f7e1e3c6-3a1d-4415-8b7d-9e1d4bda2d45_d4f5a8c3-2c49-4b9e-a5c6-3c85e80a7f4d_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
195+
"teamsExtensionUser": {
196+
"userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
197+
"tenantId": "d4f5a8c3-2c49-4b9e-a5c6-3c85e80a7f4d",
198+
"resourceId": "f7e1e3c6-3a1d-4415-8b7d-9e1d4bda2d45"
199+
}
200+
}
201+
202+
203+
// if you're not operating in the public cloud, you must also pass the right Cloud type in a request
204+
{
205+
"microsoftTeamsUser": {
206+
"userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
207+
"tenantId": "d4f5a8c3-2c49-4b9e-a5c6-3c85e80a7f4d",
208+
"resourceId": "f7e1e3c6-3a1d-4415-8b7d-9e1d4bda2d45",
209+
"cloud": "gcch"
210+
}
211+
}
212+
213+
// response
214+
{
215+
"kind": "teamsExtensionUser",
216+
"rawId": "8:gcch-acs:f7e1e3c6-3a1d-4415-8b7d-9e1d4bda2d45_d4f5a8c3-2c49-4b9e-a5c6-3c85e80a7f4d_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
217+
"teamsExtensionUser": {
218+
"userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
219+
"tenantId": "d4f5a8c3-2c49-4b9e-a5c6-3c85e80a7f4d",
220+
"resourceId": "f7e1e3c6-3a1d-4415-8b7d-9e1d4bda2d45",
221+
"cloud": "gcch"
222+
}
223+
}
224+
```
225+
226+
#### API reference
227+
228+
[TeamsExtensionUserIdentifierModel](https://github.com/Azure/azure-rest-api-specs/blob/79436d1724498ebd679471e4fd9356ae8f8d689e/specification/communication/data-plane/Common/stable/2025-06-30/common.json#L195)
229+
230+
174231
### Unknown
175232

176233
If a new identifier is introduced in a service, it downgrades to the `CommunicationIdentifierModel` if you are on an old API version.

0 commit comments

Comments
 (0)