Create or Update Entity

Article
05/10/2022

Creates or updates a messaging entity.

Request

Method	Request URI	HTTP Version
PUT	https://{serviceNamespace}.servicebus.windows.net/{Entity Path}	HTTP/1.1

The entity path can be a multi-segment name, with segments separated by '/'. The entirety of the path makes up the name of the entities. Multiple entities can share the same prefix segments.

Request Headers

The following table describes required and optional request headers.

Request Header	Description
Authorization	Specifies a Shared Access Signature (SAS) token with "Manage" rights. See Service Bus authentication with Shared Access Signatures for details.
Content-Type	Set to application/atom+xml;type=entry;charset=utf-8.
If-Match	Set this header to “*” to update the entity. You must provide all the property values that are desired on the updated entity. Any values not provided are set to the service default values. If this header is missing, the update call returns an error indicating that this entity already exists.

Request Body

The body of the request must contain a valid Atom XML entry that embeds the description of the entity that shall be created

<?xml version="1.0" encoding="utf-8" ?>  
<entry xmlns='http://www.w3.org/2005/Atom'>  
  <content type='application/xml'>  
    {description}  
  </content>  
</entry>

Whereby the {description} described either a Queue or a Topic for top-level entities, or a subscription or rule relative to their parent entities.

A queue, for instance, is described with a QueueDescription element. The XML payload for creating or updating a queue therefore might take the following form, whereby all omitted properties assume their default values:

<?xml version="1.0" encoding="utf-8" ?>  
<entry xmlns="http://www.w3.org/2005/Atom">  
  <content type="application/xml">  
    <QueueDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
       <LockDuration>T1M</LockDuration>
    </QueueDescription>
  </content>  
</entry>

See the Overview for more details on entities and how they relate to paths.

Response

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

Response Codes

Note

If you update an entity with a name containing special or encoded characters (for example, "test?Name=value&"), which gets encoded to "test%3FName%3Dvalue%26"), a (401) unauthorized exception will be generated.

Code	Description
201	Entity updated.
400	Invalid request body.
401	Authorization failure.
403	Quota exceeded; entity not updated.
500	Internal error.

For information about status codes, see Status and Error Codes.

Response Headers

None.

Response Body

The entity description is returned. Some description properties might contain default values if they were missing from the PUT request.

Share via