Create Definition

  • Article

 

The Create Definition operation creates a new definition for a specified profile. This definition will be assigned a version number by the service. For more information about creating a profile, see Create Profile.

Request

The Create Definition request is specified as follows. Replace <subscription-id> with the subscription ID and <profile-name> with the profile name. For example myapp-trafficmanager-net.

Method

Request URI

POST

https://management.core.windows.net/<subscription-id>/services/WATM/profiles/<profile-name>/definitions

You must make sure that the request that is made to the management service is secure. For additional details, see Authenticating Service Management Requests.

URI Parameters

None.

Request Headers

The following table describes the request headers.

Request Header

Description

x-ms-version

Required. Specifies the version of the operation to use for this request. This header should be set to 2011-10-01 or higher. For more information about versioning headers, see Service Management Versioning.

Request Body

The format of the request body is as follows:

<Definition xmlns="https://schemas.microsoft.com/windowsazure">
  <DnsOptions>
    <TimeToLiveInSeconds>dns-time-to-live</TimeToLiveInSeconds>
  </DnsOptions>
  <Monitors>
    <Monitor>
      <IntervalInSeconds>interval-in-seconds</IntervalInSeconds>
      <TimeoutInSeconds>timeout-in-seconds</TimeoutInSeconds>
      <ToleratedNumberOfFailures>number-of-failures</ToleratedNumberOfFailures>
      <Protocol>monitor-protocol</Protocol>
      <Port>port-number</Port>
      <HttpOptions>
        <Verb>http-verb</Verb>
        <RelativePath>path-relative-to-endpoint</RelativePath>
        <ExpectedStatusCode>expected-status</ExpectedStatusCode>
      </HttpOptions>
    </Monitor>
  </Monitors>
  <Policy>
    <LoadBalancingMethod>load-balancing-method</LoadBalancingMethod>
    <Endpoints>
      <Endpoint>
        <DomainName>domain-name</DomainName>
        <Status>endpoint-status</Status>
        <Type>endpoint-type</Type>
        <Location>endpoint-location</Location>
        <MinChildEndpoints>min-child-endpoints</MinChildEndpoints>
        <Weight>load-balancing-priority</Weight>
      </Endpoint>
    </Endpoints>
  </Policy>
</Definition>

The following table describes the elements in the request body.

Parameter Name

Description

TimeToLiveInSeconds

Specifies the DNS Time-to-Live (TTL) that informs the Local DNS resolvers how long to cache DNS entries.

The value is an integer from 30 through 999,999.

IntervalInSeconds

Specifies the number of seconds between consecutive attempts to check the status of a monitoring endpoint. The value must be set to 30.

TimeoutInSeconds

Specifies the time to wait for response from the monitoring endpoint. The value must be set to 10.

ToleratedNumberOfFailures

Specifies the number of consecutive failures to probe an endpoint before taking the endpoint out of rotation. The value must be set to 3.

Protocol

Specifies the protocol to use to monitor endpoint health.

Possible values are:

  • HTTP

  • HTTPS

Port

Specifies the port used to monitor endpoint health. Accepted values are integer values greater than 0 and less or equal to 65,535.

Verb

Specifies the verb to use when making an HTTP request to monitor endpoint health. The value must be set to GET.

RelativePath

Specifies the path relative to the endpoint domain name to probe for health state. Restrictions are:

  • The path must be from 1 through 1000 characters.

  • It must start with a forward slash /.

  • It must contain no brackets <>.

  • It must contain no double slashes //.

  • It must be a well-formed URI string. For more information, see Uri.IsWellFormedUriString Method.

ExpectedStatusCode

Specifies the HTTP status code expected from a healthy endpoint. The endpoint is considered unhealthy otherwise. The value must be set to 200.

LoadBalancingMethod

Specifies the load balancing method to use to distribute connection.

Possible values are:

  • Performance

  • Failover

  • RoundRobin

Endpoints

Encapsulates the list of Azure Traffic Manager endpoints. You can define up to 100 endpoints in the list.

If the load balancing method is set to Failover, traffic to the endpoints is load balanced in the sequential order in which the endpoints are defined.

DomainName

Specifies the endpoint domain name. The value depends on endpoint type. If Type is CloudService, the value must be a fully qualified domain name (FQDN) of a cloud service that belongs to the subscription ID that owns the definition. If Type is AzureWebsite, the value must be an FQDN of an Azure web site that belongs to the subscription ID that owns the definition. If Type is Any, the value can be any FQDN for an Azure service or a service outside of Azure.

Status

Specifies the status of the monitoring endpoint. If set to Enabled, the endpoint is considered by the load balancing method and is monitored.

Possible values are:

  • Enabled

  • Disabled

Type

Optional. Specifies the type of endpoint being added to the definition.

Possible values are:

  • CloudService

  • AzureWebsite

  • Any

  • TrafficManager

If there is more than one AzureWebsite endpoint, they must be in different datacenters. This limitation doesn’t apply to cloud services. The default value is CloudService. Use the TrafficManager type when configuring nested profiles.

Location

Required when LoadBalancingMethod is set to Performance and Type is set to Any or TrafficManager. Specifies the name of the Azure region. The Location cannot be specified for endpoints of type CloudService or AzureWebsite, in which the locations are determined from the service. For more information, see List Locations.

MinChildEndpoints

Optional. Can be specified when Type is set to TrafficManager. The minimum number of healthy endpoints within a nested profile that determines whether any of the endpoints within that profile can receive traffic. Default value is 1.

Weight

Optional. Specifies the priority of the endpoint in load balancing. The higher the weight, the more frequently the endpoint will be made available to the load balancer. The value must be greater than 0. For endpoints that do not specify a weight value, a default weight of 1 will be used.

Response

The response includes an HTTP status code, a set of response headers, and a response body.

Status Code

A successful operation returns status code 200 (OK). For information about status codes, see Service Management Status and Error Codes.

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response Header

Description

x-ms-request-id

A value that uniquely identifies a request made against the management service.

Response Body

The format of the response body is as follows:

<Definition xmlns="https://schemas.microsoft.com/windowsazure">
  <Version>1</Version>
</Definition>

The following table describes the elements in the response body.

Element Name

Description

Version

The version number assigned to the new definition. This value is always 1.