Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Communication] - Sample - Updating the Samples and regenerate the readme #17822

Merged
merged 3 commits into from
Jan 7, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 22 additions & 5 deletions sdk/communication/Azure.Communication.Administration/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Azure Communication Administration client library for .NET

> Server Version:
Identity client: 2020-07-20-preview2
> Identity client: 2020-07-20-preview2

> Phone number administration client: 2020-07-20-preview1

@@ -12,13 +12,15 @@ Azure Communication Administration is managing tokens and phone numbers for Azur
## Getting started

### Install the package

Install the Azure Communication Administration client library for .NET with [NuGet][nuget]:

```Powershell
dotnet add package Azure.Communication.Administration --version 1.0.0-beta.3
```

### Prerequisites

You need an [Azure subscription][azure_sub] and a [Communication Service Resource][communication_resource_docs] to use this package.

To create a new Communication Service, you can use the [Azure Portal][communication_resource_create_portal] or the [.NET management client library][communication_resource_create_net].
@@ -41,19 +43,30 @@ var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);
```

Clients also have the option to authenticate using a valid token.

```C# Snippet:CreateCommunicationIdentityFromToken
var endpoint = "<endpoint_url>";
TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);
```

### Key concepts

`CommunicationIdentityClient` provides the functionalities to manage user access tokens: creating new ones, renewing and revoking them.

## Examples

### Create a new identity

```C# Snippet:CreateCommunicationUserAsync
Response<CommunicationUserIdentifier> userResponse = await client.CreateUserAsync();
CommunicationUserIdentifier user = userResponse.Value;
Console.WriteLine($"User id: {user.Id}");
```

### Issuing or Refreshing a token for an existing identity

```C# Snippet:CreateCommunicationTokenAsync
Response<CommunicationUserToken> tokenResponse = await client.IssueTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat });
string token = tokenResponse.Value.Token;
@@ -63,19 +76,23 @@ Console.WriteLine($"Expires On: {expiresOn}");
```

### Revoking a user's tokens

In case a user's tokens are compromised or need to be revoked:

```C# Snippet:RevokeCommunicationUserToken
Response revokeResponse = client.RevokeTokens(
user,
issuedBefore: DateTimeOffset.UtcNow.AddDays(-1) /* optional */);
```

### Deleting a user

```C# Snippet:DeleteACommunicationUser
Response deleteResponse = client.DeleteUser(user);
```

## Troubleshooting

All User token service operations will throw a RequestFailedException on failure.

```C# Snippet:CommunicationIdentityClient_Troubleshooting
@@ -93,8 +110,6 @@ catch (RequestFailedException ex)
}
```



### Phone plans overview

Phone plans come in two types; Geographic and Toll-Free. Geographic phone plans are phone plans associated with a location, whose phone numbers' area codes are associated with the area code of a geographic location. Toll-Free phone plans are phone plans not associated location. For example, in the US, toll-free numbers can come with area codes such as 800 or 888.
@@ -174,7 +189,6 @@ foreach(var locationOption in locationOprions.Options)

Fetching area codes for geographic phone plans will require the the location options queries set. You must include the chain of geographic locations traversing down the location options object returned by the GetLocationOptions API.


```C#
var areaCodesResponse = client.GetAllAreaCodes(locationType, countryCode, planId, locationOptionsQueries);
var areaCodes = areaCodesResponse.Value;
@@ -225,14 +239,17 @@ Console.WriteLine($"ReleaseId: {releasePhoneNumberOperation.Value.ReleaseId}, St
```

## Next steps

[Read more about Communication user access tokens][user_access_token]

## Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].

This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.

<!-- LINKS -->

[azure_sub]: https://azure.microsoft.com/free/
[azure_portal]: https://portal.azure.com
[source]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.Administration/src
@@ -246,5 +263,5 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
[nuget]: https://www.nuget.org/
[user_access_token]: https://docs.microsoft.com/azure/communication-services/quickstarts/access-tokens?pivots=programming-language-csharp
[communication_resource_docs]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp
[communication_resource_create_portal]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp
[communication_resource_create_portal]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp
[communication_resource_create_net]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-net
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# Obtain user tokens from Azure Communication Services
This sample demonstrates how to obtain user tokens from Azure Communication Services. You can use this token to authenticate your users to use Azure Communication Services offerings.

This sample demonstrates how to obtain user tokens from Azure Communication Services. You can use this token to authenticate your users to use Azure Communication Services offerings.

To get started you'll need an Azure Communication Services resource. See the README for prerequisites and instructions.

<!-- UPDATE ReadMe link -->

## Create a `CommunicationIdentityClient`

To create a new `CommunicationIdentityClient` you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you have created the resource.
To create a new `CommunicationIdentityClient` you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you have created the resource.

You can set `connectionString` based on an environment variable, a configuration setting, or any way that works for your application.

@@ -16,7 +18,16 @@ var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);
```

Clients also have the option to authenticate using a valid token.

```C# Snippet:CreateCommunicationIdentityFromToken
var endpoint = "<endpoint_url>";
TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);
```

## Create a user

The `CommunicationIdentityClient` can be used to create users and issue tokens.

```C# Snippet:CreateCommunicationUser
@@ -34,7 +45,8 @@ You will need to store the `identity` that is returned by Azure Communication Se
In the example code snippet below, it is assumed that the token is generated for a user on your application. During token generation you should also pass list of scopes to Azure Communication Services,
so the token generated by Azure Communication Services is authorized only to do things determined by `scopes`. <!-- You can see the full list of scopes [here][scopes]. -->

Every token generated has an expiry date stamped on it. Once the token is expired, you can renew the token by calling the same method.
Every token generated has an expiry date stamped on it. Once the token is expired, you can renew the token by calling the same method.

```C# Snippet:CreateCommunicationToken
Response<CommunicationUserToken> tokenResponse = client.IssueToken(user, scopes: new[] { CommunicationTokenScope.Chat });
string token = tokenResponse.Value.Token;
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# Obtain user tokens from Azure Communication Services
This sample demonstrates how to obtain user tokens from Azure Communication Services. You can use this token to authenticate your users to use Azure Communication Services offerings.

This sample demonstrates how to obtain user tokens from Azure Communication Services. You can use this token to authenticate your users to use Azure Communication Services offerings.

To get started you'll need an Azure Communication Services resource. See the README for prerequisites and instructions.

<!-- TODO: Update ReadMe -->

## Create a `CommunicationIdentityClient`

To create a new `CommunicationIdentityClient` you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you have created the resource.
To create a new `CommunicationIdentityClient` you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you have created the resource.

You can set `connectionString` based on an environment variable, a configuration setting, or any way that works for your application.

@@ -16,7 +18,16 @@ var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);
```

Clients also have the option to authenticate using a valid token.

```C# Snippet:CreateCommunicationIdentityFromToken
var endpoint = "<endpoint_url>";
TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);
```

## Create a user

The `CommunicationIdentityClient` can be used to create users and issue tokens.

```C# Snippet:CreateCommunicationUserAsync
@@ -33,9 +44,11 @@ You will need to store the `identity` that is returned by Azure Communication Se

