Extension Service AMQP Message Format

vCloud Director uses the system AMQP service to communicate with extension services. Messages to and from an extension service are formatted as JSON objects.

When it receives an extension request, the vCloud Director REST service creates a message and sends it to the system AMQP service, specifying the exchange and routing key registered by the extension service. The extension service retrieves the message from a queue bound to the exchange it registered, processes the request, and returns a response to the common reply exchange.

AMQP Message Headers

Each message from vCloud Director to a service includes both standard and custom AMQP headers.

Extension Service AMQP Message Headers

Header

Value

correlationId

A standard AMQP header that provides a unique identifier for the message. The extension must supply the same correlationId in the corresponding response.

reply-to

A standard AMQP header specifying the value that the extension must use as the routingKey in the response.

messageType

A custom AMQP header. One of:

ProcessHttpRequest	Indicates that this message is a forwarded request.
ProcessHttpResponse	Indicates that this message is a forwarded response.

replyToExchange

A custom AMQP header. The name of the AMQP exchange to which the extension should publish its response.

Property Names and Values

A request message contains all of the following name=value pairs.

Extension Service AMQP Request Message Property Names and Values
Name	Value
method	The HTTP method (GET, PUT, POST, DELETE) used to make the request
id	The unique id of this message
scheme	The scheme (HTTP or HTTPS) specified in the request URL
protocol	The protocol used to make the request
headers	The request headers represented as a map of `name`:`value` pairs encoded as a JSON object in the form: `name`:`value`,`name`:`value`,...
queryString	The entire query string, or null if the request did not include a query string.
localPort	The local port to which the request was sent
remoteAddr	The IP address of the requesting machine
remotePort	The remote port from which the request was sent
localAddr	The IP address to which the request was sent
request	Always `true` in request messages
requestURI	The request URL, without any query string it might have included
parameters	always null
user	The id of the vCloud Director user who made the request
org	The id of the vCloud Director organization to which the requesting user belongs
rights	A comma-separated list of id values for the vCloud Director rights assigned to the requesting user.

The parameters, user, org, and rights properties provide the security context for the request, and are formatted as a separate JSON object, as shown in Example: AMQP Message Format

A response message contains all of the following name=value pairs.

Extension Service AMQP Response Message Property Names and Values
Name	Value
id	The unique id of this message
headers	A comma-separated list of request headers in the form: `name`:`value`,`name`:`value`,...
statusCode	The HTTP status code to return to the requester
body	A base64-encoded response body
request	Always `false` in response messages

Example: AMQP Message Format

Assume an extension service that includes an API filter of the following form:

<vmext:ApiFilter>
   <vmext:UrlPattern>/api/org/.*</vmext:UrlPattern>
</vmext:ApiFilter>

When vCloud Director receives a request like this one:

GET https://10.23.6.168:8443/api/org/a93c9db9-7471-3192-8d09-a8f7eeda85f9

it creates the following message and places it on the service's exchange.

[
  {
    "method":"GET",
    "id":"32d5b9ec-5eef-4aa3-9375-b054018b0e30",
    "scheme":"https",
    "protocol":"HTTP/1.1",
    "headers":{"Cookie":"...", "User-Agent":"...", ...},
    "queryString":null,
    "localPort":8443,
    "remoteAddr":"10.23.6.168",
    "remotePort":60576,
    "localAddr":"10.100.1.40",
    "request":true,
    "requestUri":"/api/org/a93c9db9-7471-3192-8d09-a8f7eeda85f9"
  },
  {
    "parameters":null,
    "user":"urn:vcloud:user:8cdd352f-f831-4712-a1a3-9e061687c5c6",
    "org":"urn:vcloud:org:a93c9db9-7471-3192-8d09-a8f7eeda85f9",
    "rights":["urn:vcloud:right:0b8c8cd2-5af9-32ad-a0bd-dc356503a552",...]
  },
  null
]

The service returns a response containing a base64-encoded body.

[
  {
    "id":"32d5b9ec-5eef-4aa3-9375-b054018b0e30",
    "headers":{"Date":"...", "Content-Type":"application/vnd.vmware.vcloud.org+xml;version=2.0"},
    "statusCode":200,
    "body":"base64-encoded-body",
    "request":false,
  }
]