Folder Register VM Task

Adds an existing virtual machine to the folder.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

This operation only works if the folder's type is VirtualMachine. In addition to the VirtualMachine.Inventory.Register and Resource.AssignVMToPool privileges, it requires System.Read privilege on the datastore that the existing virtual machine resides on. If the virtual machine is encrypted Cryptographer.RegisterVM is required on the folder, in which the virtual machine is registered. Otherwise, the VM is registered successfully, but is left in the locked state.

Required privileges: VirtualMachine.Inventory.Register

Request

URI

POST

https://{vcenter-host}/sdk/vim25/{release}/Folder/{moId}/RegisterVM_Task

COPY

Path Parameters

string

moId

Required

The unique identifier for the managed object to which the method attaches; the serialized managed object reference for a request has the form moType/moId, in this case Folder/{moId}.

string

release

Required

The vSphere release schema. The current specification covers vSphere 8.0.2.0 APIs.

Request Body

RegisterVMRequestType of type(s) application/json

Required

{
    "path": "string",
    "name": "string",
    "asTemplate": false,
    "pool": {
        "type": "string",
        "value": "string"
    },
    "host": {
        "type": "string",
        "value": "string"
    }
}

string

path

Required

A datastore path to the virtual machine.

string

name

Optional

The name to be assigned to the virtual machine. If this parameter is not set, the displayName configuration parameter of the virtual machine is used. An entity name must be a non-empty string of less than 80 characters. The slash (/), backslash (\) and percent (%) will be escaped using the URL syntax. For example, %2F.

boolean

asTemplate

Required

Flag to specify whether or not the virtual machine should be marked as a template.

MoRefResourcePool

pool

Optional

Reference to an instance of the ResourcePool managed object.

MoRefHostSystem

host

Optional

Reference to an instance of the HostSystem managed object.

Authentication

This operation uses the following authentication methods.

Session

Responses

200

This method returns a Task object with which to monitor the operation. The info.result property in the Task contains the newly registered VirtualMachine upon success.

Returns MoRefTask of type(s) application/json

This response body class contains all of the following: MoRefExtensibleManagedObject

{
    "_typeName": "string",
    "type": "string",
    "value": "string"
}

500

NotSupported: if the operation is not supported. For example, templates are not supported directly on hosts. Also, if the operation is invoked on a folder whose childType property is not set to "VirtualMachine".

OutOfBounds: if the maximum number of VMs for this folder has been exceeded. The maximum number is determined by Host.capability.maxSupportedVMs.

DuplicateName: if another virtual machine in the same folder has the target name.

AlreadyExists: if the virtual machine is already registered.

InvalidDatastore: if the operation cannot be performed on the target datastores.

NotFound: if the configuration file is not found on the system.

InvalidName: if the entity name is invalid.

InvalidArgument: if any of the arguments such as host or resource pool are not set to valid values.

VmConfigFault: if the format / configuration of the virtual machine is invalid. Typically, a more specific fault is thrown such as InvalidFormat if the configuration file cannot be read, or InvalidDiskFormat if the disks cannot be read.

FileFault: if there is an error accessing the files on disk.

InsufficientResourcesFault: if this operation would violate a resource usage policy.

InvalidState: if the operation is not allowed in current state of the entities involved.

Returns VimFault of type(s) application/json

This response body class contains all of the following: MethodFault

{
    "_typeName": "string",
    "faultCause": "MethodFault Object",
    "faultMessage": [
        {
            "_typeName": "string",
            "key": "string",
            "arg": [
                {
                    "_typeName": "string",
                    "key": "string",
                    "value": {
                        "_typeName": "string"
                    }
                }
            ],
            "message": "string"
        }
    ]
}

On This Page

Description

Request

Path Parameters

Request Body

Authentication

Response

200 Response Body

Errors

Folder Operations

POST

Folder Add Standalone Host Task