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.
- GetGateway ( array $params = [] )
By providing the ARN (Amazon Resource Name), this API returns the gateway.
- 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.
- PutMaintenanceStartTime ( array $params = [] )
Set the maintenance start time for a gateway.
- 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:
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
ListGatewaysoperation 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
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation cannot proceed because it is not supported.
-
The operation did not succeed because an internal error occurred. Try again later.
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
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
DeleteGateway
$result = $client->deleteGateway([/* ... */]); $promise = $client->deleteGatewayAsync([/* ... */]);
Deletes a backup gateway.
Parameter Syntax
$result = $client->deleteGateway([
'GatewayArn' => '<string>', // REQUIRED
]);
Parameter Details
Members
Result Syntax
[
'GatewayArn' => '<string>',
]
Result Details
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
DeleteHypervisor
$result = $client->deleteHypervisor([/* ... */]); $promise = $client->deleteHypervisorAsync([/* ... */]);
Deletes a hypervisor.
Parameter Syntax
$result = $client->deleteHypervisor([
'HypervisorArn' => '<string>', // REQUIRED
]);
Parameter Details
Members
Result Syntax
[
'HypervisorArn' => '<string>',
]
Result Details
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
-
The operation cannot proceed because you have insufficient permissions.
-
A resource that is required for the action wasn't found.
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
Result Syntax
[
'GatewayArn' => '<string>',
]
Result Details
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation cannot proceed because it is not supported.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
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
Result Syntax
[
'Gateway' => [
'GatewayArn' => '<string>',
'GatewayDisplayName' => '<string>',
'GatewayType' => 'BACKUP_VM',
'HypervisorId' => '<string>',
'LastSeenTime' => <DateTime>,
'NextUpdateAvailabilityTime' => <DateTime>,
'VpcEndpoint' => '<string>',
],
]
Result Details
Members
- Gateway
-
- Type: GatewayDetails structure
By providing the ARN (Amazon Resource Name), this API returns the gateway.
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
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
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
-
The operation cannot proceed because you have insufficient permissions.
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
MaxResultsnumber of resources,NextTokenallows 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
maxResultsnumber of resources,NextTokenallows you to return more items in your list starting at the location pointed to by the next token.
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
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
maxResultsnumber of resources,NextTokenallows 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
Hypervisorobjects, 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
maxResultsnumber of resources,NextTokenallows you to return more items in your list starting at the location pointed to by the next token.
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
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
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
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
ListVirtualMachines
$result = $client->listVirtualMachines([/* ... */]); $promise = $client->listVirtualMachinesAsync([/* ... */]);
Lists your virtual machines.
Parameter Syntax
$result = $client->listVirtualMachines([
'MaxResults' => <integer>,
'NextToken' => '<string>',
]);
Parameter Details
Members
- 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
maxResultsnumber of resources,NextTokenallows 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
maxResultsnumber of resources,NextTokenallows 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
VirtualMachineobjects, ordered by their Amazon Resource Names (ARNs).
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
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
SundaytoSaturday. - 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
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation cannot proceed because it is not supported.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
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
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
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
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation cannot proceed because it is not supported.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
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
Result Syntax
[
'ResourceARN' => '<string>',
]
Result Details
Members
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
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
Result Syntax
[
'GatewayArn' => '<string>',
]
Result Details
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation cannot proceed because it is not supported.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
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
Result Syntax
[
'GatewayArn' => '<string>',
]
Result Details
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
-
A resource that is required for the action wasn't found.
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
'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.
- 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
Errors
-
The operation did not succeed because a validation error occurred.
-
The operation did not succeed because an internal error occurred. Try again later.
-
The operation cannot proceed because you have insufficient permissions.
-
A resource that is required for the action wasn't found.
Shapes
AccessDeniedException
Description
The operation cannot proceed because you have insufficient permissions.
Members
ConflictException
Description
The operation cannot proceed because it is not supported.
Members
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
ListGatewaysoperation 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
ListGatewaysoperation 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.
- 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.
InternalServerException
Description
The operation did not succeed because an internal error occurred. Try again later.
Members
ResourceNotFoundException
Description
A resource that is required for the action wasn't found.
Members
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
ValidationException
Description
The operation did not succeed because a validation error occurred.
Members
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.