SDK for PHP 3.x

AWS Backup Gateway 2021-01-01

Client: Aws\BackupGateway\BackupGatewayClient
Service ID: backup-gateway
Version: 2021-01-01

This page describes the parameters and results for the operations of the AWS Backup Gateway (2021-01-01), and shows how to use the Aws\BackupGateway\BackupGatewayClient object to call the described operations. This documentation is specific to the 2021-01-01 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

AssociateGatewayToServer ( array $params = [] )
Associates a backup gateway with your server.
CreateGateway ( array $params = [] )
Creates a backup gateway.
DeleteGateway ( array $params = [] )
Deletes a backup gateway.
DeleteHypervisor ( array $params = [] )
Deletes a hypervisor.
DisassociateGatewayFromServer ( array $params = [] )
Disassociates a backup gateway from the specified server.
GetBandwidthRateLimitSchedule ( array $params = [] )
Retrieves the bandwidth rate limit schedule for a specified gateway.
GetGateway ( array $params = [] )
By providing the ARN (Amazon Resource Name), this API returns the gateway.
GetHypervisor ( array $params = [] )
This action requests information about the specified hypervisor to which the gateway will connect.
GetHypervisorPropertyMappings ( array $params = [] )
This action retrieves the property mappings for the specified hypervisor.
GetVirtualMachine ( array $params = [] )
By providing the ARN (Amazon Resource Name), this API returns the virtual machine.
ImportHypervisorConfiguration ( array $params = [] )
Connect to a hypervisor by importing its configuration.
ListGateways ( array $params = [] )
Lists backup gateways owned by an Amazon Web Services account in an Amazon Web Services Region.
ListHypervisors ( array $params = [] )
Lists your hypervisors.
ListTagsForResource ( array $params = [] )
Lists the tags applied to the resource identified by its Amazon Resource Name (ARN).
ListVirtualMachines ( array $params = [] )
Lists your virtual machines.
PutBandwidthRateLimitSchedule ( array $params = [] )
This action sets the bandwidth rate limit schedule for a specified gateway.
PutHypervisorPropertyMappings ( array $params = [] )
This action sets the property mappings for the specified hypervisor.
PutMaintenanceStartTime ( array $params = [] )
Set the maintenance start time for a gateway.
StartVirtualMachinesMetadataSync ( array $params = [] )
This action sends a request to sync metadata across the specified virtual machines.
TagResource ( array $params = [] )
Tag the resource.
TestHypervisorConfiguration ( array $params = [] )
Tests your hypervisor configuration to validate that backup gateway can connect with the hypervisor and its resources.
UntagResource ( array $params = [] )
Removes tags from the resource.
UpdateGatewayInformation ( array $params = [] )
Updates a gateway's name.
UpdateGatewaySoftwareNow ( array $params = [] )
Updates the gateway virtual machine (VM) software.
UpdateHypervisor ( array $params = [] )
Updates a hypervisor metadata, including its host, username, and password.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

ListGateways
ListHypervisors
ListVirtualMachines

Operations

AssociateGatewayToServer 

$result = $client->associateGatewayToServer([/* ... */]);
$promise = $client->associateGatewayToServerAsync([/* ... */]);

Associates a backup gateway with your server. After you complete the association process, you can back up and restore your VMs through the gateway.

Parameter Syntax

