Share via

Job Router Administration Operations - Upsert Distribution Policy

  • Reference
Service:
Communication
API Version:
2023-11-01

Creates or updates a distribution policy.

PATCH {endpoint}/routing/distributionPolicies/{distributionPolicyId}?api-version=2023-11-01

URI Parameters

Name In Required Type Description
distributionPolicyId
 path True

string

Id of a distribution policy.
endpoint
 path True

string

Uri of your Communication resource
api-version
 query True

string

minLength: 1

The API version to use for this operation.

Request Header

Media Types: "application/merge-patch+json"

Name Required Type Description
If-Match

string

The request should only proceed if an entity matches this string.
If-Unmodified-Since

string (date-time-rfc7231)

The request should only proceed if the entity was not modified after this time.

Request Body

Media Types: "application/merge-patch+json"

Name Type Description
mode DistributionModeCreateOrUpdate:

Mode governing the specific distribution method.
name

string

Friendly name of this policy.
offerExpiresAfterSeconds

number (double)

Number of seconds after which any offers created under this policy will be expired.

Responses

Name Type Description
200 OK

DistributionPolicy

The request has succeeded.

Headers

  • ETag: string
  • Last-Modified: string
201 Created

DistributionPolicy

The request has succeeded and a new resource has been created as a result.

Headers

  • ETag: string
  • Last-Modified: string
Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

AadOauth2Auth

The Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: accessCode
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize
Token URL: https://login.microsoftonline.com/common/oauth2/token

Scopes

Name Description
https://communication.azure.com/.default

Examples

Creates a Distribution policy
Updates a distribution policy

Creates a Distribution policy

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/distributionPolicies/d9033d56-659c-437a-b5b7-4f3b14301dd4?api-version=2023-11-01

{
  "mode": {
    "kind": "longestIdle",
    "minConcurrentOffers": 1,
    "maxConcurrentOffers": 5,
    "bypassSelectors": false
  },
  "offerExpiresAfterSeconds": 300,
  "name": "Main"
}

Sample response

Status code:
200 
{
  "id": "d9033d56-659c-437a-b5b7-4f3b14301dd4",
  "name": "Main",
  "offerExpiresAfterSeconds": 300,
  "mode": {
    "kind": "longestIdle",
    "minConcurrentOffers": 1,
    "maxConcurrentOffers": 5,
    "bypassSelectors": false
  },
  "etag": "etag"
}
Status code:
201 
{
  "id": "d9033d56-659c-437a-b5b7-4f3b14301dd4",
  "name": "Main",
  "offerExpiresAfterSeconds": 300,
  "mode": {
    "kind": "longestIdle",
    "minConcurrentOffers": 1,
    "maxConcurrentOffers": 5,
    "bypassSelectors": false
  },
  "etag": "etag"
}

Updates a distribution policy

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/distributionPolicies/d9033d56-659c-437a-b5b7-4f3b14301dd4?api-version=2023-11-01

{
  "mode": {
    "kind": "longestIdle",
    "minConcurrentOffers": 1,
    "maxConcurrentOffers": 5,
    "bypassSelectors": false
  },
  "offerExpiresAfterSeconds": 300,
  "name": "Main"
}

Sample response

Status code:
200 
{
  "id": "d9033d56-659c-437a-b5b7-4f3b14301dd4",
  "name": "Main",
  "offerExpiresAfterSeconds": 300,
  "mode": {
    "kind": "longestIdle",
    "minConcurrentOffers": 1,
    "maxConcurrentOffers": 5,
    "bypassSelectors": false
  },
  "etag": "etag"
}
Status code:
201 
{
  "id": "d9033d56-659c-437a-b5b7-4f3b14301dd4",
  "name": "Main",
  "offerExpiresAfterSeconds": 300,
  "mode": {
    "kind": "longestIdle",
    "minConcurrentOffers": 1,
    "maxConcurrentOffers": 5,
    "bypassSelectors": false
  },
  "etag": "etag"
}

Definitions

Name Description
Azure.Core.Foundations.Error

The error object.
Azure.Core.Foundations.ErrorResponse

A response containing error details.
Azure.Core.Foundations.InnerError

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
BestWorkerMode

Jobs are distributed to the worker with the strongest abilities available.
BestWorkerModeCreateOrUpdate

Jobs are distributed to the worker with the strongest abilities available.
DirectMapRouterRule

A rule that return the same labels as the input labels.
DirectMapRouterRuleCreateOrUpdate

A rule that return the same labels as the input labels.
DistributionModeKind

Discriminators for supported distribution mode types.
DistributionPolicy

