Update docs metadata
This commit is contained in:
azure-sdk
Родитель
cc1231ed26
Коммит
f8f662f33f
|
|
@ -1,209 +1,19 @@
|
|||
---
|
||||
title: Azure Communication Network Traversal Package client library for Java
|
||||
keywords: Azure, java, SDK, API, azure-communication-networktraversal, communication
|
||||
ms.date: 02/11/2022
|
||||
ms.date: 04/17/2024
|
||||
ms.topic: reference
|
||||
ms.devlang: java
|
||||
ms.service: communication
|
||||
ms.technology: azure
|
||||
ms.prod: azure
|
||||
---
|
||||
# Azure Communication Network Traversal Package client library for Java - version 1.0.0
|
||||
# Azure Communication Network Traversal Package client library for Java - version 1.1.0
|
||||
|
||||
|
||||
Azure Communication Network Traversal is managing TURN credentials for Azure Communication Services.
|
||||
|
||||
It will provide TURN credentials to a user.
|
||||
|
||||
[Source code](https://github.com/Azure/azure-sdk-for-java/blob/azure-communication-networktraversal_1.0.0/sdk/communication) | [API reference documentation](https://github.com/Azure/azure-sdk-for-java/blob/azure-communication-networktraversal_1.0.0/sdk/communication)
|
||||
This service was shut down on 03/31/2024 and there is no replacement, please read our [retirement notice](https://azure.microsoft.com/updates/retirement-notice-azure-communication-services-network-traversal-turn-public-preview-is-retiring/) for more details.
|
||||
|
||||
## Getting started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- An Azure subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
|
||||
- [Java Development Kit (JDK)](https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable) version 8 or above.
|
||||
- [Apache Maven](https://maven.apache.org/download.cgi).
|
||||
- A Communication Services resource. You can use the [Azure Portal](https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up.
|
||||
|
||||
### Include the package
|
||||
|
||||
[//]: # ({x-version-update-start;com.azure:azure-communication-networktraversal;current})
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.azure</groupId>
|
||||
<artifactId>azure-communication-networktraversal</artifactId>
|
||||
<version>1.0.0-beta.3</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## Authenticate the client
|
||||
|
||||
There are two forms of authentication to use the Relay SDK:
|
||||
|
||||
### Azure Active Directory Token Authentication
|
||||
A `DefaultAzureCredential` object can be passed to the `CommunicationRelayClientBuilder` via the credential() function. Endpoint must also be set via the endpoint() function.
|
||||
|
||||
`AZURE_CLIENT_SECRET`, `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` environment variables
|
||||
are needed to create a DefaultAzureCredential object.
|
||||
|
||||
```java readme-sample-createCommunicationRelayClientWithAAD
|
||||
// You can find your endpoint and access key from your resource in the Azure Portal
|
||||
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
|
||||
|
||||
CommunicationRelayClient communicationRelayClient = new CommunicationRelayClientBuilder()
|
||||
.endpoint(endpoint)
|
||||
.credential(new DefaultAzureCredentialBuilder().build())
|
||||
.buildClient();
|
||||
```
|
||||
|
||||
### AzureKeyCredential Authentication
|
||||
Network Traversal uses HMAC authentication with the resource access key.
|
||||
The access key can be used to create an AzureKeyCredential and provided to the `CommunicationRelayClientBuilder` via the credential() function. Endpoint must also be set via the endpoint() function.
|
||||
|
||||
```java readme-sample-createCommunicationNetworkTraversalClient
|
||||
// You can find your endpoint and access key from your resource in the Azure Portal
|
||||
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
|
||||
AzureKeyCredential keyCredential = new AzureKeyCredential("<access-key>");
|
||||
|
||||
CommunicationRelayClient communicationRelayClient = new CommunicationRelayClientBuilder()
|
||||
.endpoint(endpoint)
|
||||
.credential(keyCredential)
|
||||
.buildClient();
|
||||
```
|
||||
|
||||
```java readme-sample-createCommunicationNetworkTraversalAsyncClient
|
||||
// You can find your endpoint and access key from your resource in the Azure Portal
|
||||
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
|
||||
AzureKeyCredential keyCredential = new AzureKeyCredential("<access-key>");
|
||||
|
||||
CommunicationRelayAsyncClient communicationRelayClient = new CommunicationRelayClientBuilder()
|
||||
.endpoint(endpoint)
|
||||
.credential(keyCredential)
|
||||
.buildAsyncClient();
|
||||
```
|
||||
|
||||
### Connection String Authentication
|
||||
Alternatively, you can provide the entire connection string using the connectionString() function instead of providing the endpoint and access key.
|
||||
|
||||
```java readme-sample-createCommunicationRelayClientWithConnectionString
|
||||
// You can find your connection string from your resource in the Azure Portal
|
||||
String connectionString = "<connection_string>";
|
||||
|
||||
CommunicationRelayClient communicationRelayClient = new CommunicationRelayClientBuilder()
|
||||
.connectionString(connectionString)
|
||||
.buildClient();
|
||||
```
|
||||
|
||||
## Key concepts
|
||||
|
||||
`CommunicationRelayClient` and `CommunicationRelayAsyncClient` provide the functionalities to manage users and user tokens.
|
||||
|
||||
## Examples
|
||||
|
||||
### Getting a new Relay Configuration
|
||||
|
||||
```java readme-sample-getRelayConfigurationWithoutIdentity
|
||||
CommunicationRelayClient communicationRelayClient = createCommunicationNetworkTraversalClient();
|
||||
CommunicationRelayConfiguration config = communicationRelayClient.getRelayConfiguration();
|
||||
|
||||
System.out.println("Expires on:" + config.getExpiresOn());
|
||||
List<CommunicationIceServer> iceServers = config.getIceServers();
|
||||
|
||||
for (CommunicationIceServer iceS : iceServers) {
|
||||
System.out.println("URLS: " + iceS.getUrls());
|
||||
System.out.println("Username: " + iceS.getUsername());
|
||||
System.out.println("Credential: " + iceS.getCredential());
|
||||
System.out.println("RouteType: " + iceS.getRouteType());
|
||||
}
|
||||
```
|
||||
|
||||
### Getting a new Relay Configuration providing a user
|
||||
|
||||
Use the `createUser` function to create a new user from CommunicationIdentityClient
|
||||
Use the `getRelayConfiguration` function to get a Relay Configuration
|
||||
|
||||
```java readme-sample-getRelayConfiguration
|
||||
CommunicationIdentityClient communicationIdentityClient = createCommunicationIdentityClient();
|
||||
|
||||
CommunicationUserIdentifier user = communicationIdentityClient.createUser();
|
||||
System.out.println("User id: " + user.getId());
|
||||
|
||||
GetRelayConfigurationOptions options = new GetRelayConfigurationOptions();
|
||||
options.setCommunicationUserIdentifier(user);
|
||||
|
||||
CommunicationRelayClient communicationRelayClient = createCommunicationNetworkTraversalClient();
|
||||
CommunicationRelayConfiguration config = communicationRelayClient.getRelayConfiguration(options);
|
||||
|
||||
System.out.println("Expires on:" + config.getExpiresOn());
|
||||
List<CommunicationIceServer> iceServers = config.getIceServers();
|
||||
|
||||
for (CommunicationIceServer iceS : iceServers) {
|
||||
System.out.println("URLS: " + iceS.getUrls());
|
||||
System.out.println("Username: " + iceS.getUsername());
|
||||
System.out.println("Credential: " + iceS.getCredential());
|
||||
System.out.println("RouteType: " + iceS.getRouteType());
|
||||
}
|
||||
```
|
||||
|
||||
### Getting a new Relay Configuration providing a Route Type
|
||||
|
||||
```java readme-sample-getRelayConfigurationWithRouteType
|
||||
|
||||
GetRelayConfigurationOptions options = new GetRelayConfigurationOptions();
|
||||
options.setRouteType(RouteType.ANY);
|
||||
|
||||
CommunicationRelayClient communicationRelayClient = createCommunicationNetworkTraversalClient();
|
||||
CommunicationRelayConfiguration config = communicationRelayClient.getRelayConfiguration(options);
|
||||
|
||||
System.out.println("Expires on:" + config.getExpiresOn());
|
||||
List<CommunicationIceServer> iceServers = config.getIceServers();
|
||||
|
||||
for (CommunicationIceServer iceS : iceServers) {
|
||||
System.out.println("URLS: " + iceS.getUrls());
|
||||
System.out.println("Username: " + iceS.getUsername());
|
||||
System.out.println("Credential: " + iceS.getCredential());
|
||||
System.out.println("RouteType: " + iceS.getRouteType());
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
All user token service operations will throw an exception on failure.
|
||||
|
||||
```java readme-sample-createUserTroubleshooting
|
||||
try {
|
||||
CommunicationUserIdentifier user = communicationIdentityClient.createUser();
|
||||
GetRelayConfigurationOptions options = new GetRelayConfigurationOptions();
|
||||
options.setCommunicationUserIdentifier(user);
|
||||
|
||||
CommunicationRelayClient communicationRelayClient = createCommunicationNetworkTraversalClient();
|
||||
CommunicationRelayConfiguration config = communicationRelayClient.getRelayConfiguration(options);
|
||||
} catch (RuntimeException ex) {
|
||||
System.out.println(ex.getMessage());
|
||||
}
|
||||
```
|
||||
Refer to the official documentation for more details and error codes (to be added).
|
||||
|
||||
## Next steps
|
||||
|
||||
Please take a look at the [samples][samples] directory for detailed examples of how to use this library to manage relay configuration
|
||||
|
||||
## Contributing
|
||||
|
||||
This project welcomes contributions and suggestions. Most contributions require you to agree to a [Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights to use your contribution.
|
||||
|
||||
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our 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 -->
|
||||
[cla]: https://cla.microsoft.com
|
||||
[coc]: https://opensource.microsoft.com/codeofconduct/
|
||||
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
|
||||
[coc_contact]: mailto:opencode@microsoft.com
|
||||
[product_docs]: https://docs.microsoft.com/azure/communication-services/
|
||||
[api_documentation]: https://aka.ms/java-docs
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,18 @@
|
|||
{
|
||||
"Name": "azure-communication-networktraversal",
|
||||
"Version": "1.1.0",
|
||||
"DevVersion": null,
|
||||
"DirectoryPath": "sdk/communication/azure-communication-networktraversal",
|
||||
"ServiceDirectory": "communication",
|
||||
"ReadMePath": "sdk/communication/azure-communication-networktraversal/README.md",
|
||||
"ChangeLogPath": "sdk/communication/azure-communication-networktraversal/CHANGELOG.md",
|
||||
"Group": "com.azure",
|
||||
"SdkType": "client",
|
||||
"IsNewSdk": true,
|
||||
"ArtifactName": "azure-communication-networktraversal",
|
||||
"ReleaseStatus": "2024-04-11",
|
||||
"Namespaces": [
|
||||
"com.azure.communication.networktraversal",
|
||||
"com.azure.communication.networktraversal.models"
|
||||
]
|
||||
}
|
||||
Загрузка…
Ссылка в новой задаче