$result = $client->associateGatewayToServer([
    'GatewayArn' => '<string>', // REQUIRED
    'ServerArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and Amazon Web Services Region.

ServerArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the server that hosts your virtual machines.

Result Syntax

[
    'GatewayArn' => '<string>',
]

Result Details

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of a gateway.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

ConflictException:

The operation cannot proceed because it is not supported.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

CreateGateway 

$result = $client->createGateway([/* ... */]);
$promise = $client->createGatewayAsync([/* ... */]);

Creates a backup gateway. After you create a gateway, you can associate it with a server using the AssociateGatewayToServer operation.

Parameter Syntax

$result = $client->createGateway([
    'ActivationKey' => '<string>', // REQUIRED
    'GatewayDisplayName' => '<string>', // REQUIRED
    'GatewayType' => 'BACKUP_VM', // REQUIRED
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members
ActivationKey
Required: Yes
Type: string

The activation key of the created gateway.

GatewayDisplayName
Required: Yes
Type: string

The display name of the created gateway.

GatewayType
Required: Yes
Type: string

The type of created gateway.

Tags
Type: Array of Tag structures

A list of up to 50 tags to assign to the gateway. Each tag is a key-value pair.

Result Syntax

[
    'GatewayArn' => '<string>',
]

Result Details

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of the gateway you create.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

DeleteGateway 

$result = $client->deleteGateway([/* ... */]);
$promise = $client->deleteGatewayAsync([/* ... */]);

Deletes a backup gateway.

Parameter Syntax

$result = $client->deleteGateway([
    'GatewayArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the gateway to delete.

Result Syntax

[
    'GatewayArn' => '<string>',
]

Result Details

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of the gateway you deleted.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

DeleteHypervisor 

$result = $client->deleteHypervisor([/* ... */]);
$promise = $client->deleteHypervisorAsync([/* ... */]);

Deletes a hypervisor.

Parameter Syntax

$result = $client->deleteHypervisor([
    'HypervisorArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
HypervisorArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the hypervisor to delete.

Result Syntax

[
    'HypervisorArn' => '<string>',
]

Result Details

Members
HypervisorArn
Type: string

The Amazon Resource Name (ARN) of the hypervisor you deleted.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

ConflictException:

The operation cannot proceed because it is not supported.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

AccessDeniedException:

The operation cannot proceed because you have insufficient permissions.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

DisassociateGatewayFromServer 

$result = $client->disassociateGatewayFromServer([/* ... */]);
$promise = $client->disassociateGatewayFromServerAsync([/* ... */]);

Disassociates a backup gateway from the specified server. After the disassociation process finishes, the gateway can no longer access the virtual machines on the server.

Parameter Syntax

$result = $client->disassociateGatewayFromServer([
    'GatewayArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the gateway to disassociate.

Result Syntax

[
    'GatewayArn' => '<string>',
]

Result Details

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of the gateway you disassociated.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

ConflictException:

The operation cannot proceed because it is not supported.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

GetBandwidthRateLimitSchedule 

$result = $client->getBandwidthRateLimitSchedule([/* ... */]);
$promise = $client->getBandwidthRateLimitScheduleAsync([/* ... */]);

Retrieves the bandwidth rate limit schedule for a specified gateway. By default, gateways do not have bandwidth rate limit schedules, which means no bandwidth rate limiting is in effect. Use this to get a gateway's bandwidth rate limit schedule.

Parameter Syntax

$result = $client->getBandwidthRateLimitSchedule([
    'GatewayArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and Amazon Web Services Region.

Result Syntax

[
    'BandwidthRateLimitIntervals' => [
        [
            'AverageUploadRateLimitInBitsPerSec' => <integer>,
            'DaysOfWeek' => [<integer>, ...],
            'EndHourOfDay' => <integer>,
            'EndMinuteOfHour' => <integer>,
            'StartHourOfDay' => <integer>,
            'StartMinuteOfHour' => <integer>,
        ],
        // ...
    ],
    'GatewayArn' => '<string>',
]

Result Details

Members
BandwidthRateLimitIntervals
Type: Array of BandwidthRateLimitInterval structures

An array containing bandwidth rate limit schedule intervals for a gateway. When no bandwidth rate limit intervals have been scheduled, the array is empty.

GatewayArn
Type: string

The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and Amazon Web Services Region.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

GetGateway 

$result = $client->getGateway([/* ... */]);
$promise = $client->getGatewayAsync([/* ... */]);

By providing the ARN (Amazon Resource Name), this API returns the gateway.

Parameter Syntax

$result = $client->getGateway([
    'GatewayArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the gateway.

Result Syntax

[
    'Gateway' => [
        'GatewayArn' => '<string>',
        'GatewayDisplayName' => '<string>',
        'GatewayType' => 'BACKUP_VM',
        'HypervisorId' => '<string>',
        'LastSeenTime' => <DateTime>,
        'MaintenanceStartTime' => [
            'DayOfMonth' => <integer>,
            'DayOfWeek' => <integer>,
            'HourOfDay' => <integer>,
            'MinuteOfHour' => <integer>,
        ],
        'NextUpdateAvailabilityTime' => <DateTime>,
        'VpcEndpoint' => '<string>',
    ],
]

Result Details

Members
Gateway
Type: GatewayDetails structure

By providing the ARN (Amazon Resource Name), this API returns the gateway.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

GetHypervisor 

$result = $client->getHypervisor([/* ... */]);
$promise = $client->getHypervisorAsync([/* ... */]);

This action requests information about the specified hypervisor to which the gateway will connect. A hypervisor is hardware, software, or firmware that creates and manages virtual machines, and allocates resources to them.

Parameter Syntax

$result = $client->getHypervisor([
    'HypervisorArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
HypervisorArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the hypervisor.

Result Syntax

[
    'Hypervisor' => [
        'Host' => '<string>',
        'HypervisorArn' => '<string>',
        'KmsKeyArn' => '<string>',
        'LastSuccessfulMetadataSyncTime' => <DateTime>,
        'LatestMetadataSyncStatus' => 'CREATED|RUNNING|FAILED|PARTIALLY_FAILED|SUCCEEDED',
        'LatestMetadataSyncStatusMessage' => '<string>',
        'LogGroupArn' => '<string>',
        'Name' => '<string>',
        'State' => 'PENDING|ONLINE|OFFLINE|ERROR',
    ],
]

Result Details

Members
Hypervisor
Type: HypervisorDetails structure

Details about the requested hypervisor.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

GetHypervisorPropertyMappings 

$result = $client->getHypervisorPropertyMappings([/* ... */]);
$promise = $client->getHypervisorPropertyMappingsAsync([/* ... */]);

This action retrieves the property mappings for the specified hypervisor. A hypervisor property mapping displays the relationship of entity properties available from the on-premises hypervisor to the properties available in Amazon Web Services.

Parameter Syntax

$result = $client->getHypervisorPropertyMappings([
    'HypervisorArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
HypervisorArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the hypervisor.

Result Syntax

[
    'HypervisorArn' => '<string>',
    'IamRoleArn' => '<string>',
    'VmwareToAwsTagMappings' => [
        [
            'AwsTagKey' => '<string>',
            'AwsTagValue' => '<string>',
            'VmwareCategory' => '<string>',
            'VmwareTagName' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
HypervisorArn
Type: string

The Amazon Resource Name (ARN) of the hypervisor.

IamRoleArn
Type: string

The Amazon Resource Name (ARN) of the IAM role.

VmwareToAwsTagMappings
Type: Array of VmwareToAwsTagMapping structures

This is a display of the mappings of on-premises VMware tags to the Amazon Web Services tags.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

GetVirtualMachine 

$result = $client->getVirtualMachine([/* ... */]);
$promise = $client->getVirtualMachineAsync([/* ... */]);

By providing the ARN (Amazon Resource Name), this API returns the virtual machine.

Parameter Syntax

$result = $client->getVirtualMachine([
    'ResourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
ResourceArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the virtual machine.

Result Syntax

[
    'VirtualMachine' => [
        'HostName' => '<string>',
        'HypervisorId' => '<string>',
        'LastBackupDate' => <DateTime>,
        'Name' => '<string>',
        'Path' => '<string>',
        'ResourceArn' => '<string>',
        'VmwareTags' => [
            [
                'VmwareCategory' => '<string>',
                'VmwareTagDescription' => '<string>',
                'VmwareTagName' => '<string>',
            ],
            // ...
        ],
    ],
]

Result Details

Members
VirtualMachine
Type: VirtualMachineDetails structure

This object contains the basic attributes of VirtualMachine contained by the output of GetVirtualMachine

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

ImportHypervisorConfiguration 

$result = $client->importHypervisorConfiguration([/* ... */]);
$promise = $client->importHypervisorConfigurationAsync([/* ... */]);

Connect to a hypervisor by importing its configuration.

Parameter Syntax

$result = $client->importHypervisorConfiguration([
    'Host' => '<string>', // REQUIRED
    'KmsKeyArn' => '<string>',
    'Name' => '<string>', // REQUIRED
    'Password' => '<string>',
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
    'Username' => '<string>',
]);

Parameter Details

Members
Host
Required: Yes
Type: string

The server host of the hypervisor. This can be either an IP address or a fully-qualified domain name (FQDN).

KmsKeyArn
Type: string

The Key Management Service for the hypervisor.

Name
Required: Yes
Type: string

The name of the hypervisor.

Password
Type: string

The password for the hypervisor.

Tags
Type: Array of Tag structures

The tags of the hypervisor configuration to import.

Username
Type: string

The username for the hypervisor.

Result Syntax

[
    'HypervisorArn' => '<string>',
]

Result Details

Members
HypervisorArn
Type: string

The Amazon Resource Name (ARN) of the hypervisor you disassociated.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

ConflictException:

The operation cannot proceed because it is not supported.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

AccessDeniedException:

The operation cannot proceed because you have insufficient permissions.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

ListGateways 

$result = $client->listGateways([/* ... */]);
$promise = $client->listGatewaysAsync([/* ... */]);

Lists backup gateways owned by an Amazon Web Services account in an Amazon Web Services Region. The returned list is ordered by gateway Amazon Resource Name (ARN).

Parameter Syntax

$result = $client->listGateways([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
MaxResults
Type: int

The maximum number of gateways to list.

NextToken
Type: string

The next item following a partial list of returned resources. For example, if a request is made to return MaxResults number of resources, NextToken allows you to return more items in your list starting at the location pointed to by the next token.

Result Syntax

[
    'Gateways' => [
        [
            'GatewayArn' => '<string>',
            'GatewayDisplayName' => '<string>',
            'GatewayType' => 'BACKUP_VM',
            'HypervisorId' => '<string>',
            'LastSeenTime' => <DateTime>,
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members
Gateways
Type: Array of Gateway structures

A list of your gateways.

NextToken
Type: string

The next item following a partial list of returned resources. For example, if a request is made to return maxResults number of resources, NextToken allows you to return more items in your list starting at the location pointed to by the next token.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

ListHypervisors 

$result = $client->listHypervisors([/* ... */]);
$promise = $client->listHypervisorsAsync([/* ... */]);

Lists your hypervisors.

Parameter Syntax

$result = $client->listHypervisors([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
MaxResults
Type: int

The maximum number of hypervisors to list.

NextToken
Type: string

The next item following a partial list of returned resources. For example, if a request is made to return maxResults number of resources, NextToken allows you to return more items in your list starting at the location pointed to by the next token.

Result Syntax

[
    'Hypervisors' => [
        [
            'Host' => '<string>',
            'HypervisorArn' => '<string>',
            'KmsKeyArn' => '<string>',
            'Name' => '<string>',
            'State' => 'PENDING|ONLINE|OFFLINE|ERROR',
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members
Hypervisors
Type: Array of Hypervisor structures

A list of your Hypervisor objects, ordered by their Amazon Resource Names (ARNs).

NextToken
Type: string

The next item following a partial list of returned resources. For example, if a request is made to return maxResults number of resources, NextToken allows you to return more items in your list starting at the location pointed to by the next token.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

ListTagsForResource 

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

Lists the tags applied to the resource identified by its Amazon Resource Name (ARN).

Parameter Syntax

$result = $client->listTagsForResource([
    'ResourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
ResourceArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the resource's tags to list.

Result Syntax

[
    'ResourceArn' => '<string>',
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
ResourceArn
Type: string

The Amazon Resource Name (ARN) of the resource's tags that you listed.

Tags
Type: Array of Tag structures

A list of the resource's tags.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

ListVirtualMachines 

$result = $client->listVirtualMachines([/* ... */]);
$promise = $client->listVirtualMachinesAsync([/* ... */]);

Lists your virtual machines.

Parameter Syntax

$result = $client->listVirtualMachines([
    'HypervisorArn' => '<string>',
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
HypervisorArn
Type: string

The Amazon Resource Name (ARN) of the hypervisor connected to your virtual machine.

MaxResults
Type: int

The maximum number of virtual machines to list.

NextToken
Type: string

The next item following a partial list of returned resources. For example, if a request is made to return maxResults number of resources, NextToken allows you to return more items in your list starting at the location pointed to by the next token.

Result Syntax

[
    'NextToken' => '<string>',
    'VirtualMachines' => [
        [
            'HostName' => '<string>',
            'HypervisorId' => '<string>',
            'LastBackupDate' => <DateTime>,
            'Name' => '<string>',
            'Path' => '<string>',
            'ResourceArn' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
NextToken
Type: string

The next item following a partial list of returned resources. For example, if a request is made to return maxResults number of resources, NextToken allows you to return more items in your list starting at the location pointed to by the next token.

VirtualMachines
Type: Array of VirtualMachine structures

A list of your VirtualMachine objects, ordered by their Amazon Resource Names (ARNs).

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

PutBandwidthRateLimitSchedule 

$result = $client->putBandwidthRateLimitSchedule([/* ... */]);
$promise = $client->putBandwidthRateLimitScheduleAsync([/* ... */]);

This action sets the bandwidth rate limit schedule for a specified gateway. By default, gateways do not have a bandwidth rate limit schedule, which means no bandwidth rate limiting is in effect. Use this to initiate a gateway's bandwidth rate limit schedule.

Parameter Syntax

$result = $client->putBandwidthRateLimitSchedule([
    'BandwidthRateLimitIntervals' => [ // REQUIRED
        [
            'AverageUploadRateLimitInBitsPerSec' => <integer>,
            'DaysOfWeek' => [<integer>, ...], // REQUIRED
            'EndHourOfDay' => <integer>, // REQUIRED
            'EndMinuteOfHour' => <integer>, // REQUIRED
            'StartHourOfDay' => <integer>, // REQUIRED
            'StartMinuteOfHour' => <integer>, // REQUIRED
        ],
        // ...
    ],
    'GatewayArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
BandwidthRateLimitIntervals
Required: Yes
Type: Array of BandwidthRateLimitInterval structures

An array containing bandwidth rate limit schedule intervals for a gateway. When no bandwidth rate limit intervals have been scheduled, the array is empty.

GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and Amazon Web Services Region.

Result Syntax

[
    'GatewayArn' => '<string>',
]

Result Details

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and Amazon Web Services Region.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

PutHypervisorPropertyMappings 

$result = $client->putHypervisorPropertyMappings([/* ... */]);
$promise = $client->putHypervisorPropertyMappingsAsync([/* ... */]);

This action sets the property mappings for the specified hypervisor. A hypervisor property mapping displays the relationship of entity properties available from the on-premises hypervisor to the properties available in Amazon Web Services.

Parameter Syntax

$result = $client->putHypervisorPropertyMappings([
    'HypervisorArn' => '<string>', // REQUIRED
    'IamRoleArn' => '<string>', // REQUIRED
    'VmwareToAwsTagMappings' => [ // REQUIRED
        [
            'AwsTagKey' => '<string>', // REQUIRED
            'AwsTagValue' => '<string>', // REQUIRED
            'VmwareCategory' => '<string>', // REQUIRED
            'VmwareTagName' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members
HypervisorArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the hypervisor.

IamRoleArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the IAM role.

VmwareToAwsTagMappings
Required: Yes
Type: Array of VmwareToAwsTagMapping structures

This action requests the mappings of on-premises VMware tags to the Amazon Web Services tags.

Result Syntax

[
    'HypervisorArn' => '<string>',
]

Result Details

Members
HypervisorArn
Type: string

The Amazon Resource Name (ARN) of the hypervisor.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

ConflictException:

The operation cannot proceed because it is not supported.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

AccessDeniedException:

The operation cannot proceed because you have insufficient permissions.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

PutMaintenanceStartTime 

$result = $client->putMaintenanceStartTime([/* ... */]);
$promise = $client->putMaintenanceStartTimeAsync([/* ... */]);

Set the maintenance start time for a gateway.

Parameter Syntax

$result = $client->putMaintenanceStartTime([
    'DayOfMonth' => <integer>,
    'DayOfWeek' => <integer>,
    'GatewayArn' => '<string>', // REQUIRED
    'HourOfDay' => <integer>, // REQUIRED
    'MinuteOfHour' => <integer>, // REQUIRED
]);

Parameter Details

Members
DayOfMonth
Type: int

The day of the month start maintenance on a gateway.

Valid values range from Sunday to Saturday.

DayOfWeek
Type: int

The day of the week to start maintenance on a gateway.

GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) for the gateway, used to specify its maintenance start time.

HourOfDay
Required: Yes
Type: int

The hour of the day to start maintenance on a gateway.

MinuteOfHour
Required: Yes
Type: int

The minute of the hour to start maintenance on a gateway.

Result Syntax

[
    'GatewayArn' => '<string>',
]

Result Details

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of a gateway for which you set the maintenance start time.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

ConflictException:

The operation cannot proceed because it is not supported.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

StartVirtualMachinesMetadataSync 

$result = $client->startVirtualMachinesMetadataSync([/* ... */]);
$promise = $client->startVirtualMachinesMetadataSyncAsync([/* ... */]);

This action sends a request to sync metadata across the specified virtual machines.

Parameter Syntax

$result = $client->startVirtualMachinesMetadataSync([
    'HypervisorArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
HypervisorArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the hypervisor.

Result Syntax

[
    'HypervisorArn' => '<string>',
]

Result Details

Members
HypervisorArn
Type: string

The Amazon Resource Name (ARN) of the hypervisor.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

AccessDeniedException:

The operation cannot proceed because you have insufficient permissions.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

TagResource 

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Tag the resource.

Parameter Syntax

$result = $client->tagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'Tags' => [ // REQUIRED
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members
ResourceARN
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the resource to tag.

Tags
Required: Yes
Type: Array of Tag structures

A list of tags to assign to the resource.

Result Syntax

[
    'ResourceARN' => '<string>',
]

Result Details

Members
ResourceARN
Type: string

The Amazon Resource Name (ARN) of the resource you tagged.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

TestHypervisorConfiguration 

$result = $client->testHypervisorConfiguration([/* ... */]);
$promise = $client->testHypervisorConfigurationAsync([/* ... */]);

Tests your hypervisor configuration to validate that backup gateway can connect with the hypervisor and its resources.

Parameter Syntax

$result = $client->testHypervisorConfiguration([
    'GatewayArn' => '<string>', // REQUIRED
    'Host' => '<string>', // REQUIRED
    'Password' => '<string>',
    'Username' => '<string>',
]);

Parameter Details

Members
GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the gateway to the hypervisor to test.

Host
Required: Yes
Type: string

The server host of the hypervisor. This can be either an IP address or a fully-qualified domain name (FQDN).

Password
Type: string

The password for the hypervisor.

Username
Type: string

The username for the hypervisor.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

ConflictException:

The operation cannot proceed because it is not supported.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

UntagResource 

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes tags from the resource.

Parameter Syntax

$result = $client->untagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'TagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
ResourceARN
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the resource from which to remove tags.

TagKeys
Required: Yes
Type: Array of strings

The list of tag keys specifying which tags to remove.

Result Syntax

[
    'ResourceARN' => '<string>',
]

Result Details

Members
ResourceARN
Type: string

The Amazon Resource Name (ARN) of the resource from which you removed tags.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

UpdateGatewayInformation 

$result = $client->updateGatewayInformation([/* ... */]);
$promise = $client->updateGatewayInformationAsync([/* ... */]);

Updates a gateway's name. Specify which gateway to update using the Amazon Resource Name (ARN) of the gateway in your request.

Parameter Syntax

$result = $client->updateGatewayInformation([
    'GatewayArn' => '<string>', // REQUIRED
    'GatewayDisplayName' => '<string>',
]);

Parameter Details

Members
GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the gateway to update.

GatewayDisplayName
Type: string

The updated display name of the gateway.

Result Syntax

[
    'GatewayArn' => '<string>',
]

Result Details

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of the gateway you updated.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

ConflictException:

The operation cannot proceed because it is not supported.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

UpdateGatewaySoftwareNow 

$result = $client->updateGatewaySoftwareNow([/* ... */]);
$promise = $client->updateGatewaySoftwareNowAsync([/* ... */]);

Updates the gateway virtual machine (VM) software. The request immediately triggers the software update.

When you make this request, you get a 200 OK success response immediately. However, it might take some time for the update to complete.

Parameter Syntax

$result = $client->updateGatewaySoftwareNow([
    'GatewayArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
GatewayArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the gateway to be updated.

Result Syntax

[
    'GatewayArn' => '<string>',
]

Result Details

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of the gateway you updated.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

UpdateHypervisor 

$result = $client->updateHypervisor([/* ... */]);
$promise = $client->updateHypervisorAsync([/* ... */]);

Updates a hypervisor metadata, including its host, username, and password. Specify which hypervisor to update using the Amazon Resource Name (ARN) of the hypervisor in your request.

Parameter Syntax

$result = $client->updateHypervisor([
    'Host' => '<string>',
    'HypervisorArn' => '<string>', // REQUIRED
    'LogGroupArn' => '<string>',
    'Name' => '<string>',
    'Password' => '<string>',
    'Username' => '<string>',
]);

Parameter Details

Members
Host
Type: string

The updated host of the hypervisor. This can be either an IP address or a fully-qualified domain name (FQDN).

HypervisorArn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the hypervisor to update.

LogGroupArn
Type: string

The Amazon Resource Name (ARN) of the group of gateways within the requested log.

Name
Type: string

The updated name for the hypervisor

Password
Type: string

The updated password for the hypervisor.

Username
Type: string

The updated username for the hypervisor.

Result Syntax

[
    'HypervisorArn' => '<string>',
]

Result Details

Members
HypervisorArn
Type: string

The Amazon Resource Name (ARN) of the hypervisor you updated.

Errors

ValidationException:

The operation did not succeed because a validation error occurred.

ConflictException:

The operation cannot proceed because it is not supported.

InternalServerException:

The operation did not succeed because an internal error occurred. Try again later.

AccessDeniedException:

The operation cannot proceed because you have insufficient permissions.

ResourceNotFoundException:

A resource that is required for the action wasn't found.

ThrottlingException:

TPS has been limited to protect against intentional or unintentional high request volumes.

Shapes

AccessDeniedException

Description

The operation cannot proceed because you have insufficient permissions.

Members
ErrorCode
Required: Yes
Type: string

A description of why you have insufficient permissions.

Message
Type: string

BandwidthRateLimitInterval

Description

Describes a bandwidth rate limit interval for a gateway. A bandwidth rate limit schedule consists of one or more bandwidth rate limit intervals. A bandwidth rate limit interval defines a period of time on one or more days of the week, during which bandwidth rate limits are specified for uploading, downloading, or both.

Members
AverageUploadRateLimitInBitsPerSec
Type: long (int|float)

The average upload rate limit component of the bandwidth rate limit interval, in bits per second. This field does not appear in the response if the upload rate limit is not set.

For Backup Gateway, the minimum value is (Value).

DaysOfWeek
Required: Yes
Type: Array of ints

The days of the week component of the bandwidth rate limit interval, represented as ordinal numbers from 0 to 6, where 0 represents Sunday and 6 represents Saturday.

EndHourOfDay
Required: Yes
Type: int

The hour of the day to end the bandwidth rate limit interval.

EndMinuteOfHour
Required: Yes
Type: int

The minute of the hour to end the bandwidth rate limit interval.

The bandwidth rate limit interval ends at the end of the minute. To end an interval at the end of an hour, use the value 59.

StartHourOfDay
Required: Yes
Type: int

The hour of the day to start the bandwidth rate limit interval.

StartMinuteOfHour
Required: Yes
Type: int

The minute of the hour to start the bandwidth rate limit interval. The interval begins at the start of that minute. To begin an interval exactly at the start of the hour, use the value 0.

ConflictException

Description

The operation cannot proceed because it is not supported.

Members
ErrorCode
Required: Yes
Type: string

A description of why the operation is not supported.

Message
Type: string

Gateway

Description

A gateway is an Backup Gateway appliance that runs on the customer's network to provide seamless connectivity to backup storage in the Amazon Web Services Cloud.

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and Amazon Web Services Region.

GatewayDisplayName
Type: string

The display name of the gateway.

GatewayType
Type: string

The type of the gateway.

HypervisorId
Type: string

The hypervisor ID of the gateway.

LastSeenTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

The last time Backup gateway communicated with the gateway, in Unix format and UTC time.

GatewayDetails

Description

The details of gateway.

Members
GatewayArn
Type: string

The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and Amazon Web Services Region.

GatewayDisplayName
Type: string

The display name of the gateway.

GatewayType
Type: string

The type of the gateway type.

HypervisorId
Type: string

The hypervisor ID of the gateway.

LastSeenTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

Details showing the last time Backup gateway communicated with the cloud, in Unix format and UTC time.

MaintenanceStartTime
Type: MaintenanceStartTime structure

Returns your gateway's weekly maintenance start time including the day and time of the week. Note that values are in terms of the gateway's time zone. Can be weekly or monthly.

NextUpdateAvailabilityTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

Details showing the next update availability time of the gateway.

VpcEndpoint
Type: string

The DNS name for the virtual private cloud (VPC) endpoint the gateway uses to connect to the cloud for backup gateway.

Hypervisor

Description

Represents the hypervisor's permissions to which the gateway will connect.

A hypervisor is hardware, software, or firmware that creates and manages virtual machines, and allocates resources to them.

Members
Host
Type: string

The server host of the hypervisor. This can be either an IP address or a fully-qualified domain name (FQDN).

HypervisorArn
Type: string

The Amazon Resource Name (ARN) of the hypervisor.

KmsKeyArn
Type: string

The Amazon Resource Name (ARN) of the Key Management Service used to encrypt the hypervisor.

Name
Type: string

The name of the hypervisor.

State
Type: string

The state of the hypervisor.

HypervisorDetails

Description

These are the details of the specified hypervisor. A hypervisor is hardware, software, or firmware that creates and manages virtual machines, and allocates resources to them.

Members
Host
Type: string

The server host of the hypervisor. This can be either an IP address or a fully-qualified domain name (FQDN).

HypervisorArn
Type: string

The Amazon Resource Name (ARN) of the hypervisor.

KmsKeyArn
Type: string

The Amazon Resource Name (ARN) of the KMS used to encrypt the hypervisor.

LastSuccessfulMetadataSyncTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

This is the time when the most recent successful sync of metadata occurred.

LatestMetadataSyncStatus
Type: string

This is the most recent status for the indicated metadata sync.

LatestMetadataSyncStatusMessage
Type: string

This is the most recent status for the indicated metadata sync.

LogGroupArn
Type: string

The Amazon Resource Name (ARN) of the group of gateways within the requested log.

Name
Type: string

This is the name of the specified hypervisor.

State
Type: string

This is the current state of the specified hypervisor.

The possible states are PENDING, ONLINE, OFFLINE, or ERROR.

InternalServerException

Description

The operation did not succeed because an internal error occurred. Try again later.

Members
ErrorCode
Type: string

A description of which internal error occured.

Message
Type: string

MaintenanceStartTime

Description

This is your gateway's weekly maintenance start time including the day and time of the week. Note that values are in terms of the gateway's time zone. Can be weekly or monthly.

Members
DayOfMonth
Type: int

The day of the month component of the maintenance start time represented as an ordinal number from 1 to 28, where 1 represents the first day of the month and 28 represents the last day of the month.

DayOfWeek
Type: int

An ordinal number between 0 and 6 that represents the day of the week, where 0 represents Sunday and 6 represents Saturday. The day of week is in the time zone of the gateway.

HourOfDay
Required: Yes
Type: int

The hour component of the maintenance start time represented as hh, where hh is the hour (0 to 23). The hour of the day is in the time zone of the gateway.

MinuteOfHour
Required: Yes
Type: int

The minute component of the maintenance start time represented as mm, where mm is the minute (0 to 59). The minute of the hour is in the time zone of the gateway.

ResourceNotFoundException

Description

A resource that is required for the action wasn't found.

Members
ErrorCode
Type: string

A description of which resource wasn't found.

Message
Type: string

Tag

Description

A key-value pair you can use to manage, filter, and search for your resources. Allowed characters include UTF-8 letters, numbers, spaces, and the following characters: + - = . _ : /.

Members
Key
Required: Yes
Type: string

The key part of a tag's key-value pair. The key can't start with aws:.

Value
Required: Yes
Type: string

The value part of a tag's key-value pair.

ThrottlingException

Description

TPS has been limited to protect against intentional or unintentional high request volumes.

Members
ErrorCode
Required: Yes
Type: string

Error: TPS has been limited to protect against intentional or unintentional high request volumes.

Message
Type: string

ValidationException

Description

The operation did not succeed because a validation error occurred.

Members
ErrorCode
Type: string

A description of what caused the validation error.

Message
Type: string

VirtualMachine

Description

A virtual machine that is on a hypervisor.

Members
HostName
Type: string

The host name of the virtual machine.

HypervisorId
Type: string

The ID of the virtual machine's hypervisor.

LastBackupDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The most recent date a virtual machine was backed up, in Unix format and UTC time.

Name
Type: string

The name of the virtual machine.

Path
Type: string

The path of the virtual machine.

ResourceArn
Type: string

The Amazon Resource Name (ARN) of the virtual machine. For example, arn:aws:backup-gateway:us-west-1:0000000000000:vm/vm-0000ABCDEFGIJKL.

VirtualMachineDetails

Description

Your VirtualMachine objects, ordered by their Amazon Resource Names (ARNs).

Members
HostName
Type: string

The host name of the virtual machine.

HypervisorId
Type: string

The ID of the virtual machine's hypervisor.

LastBackupDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The most recent date a virtual machine was backed up, in Unix format and UTC time.

Name
Type: string

The name of the virtual machine.

Path
Type: string

The path of the virtual machine.

ResourceArn
Type: string

The Amazon Resource Name (ARN) of the virtual machine. For example, arn:aws:backup-gateway:us-west-1:0000000000000:vm/vm-0000ABCDEFGIJKL.

VmwareTags
Type: Array of VmwareTag structures

These are the details of the VMware tags associated with the specified virtual machine.

VmwareTag

Description

A VMware tag is a tag attached to a specific virtual machine. A tag is a key-value pair you can use to manage, filter, and search for your resources.

The content of VMware tags can be matched to Amazon Web Services tags.

Members
VmwareCategory
Type: string

The is the category of VMware.

VmwareTagDescription
Type: string

This is a user-defined description of a VMware tag.

VmwareTagName
Type: string

This is the user-defined name of a VMware tag.

VmwareToAwsTagMapping

Description

This displays the mapping of on-premises VMware tags to the corresponding Amazon Web Services tags.

Members
AwsTagKey
Required: Yes
Type: string

The key part of the Amazon Web Services tag's key-value pair.

AwsTagValue
Required: Yes
Type: string

The value part of the Amazon Web Services tag's key-value pair.

VmwareCategory
Required: Yes
Type: string

The is the category of VMware.

VmwareTagName
Required: Yes
Type: string

This is the user-defined name of a VMware tag.