Policy governing how jobs are distributed to workers
DistributionPolicyCreateOrUpdate

Policy governing how jobs are distributed to workers
ExpressionRouterRule

A rule providing inline expression rules.
ExpressionRouterRuleCreateOrUpdate

A rule providing inline expression rules.
ExpressionRouterRuleLanguage

Available expression languages that can be configured.
FunctionRouterRule

A rule providing a binding to an HTTP Triggered Azure Function.
FunctionRouterRuleCreateOrUpdate

A rule providing a binding to an HTTP Triggered Azure Function.
FunctionRouterRuleCredential

Credentials used to access Azure function rule.
LongestIdleMode

Jobs are directed to the worker who has been idle longest.
LongestIdleModeCreateOrUpdate

Jobs are directed to the worker who has been idle longest.
OAuth2WebhookClientCredential

OAuth2.0 Credentials used to Contoso's Authorization server. Reference: https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/
RoundRobinMode

Jobs are distributed in order to workers, starting with the worker that is after the last worker to receive a job.
RoundRobinModeCreateOrUpdate

Jobs are distributed in order to workers, starting with the worker that is after the last worker to receive a job.
RouterRuleKind

Discriminators for supported router rule types.
ScoringRuleOptions

Encapsulates all options that can be passed as parameters for scoring rule with BestWorkerMode.
ScoringRuleParameterSelector

Supported parameters for scoring workers used with BestWorkerMode.
StaticRouterRule

A rule providing static rules that always return the same result, regardless of input.
StaticRouterRuleCreateOrUpdate

A rule providing static rules that always return the same result, regardless of input.
WebhookRouterRule

A rule providing a binding to an external web server.
WebhookRouterRuleCreateOrUpdate

A rule providing a binding to an external web server.

Azure.Core.Foundations.Error

Object

The error object.

Name Type Description
code

string

One of a server-defined set of error codes.
details

Azure.Core.Foundations.Error[]

An array of details about specific errors that led to this reported error.
innererror

Azure.Core.Foundations.InnerError

An object containing more specific information than the current object about the error.
message

string

A human-readable representation of the error.
target

string

The target of the error.

Azure.Core.Foundations.ErrorResponse

Object

A response containing error details.

Name Type Description
error

Azure.Core.Foundations.Error

The error object.

Azure.Core.Foundations.InnerError

Object

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name Type Description
code

string

One of a server-defined set of error codes.
innererror

Azure.Core.Foundations.InnerError

Inner error.

BestWorkerMode

Object

Jobs are distributed to the worker with the strongest abilities available.

Name Type Default value Description
bypassSelectors

boolean

False

If set to true, then router will match workers to jobs even if they don't match label selectors. Warning: You may get workers that are not qualified for a job they are matched with if you set this variable to true. This flag is intended more for temporary usage. By default, set to false.
kind string:

bestWorker

The type discriminator describing a sub-type of DistributionMode.
maxConcurrentOffers

integer (int32)

1

Governs the maximum number of active concurrent offers a job can have.
minConcurrentOffers

integer (int32)

1

Governs the minimum desired number of active concurrent offers a job can have.
scoringRule RouterRule:

