Communication Network Traversal - Issue Relay Configuration

Reference

Service:: Communication

API Version:: 2022-03-01-preview

Issue a configuration for an STUN/TURN server.

POST {endpoint}/networkTraversal/:issueRelayConfiguration?api-version=2022-03-01-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	The communication resource, for example https://my-resource.communication.azure.com
api-version	query	True	string	Version of API to invoke.

Request Body

Name	Type	Description
id	string	An identity to be associated with telemetry for data relayed using the returned credentials. Must be an existing ACS user identity. If not provided, the telemetry will not contain an associated identity value.
routeType	RouteType	Filter the routing methodology returned. If not provided, will return all route types in separate ICE servers.
ttl	integer	The credential Time-To-Live (TTL), in seconds. The default value will be used if given value exceeds it.

Responses

Name	Type	Description
200 OK	CommunicationRelayConfiguration	Success
Other Status Codes	CommunicationErrorResponse	Error

Examples

Issue Relay Configuration

Sample Request

HTTP

POST https://my-resource.communication.azure.com/networkTraversal/:issueRelayConfiguration?api-version=2022-03-01-preview

{
  "id": "8:acs:2dee53b4-368b-45b4-ab52-8493fb117652_00000005-14a2-493b-8a72-5a3a0d000081",
  "ttl": 3600
}

Sample Response

Status code:: 200

{
  "expiresOn": "2022-03-01T21:39:39.3244584+00:00",
  "iceServers": [
    {
      "urls": [
        "turn:131.107.255.255:3478",
        "stun:131.107.255.255:3478"
      ],
      "username": "<USERNAME>",
      "credential": "<CREDENTIAL>",
      "routeType": "any"
    }
  ]
}

Definitions

Name	Description
CommunicationError	The Communication Services error.
CommunicationErrorResponse	The Communication Services error.
CommunicationIceServer	An instance of a STUN/TURN server with credentials to be used for ICE negotiation.
CommunicationRelayConfiguration	A relay configuration containing the STUN/TURN URLs and credentials.
CommunicationRelayConfigurationRequest	Request for a CommunicationRelayConfiguration.
RouteType	The routing methodology to where the ICE server will be located from the client. "any" will have higher reliability while "nearest" will have lower latency. It is recommended to default to use the "any" routing method unless there are specific scenarios which minimizing latency is critical.

CommunicationError

The Communication Services error.

Name	Type	Description
code	string	The error code.
details	CommunicationError[]	Further details about specific errors that led to this error.
innererror	CommunicationError	The inner error if any.
message	string	The error message.
target	string	The error target.

CommunicationErrorResponse

The Communication Services error.

Name	Type	Description
error	CommunicationError	The Communication Services error.

CommunicationIceServer

An instance of a STUN/TURN server with credentials to be used for ICE negotiation.

Name	Type	Description
credential	string	Credential for the server.
routeType	RouteType	The routing methodology to where the ICE server will be located from the client. "any" will have higher reliability while "nearest" will have lower latency. It is recommended to default to use the "any" routing method unless there are specific scenarios which minimizing latency is critical.
urls	string[]	List of STUN/TURN server URLs.
username	string	User account name which uniquely identifies the credentials.

CommunicationRelayConfiguration

A relay configuration containing the STUN/TURN URLs and credentials.

Name	Type	Description
expiresOn	string	The date for which the username and credentials are not longer valid. Will be 48 hours from request time.
iceServers	CommunicationIceServer[]	An array representing the credentials and the STUN/TURN server URLs for use in ICE negotiations.

CommunicationRelayConfigurationRequest

Request for a CommunicationRelayConfiguration.

Name	Type	Default Value	Description
id	string		An identity to be associated with telemetry for data relayed using the returned credentials. Must be an existing ACS user identity. If not provided, the telemetry will not contain an associated identity value.
routeType	RouteType		Filter the routing methodology returned. If not provided, will return all route types in separate ICE servers.
ttl	integer	172800	The credential Time-To-Live (TTL), in seconds. The default value will be used if given value exceeds it.

RouteType

The routing methodology to where the ICE server will be located from the client. "any" will have higher reliability while "nearest" will have lower latency. It is recommended to default to use the "any" routing method unless there are specific scenarios which minimizing latency is critical.

Name	Type	Description
any	string
nearest	string

Share via