In the example code snippet below, it is assumed that the token is generated for a user on your application. During token generation you should also pass list of scopes to Azure Communication Services,
so the token generated by Azure Communication Services is authorized only to do things determined by `scopes`.

<!-- You can see the full list of scopes TODO: [here](https://github.com/mikben/azure-docs-pr/blob/release-project-spool/articles/project-spool/concepts/identity-model.md).-->

Every token generated has an expiry date stamped on it. Once the token is expired, you can renew the token by calling the same method.
Every token generated has an expiry date stamped on it. Once the token is expired, you can renew the token by calling the same method.

```C# Snippet:CreateCommunicationTokenAsync
Response<CommunicationUserToken> tokenResponse = await client.IssueTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat });
string token = tokenResponse.Value.Token;

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
@@ -5,7 +5,9 @@
using System.Threading.Tasks;
using Azure.Communication.Administration.Models;
using Azure.Communication.Administration.Tests;
using Azure.Core;
using Azure.Core.TestFramework;
using Azure.Identity;
using NUnit.Framework;

#pragma warning disable IDE0059 // Unnecessary assignment of a value
@@ -17,7 +19,7 @@ namespace Azure.Communication.Administration.Samples
/// </summary>
public partial class Sample1_CommunicationIdentityClient : CommunicationIdentityClientLiveTestBase
{
public Sample1_CommunicationIdentityClient(bool isAsync): base(isAsync)
public Sample1_CommunicationIdentityClient(bool isAsync) : base(isAsync)
=> Matcher.IgnoredHeaders.Add("x-ms-content-sha256");

[Test]
@@ -97,6 +99,28 @@ public void UserAndTokenLifeCycle()
#endregion Snippet:DeleteACommunicationUser
}

[Test]
public async Task CreateIdentityWithToken()
{
var endpoint = TestEnvironment.EndpointString;
#region Snippet:CreateCommunicationIdentityFromToken
//@@var endpoint = "<endpoint_url>";
TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);
#endregion Snippet:CreateCommunicationIdentityFromToken

tokenCredential = (Mode == RecordedTestMode.Playback) ? new MockCredential() : new DefaultAzureCredential();
client = CreateInstrumentedCommunicationIdentityClientWithToken(tokenCredential);
try
{
Response<CommunicationUserIdentifier> userResponse = await client.CreateUserAsync();
}
catch (Exception ex)
{
Assert.Fail($"Unexpected error: {ex}");
}
}

[Test]
public async Task Troubleshooting()
{