Define a scoring rule to use, when calculating a score to determine the best worker. If not set, will use a default scoring formula that uses the number of job labels that the worker labels match, as well as the number of label selectors the worker labels match and/or exceed using a logistic function (https://en.wikipedia.org/wiki/Logistic_function).
scoringRuleOptions

ScoringRuleOptions

Options to configure 'scoringRule'. If not set, default values are used.

BestWorkerModeCreateOrUpdate

Object

Jobs are distributed to the worker with the strongest abilities available.

Name Type Default value Description
bypassSelectors

boolean

False

If set to true, then router will match workers to jobs even if they don't match label selectors. Warning: You may get workers that are not qualified for a job they are matched with if you set this variable to true. This flag is intended more for temporary usage. By default, set to false.
kind string:

bestWorker

The type discriminator describing a sub-type of DistributionMode.
maxConcurrentOffers

integer (int32)

1

Governs the maximum number of active concurrent offers a job can have.
minConcurrentOffers

integer (int32)

1

Governs the minimum desired number of active concurrent offers a job can have.
scoringRule RouterRuleCreateOrUpdate:

Define a scoring rule to use, when calculating a score to determine the best worker. If not set, will use a default scoring formula that uses the number of job labels that the worker labels match, as well as the number of label selectors the worker labels match and/or exceed using a logistic function (https://en.wikipedia.org/wiki/Logistic_function).
scoringRuleOptions

ScoringRuleOptions

Options to configure 'scoringRule'. If not set, default values are used.

DirectMapRouterRule

Object

A rule that return the same labels as the input labels.

Name Type Description
kind string:

directMap

The type discriminator describing a sub-type of RouterRule

DirectMapRouterRuleCreateOrUpdate

Object

A rule that return the same labels as the input labels.

Name Type Description
kind string:

directMap

The type discriminator describing a sub-type of RouterRule

DistributionModeKind

Enumeration

Discriminators for supported distribution mode types.

Value Description
bestWorker

Discriminator value for BestWorkerMode.
longestIdle

Discriminator value for LongestIdleMode.
roundRobin

Discriminator value for RoundRobinMode.

DistributionPolicy

Object

Policy governing how jobs are distributed to workers

Name Type Description
etag

string

The entity tag for this resource.
id

string

Id of a distribution policy.
mode DistributionMode:

Mode governing the specific distribution method.
name

string

Friendly name of this policy.
offerExpiresAfterSeconds

number (double)

Number of seconds after which any offers created under this policy will be expired.

DistributionPolicyCreateOrUpdate

Object

Policy governing how jobs are distributed to workers

Name Type Description
mode DistributionModeCreateOrUpdate:

Mode governing the specific distribution method.
name

string

Friendly name of this policy.
offerExpiresAfterSeconds

number (double)

Number of seconds after which any offers created under this policy will be expired.

ExpressionRouterRule

Object

A rule providing inline expression rules.

Name Type Description
expression

string

An expression to evaluate. Should contain return statement with calculated values.
kind string:

expression

The type discriminator describing a sub-type of RouterRule
language

ExpressionRouterRuleLanguage

The expression language to compile to and execute.

ExpressionRouterRuleCreateOrUpdate

Object

A rule providing inline expression rules.

Name Type Description
expression

string

An expression to evaluate. Should contain return statement with calculated values.
kind string:

expression

The type discriminator describing a sub-type of RouterRule
language

ExpressionRouterRuleLanguage

The expression language to compile to and execute.

ExpressionRouterRuleLanguage

Enumeration

Available expression languages that can be configured.

Value Description
powerFx

PowerFx

FunctionRouterRule

Object

A rule providing a binding to an HTTP Triggered Azure Function.

Name Type Description
credential

FunctionRouterRuleCredential

Credentials used to access Azure function rule.
functionUri

string (uri)

URL for Azure Function.
kind string:

function

The type discriminator describing a sub-type of RouterRule

FunctionRouterRuleCreateOrUpdate

Object

A rule providing a binding to an HTTP Triggered Azure Function.

Name Type Description
credential

FunctionRouterRuleCredential

Credentials used to access Azure function rule.
functionUri

string (uri)

URL for Azure Function.
kind string:

function

The type discriminator describing a sub-type of RouterRule

FunctionRouterRuleCredential

Object

Credentials used to access Azure function rule.

Name Type Description
appKey

string

Access key scoped to a Azure Function app. This key grants access to all functions under the app.
clientId

string

Client id, when AppKey is provided In context of Azure function, this is usually the name of the key.
functionKey

string

Access key scoped to a particular function.

LongestIdleMode

Object

Jobs are directed to the worker who has been idle longest.

Name Type Default value Description
bypassSelectors

boolean

False

If set to true, then router will match workers to jobs even if they don't match label selectors. Warning: You may get workers that are not qualified for a job they are matched with if you set this variable to true. This flag is intended more for temporary usage. By default, set to false.
kind string:

longestIdle

The type discriminator describing a sub-type of DistributionMode.
maxConcurrentOffers

integer (int32)

1

Governs the maximum number of active concurrent offers a job can have.
minConcurrentOffers

integer (int32)

1

Governs the minimum desired number of active concurrent offers a job can have.

LongestIdleModeCreateOrUpdate

Object

Jobs are directed to the worker who has been idle longest.

Name Type Default value Description
bypassSelectors

boolean

False

If set to true, then router will match workers to jobs even if they don't match label selectors. Warning: You may get workers that are not qualified for a job they are matched with if you set this variable to true. This flag is intended more for temporary usage. By default, set to false.
kind string:

longestIdle

The type discriminator describing a sub-type of DistributionMode.
maxConcurrentOffers

integer (int32)

1

Governs the maximum number of active concurrent offers a job can have.
minConcurrentOffers

integer (int32)

1

Governs the minimum desired number of active concurrent offers a job can have.

OAuth2WebhookClientCredential

Object

OAuth2.0 Credentials used to Contoso's Authorization server. Reference: https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/

Name Type Description
clientId

string

ClientId for Contoso Authorization server.
clientSecret

string

Client secret for Contoso Authorization server.

RoundRobinMode

Object

Jobs are distributed in order to workers, starting with the worker that is after the last worker to receive a job.

Name Type Default value Description
bypassSelectors

boolean

False

If set to true, then router will match workers to jobs even if they don't match label selectors. Warning: You may get workers that are not qualified for a job they are matched with if you set this variable to true. This flag is intended more for temporary usage. By default, set to false.
kind string:

roundRobin

The type discriminator describing a sub-type of DistributionMode.
maxConcurrentOffers

integer (int32)

1

Governs the maximum number of active concurrent offers a job can have.
minConcurrentOffers

integer (int32)

1

Governs the minimum desired number of active concurrent offers a job can have.

RoundRobinModeCreateOrUpdate

Object

Jobs are distributed in order to workers, starting with the worker that is after the last worker to receive a job.

Name Type Default value Description
bypassSelectors

boolean

False

If set to true, then router will match workers to jobs even if they don't match label selectors. Warning: You may get workers that are not qualified for a job they are matched with if you set this variable to true. This flag is intended more for temporary usage. By default, set to false.
kind string:

roundRobin

The type discriminator describing a sub-type of DistributionMode.
maxConcurrentOffers

integer (int32)

1

Governs the maximum number of active concurrent offers a job can have.
minConcurrentOffers

integer (int32)

1

Governs the minimum desired number of active concurrent offers a job can have.

RouterRuleKind

Enumeration

Discriminators for supported router rule types.

Value Description
directMap

Discriminator value for DirectMapRouterRule.
expression

Discriminator value for ExpressionRouterRule.
function

Discriminator value for FunctionRouterRule.
static

Discriminator value for StaticRouterRule.
webhook

Discriminator value for WebhookRouterRule.

ScoringRuleOptions

Object

Encapsulates all options that can be passed as parameters for scoring rule with BestWorkerMode.

Name Type Default value Description
batchSize

integer (int32)

20

Set batch size when 'isBatchScoringEnabled' is set to true. Defaults to 20 if not configured.
descendingOrder

boolean

True

If false, will sort scores by ascending order. By default, set to true.
isBatchScoringEnabled

boolean

False

If set to true, will score workers in batches, and the parameter name of the worker labels will be sent as workers. By default, set to false and the parameter name for the worker labels will be sent as worker. Note: If enabled, use 'batchSize' to set batch size.
scoringParameters

ScoringRuleParameterSelector[]

[ "jobLabels", "workerSelectors" ]

List of extra parameters from a job that will be sent as part of the payload to scoring rule. If not set, a job's labels (sent in the payload as job) and a job's worker selectors (sent in the payload as selectors) are added to the payload of the scoring rule by default. Note: Worker labels are always sent with scoring payload.

ScoringRuleParameterSelector

Enumeration

Supported parameters for scoring workers used with BestWorkerMode.

Value Description
jobLabels

Parameter to add job labels to scoring payload. Property is sent as job.
workerSelectors

Parameter to add worker selectors from a job to scoring payload. Property is sent as selectors.

StaticRouterRule

Object

A rule providing static rules that always return the same result, regardless of input.

Name Type Description
kind string:

static

The type discriminator describing a sub-type of RouterRule
value

The static value this rule always returns. Values must be primitive values - number, string, boolean.

StaticRouterRuleCreateOrUpdate

Object

A rule providing static rules that always return the same result, regardless of input.

Name Type Description
kind string:

static

The type discriminator describing a sub-type of RouterRule
value

The static value this rule always returns. Values must be primitive values - number, string, boolean.

WebhookRouterRule

Object

A rule providing a binding to an external web server.

Name Type Description
authorizationServerUri

string (uri)

Uri for Authorization Server.
clientCredential

OAuth2WebhookClientCredential

OAuth2.0 Credentials used to Contoso's Authorization server. Reference: https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/
kind string:

webhook

The type discriminator describing a sub-type of RouterRule
webhookUri

string (uri)

Uri for Contoso's Web Server.

WebhookRouterRuleCreateOrUpdate

Object

A rule providing a binding to an external web server.

Name Type Description
authorizationServerUri

string (uri)

Uri for Authorization Server.
clientCredential

OAuth2WebhookClientCredential

OAuth2.0 Credentials used to Contoso's Authorization server. Reference: https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/
kind string:

webhook

The type discriminator describing a sub-type of RouterRule
webhookUri

string (uri)

Uri for Contoso's Web Server.