Share via

Job Router Operations - Upsert Worker

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

Creates or updates a worker.

PATCH {endpoint}/routing/workers/{workerId}?api-version=2023-11-01

URI Parameters

Name In Required Type Description
endpoint
 path True

string

Uri of your Communication resource
workerId
 path True

string

Id of a worker.
api-version
 query True

string

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
availableForOffers

boolean

A flag indicating this worker is open to receive offers or not.
capacity

integer

The total capacity score this worker has to manage multiple concurrent jobs.
channels

RouterChannel[]

Collection of channel(s) this worker can handle and their impact on the workers capacity.
labels

A set of key/value pairs that are identifying attributes used by the rules engines to make decisions. Values must be primitive values - number, string, boolean.
queues

string[]

Collection of queue(s) that this worker can receive work from.
tags

A set of non-identifying attributes attached to this worker. Values must be primitive values - number, string, boolean.

Responses

Name Type Description
200 OK

RouterWorker

The request has succeeded.

Headers

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

RouterWorker

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

Examples

Creates a worker
De-register an active worker
De-register an inactive worker
Register a worker
Updates a worker

Creates a worker

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/workers/WorkerId?api-version=2023-11-01

{
  "capacity": 10,
  "queues": [
    "MainQueue"
  ],
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "availableForOffers": false
}

Sample response

Status code:
200 
{
  "id": "WorkerId",
  "state": "inactive",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": false,
  "etag": "etag"
}
Status code:
201 
{
  "id": "WorkerId",
  "state": "inactive",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": false,
  "etag": "etag"
}

De-register an active worker

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/workers/WorkerId?api-version=2023-11-01

{
  "availableForOffers": false,
  "capacity": 10
}

Sample response

Status code:
200 
{
  "id": "WorkerId",
  "state": "draining",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": false,
  "etag": "etag"
}
Status code:
201 
{
  "id": "WorkerId",
  "state": "draining",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": false,
  "etag": "etag"
}

De-register an inactive worker

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/workers/WorkerId?api-version=2023-11-01

{
  "availableForOffers": false,
  "capacity": 10
}

Sample response

Status code:
200 
{
  "id": "WorkerId",
  "state": "inactive",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": false,
  "etag": "etag"
}
Status code:
201 
{
  "id": "WorkerId",
  "state": "inactive",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": false,
  "etag": "etag"
}

Register a worker

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/workers/WorkerId?api-version=2023-11-01

{
  "availableForOffers": true,
  "capacity": 10
}

Sample response

Status code:
200 
{
  "id": "WorkerId",
  "state": "active",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": true,
  "etag": "etag"
}
Status code:
201 
{
  "id": "WorkerId",
  "state": "active",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": true,
  "etag": "etag"
}

Updates a worker

Sample request

PATCH https://contoso.westus.communications.azure.com/routing/workers/WorkerId?api-version=2023-11-01

{
  "capacity": 10,
  "queues": [
    "MainQueue",
    "SecondaryQueue"
  ],
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "availableForOffers": false
}

Sample response

Status code:
200 
{
  "id": "WorkerId",
  "state": "inactive",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": false,
  "etag": "etag"
}
Status code:
201 
{
  "id": "WorkerId",
  "state": "inactive",
  "queues": [
    "MainQueue"
  ],
  "capacity": 10,
  "labels": {},
  "tags": {},
  "channels": [
    {
      "channelId": "CustomChatChannel",
      "capacityCostPerJob": 11,
      "maxNumberOfJobs": 4
    },
    {
      "channelId": "CustomVoiceChannel",
      "capacityCostPerJob": 10,
      "maxNumberOfJobs": 1
    }
  ],
  "offers": [],
  "assignedJobs": [],
  "loadRatio": 0,
  "availableForOffers": 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.
RouterChannel

Represents the capacity a job in this channel will consume from a worker.
RouterJobOffer

An offer of a job to a worker.
RouterWorker

An entity for jobs to be routed to.
RouterWorkerAssignment

The assignment for a worker to a job.
RouterWorkerCreateOrUpdate

An entity for jobs to be routed to.
RouterWorkerState

Enums for worker states.

Azure.Core.Foundations.Error

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

A response containing error details.

Name Type Description
error

Azure.Core.Foundations.Error

The error object.

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.

Name Type Description
code

string

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

Azure.Core.Foundations.InnerError

Inner error.

RouterChannel

Represents the capacity a job in this channel will consume from a worker.

Name Type Description
capacityCostPerJob

integer

The amount of capacity that an instance of a job of this channel will consume of the total worker capacity.
channelId

string

Id of a channel.
maxNumberOfJobs

integer

The maximum number of jobs that can be supported concurrently for this channel. Value must be greater than zero.

RouterJobOffer

An offer of a job to a worker.

Name Type Description
capacityCost

integer

The capacity cost consumed by the job offer.
expiresAt

string

Timestamp when the offer will expire in UTC.
jobId

string

Id of the job.
offerId

string

Id of an offer.
offeredAt

string

Timestamp when the offer was created in UTC.

RouterWorker

An entity for jobs to be routed to.

Name Type Description
assignedJobs

RouterWorkerAssignment[]

A list of assigned jobs attached to this worker.
availableForOffers

boolean

A flag indicating this worker is open to receive offers or not.
capacity

integer

The total capacity score this worker has to manage multiple concurrent jobs.
channels

RouterChannel[]

Collection of channel(s) this worker can handle and their impact on the workers capacity.
etag

string

The entity tag for this resource.
id

string

Id of a worker.
labels

A set of key/value pairs that are identifying attributes used by the rules engines to make decisions. Values must be primitive values - number, string, boolean.
loadRatio

number

A value indicating the workers capacity. A value of '1' means all capacity is consumed. A value of '0' means no capacity is currently consumed.
offers

RouterJobOffer[]

A list of active offers issued to this worker.
queues

string[]

Collection of queue(s) that this worker can receive work from.
state

RouterWorkerState

Current state of a worker.
tags

A set of non-identifying attributes attached to this worker. Values must be primitive values - number, string, boolean.

RouterWorkerAssignment

The assignment for a worker to a job.

Name Type Description
assignedAt

string

The assignment time of the job in UTC.
assignmentId

string

Id of the assignment.
capacityCost

integer

The amount of capacity this assignment has consumed on the worker.
jobId

string

Id of the job assigned.

RouterWorkerCreateOrUpdate

An entity for jobs to be routed to.

Name Type Description
availableForOffers

boolean

A flag indicating this worker is open to receive offers or not.
capacity

integer

The total capacity score this worker has to manage multiple concurrent jobs.
channels

RouterChannel[]

Collection of channel(s) this worker can handle and their impact on the workers capacity.
labels

A set of key/value pairs that are identifying attributes used by the rules engines to make decisions. Values must be primitive values - number, string, boolean.
queues

string[]

Collection of queue(s) that this worker can receive work from.
tags

A set of non-identifying attributes attached to this worker. Values must be primitive values - number, string, boolean.

RouterWorkerState

Enums for worker states.

Name Type Description
active

string

Worker is active and available to take offers.
draining

string

Worker is not active, if there are existing offers they are being revoked. No new offers are sent.
inactive

string

Worker is not active. No new offers are sent.