REST API - get

esx gdp guest data: get

Return a stream of published guest data.

. Warning: This operation is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Request:

HTTP request

POST https://{server}/api/esx/gdp/guest-data
{
    "topic_prefixes"[
        "string",
        "string"
    ],
    "type""VM",
    "vms"[
        {
            "vm""obj-103",
            "instance_uuid""string",
            "bios_uuid""string"
        },
        {
            "vm""obj-103",
            "instance_uuid""string",
            "bios_uuid""string"
        }
    ],
    "past_seconds"1
}

Body Parameters:

Name Type Description
bold = required
- filter_spec Filter spec.
-.type string Type of the virtual machine identifier that users provide to indicate the virtual machine identifier scheme used in the array of vm_filter_spec. It determines which one of esx.gdp.guest_data.vm_filter_spec.vm, esx.gdp.guest_data.vm_filter_spec.bios_uuid, or esx.gdp.guest_data.vm_filter_spec.instance_uuid is set.

The publish_result structure returned from {@link GuestData@get} has the esx.gdp.publish_result.vm_id_type field set to the same value.

. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

List the ways to identify virtual machines on a host. Warning: This enumeration is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Value is one of:
VM: Use the identifier that VirtualCenter assigns to a virtual machine. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
BIOS_UUID: Use the virtual machine SMBIOS UUID. The virtual machine SMBIOS UUID is a 128-bit SMBIOS UUID of a virtual machine represented as a hexadecimal string in "12345678-abcd-1234-cdef-123456789abc" format. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
INSTANCE_UUID: Use the virtual machine instance UUID. The virtual machine instance UUID is a VirtualCenter-specific 128-bit UUID of a virtual machine, represented as a hexademical string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that may share the same SMBIOS UUID. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

-.vms vm_filter_spec[] A list of virtual machines to get data from. @field.optional If unset, get for all virtual machines on the hosts.

Each {name VmFilterSpec} in the list must set the corresponding virtual machine identifier field to match the virtual machine identifier type that esx.gdp.guest_data.filter_spec.type specifies. If a virtual machine appears in the list more than once, any redundant item is ignored.

. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional.

-.vms[].vm string Identifier that VirtualCenter assigns to a virtual machine.

esx.gdp.guest_data.filter_spec.type determines exactly which one of esx.gdp.guest_data.vm_filter_spec.vm, esx.gdp.guest_data.vm_filter_spec.bios_uuid, or esx.gdp.guest_data.vm_filter_spec.instance_uuid is set.

. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. If set, filter for a virtual machine matching this identifer. get throws InvalidArgument if esx.gdp.guest_data.filter_spec.type is not VM but this field is set.When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: VirtualMachine. When operations return a value of this structure as a result, the field will be an identifier for the resource type: VirtualMachine.

-.vms[].bios_uuid string 128-bit SMBIOS UUID of a virtual machine represented as a hexadecimal string in "12345678-abcd-1234-cdef-123456789abc" format.

. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. If set, filter for a virtual machine matching this identifier. get throws InvalidArgument if esx.gdp.guest_data.filter_spec.type is not BIOS_UUID but this field is set.

-.vms[].instance_uuid string VirtualCenter-specific 128-bit UUID of a virtual machine, represented as a hexademical string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that may share the same SMBIOS UUID.

. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. If set, filter for a virtual machine matching this identifier. get throws InvalidArgument if esx.gdp.guest_data.filter_spec.type is not INSTANCE_UUID but this field is set.

-.topic_prefixes string[] List of topic prefixes to match published data topics. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. If unset, get all topics available.

Each topic prefix is in the format of dot-concatenated topic domains starting with the root domain. For example, topic prefix x.y.z identify the topic branch of z, which is under the domain of y, which is under the root domain of x. Each topic prefix matches the entire branch, including all the sub nodes. For example, topic prefix x.y matches topic x.y and sub topic x.y.z if they are available.

A topic prefix is not allowed to be empty, or start with a dot, or end with a dot. get throws InvalidArgument if the above rule is violated.

.
-.past_seconds long The number of seconds of history to go back to. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. If unset, zero will be used.

Allows a client to get old published data cached in the system. The oldest available data are limited by the system cache size. This allows a client to recover lost data due to a network conection dropped momentarily. There is no limit on how large the input value can be so long as it fits the type. However, the system can only deliver available data in the cache, and will not deliver any data already evicted.

A negative value is not allowed. get throws InvalidArgument if the above rule is violated.

.

Response:

HTTP Status Code: 200

Response Body Structure:

{
    "create_time""2015-01-01T22:13:05.651Z",
    "vm_id_type""VM",
    "vm""obj-103",
    "topic""string",
    "type""string",
    "instance_uuid""string",
    "bios_uuid""string",
    "token""string"
}

Headers:

None

Type:

Name Type Description
bold = required
-.type string The type of the publication. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

-.topic string The topic of the publication in the format of dot-concatenated topic domains starting with the root domain. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

-.vm_id_type string Type of the virtual machine identity. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

List the ways to identify virtual machines on a host. Warning: This enumeration is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Value is one of:
VM: Use the identifier that VirtualCenter assigns to a virtual machine. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
BIOS_UUID: Use the virtual machine SMBIOS UUID. The virtual machine SMBIOS UUID is a 128-bit SMBIOS UUID of a virtual machine represented as a hexadecimal string in "12345678-abcd-1234-cdef-123456789abc" format. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
INSTANCE_UUID: Use the virtual machine instance UUID. The virtual machine instance UUID is a VirtualCenter-specific 128-bit UUID of a virtual machine, represented as a hexademical string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that may share the same SMBIOS UUID. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

-.vm string Identifier that VirtualCenter assigns to the virtual machine that published this datum. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. It is only relevant when vm_id_type has value VM. This field is optional and it is only relevant when the value of vm_id_type is VM.When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: VirtualMachine. When operations return a value of this structure as a result, the field will be an identifier for the resource type: VirtualMachine.

-.bios_uuid string SMBIOS UUID of the virtual machine that published this datum. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. It is only relevant when vm_id_type has value BIOS_UUID. This field is optional and it is only relevant when the value of vm_id_type is BIOS_UUID.

-.instance_uuid string Instance UUID of the virtual machine that published this datum. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Optional. It is only relevant when vm_id_type has value INSTANCE_UUID. This field is optional and it is only relevant when the value of vm_id_type is INSTANCE_UUID.

-.create_time date_time The time when the publication is created. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

-.token string The authorization token that subscribers can use to validate the publication on the particular topic is legit.

The publisher provided this token. The mechanism how to validate the token is between publishers and subscribers.

. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

- object Guest data published in real time.

Errors:

HTTP Status Code Type Description
400 invalid_argument if the filter spec is invalid.
401 unauthenticated if the caller is not authenticated.
403 unauthorized if the caller is not authorized.
500 error for any other error.