2019/04/16 - AWS Storage Gateway - 8 updated api methods
Changes This change allows you to select either a weekly or monthly maintenance window for your volume or tape gateway. It also allows you to tag your tape and volume resources on creation by adding a Tag value on calls to the respective api endpoints.
{'Tags': [{'Key': 'string', 'Value': 'string'}]}
Creates a cached volume on a specified cached volume gateway. This operation is only supported in the cached volume gateway type.
Note
Cache storage must be allocated to the gateway before you can create a cached volume. Use the AddCache operation to add cache storage to a gateway.
In the request, you must specify the gateway, size of the volume in bytes, the iSCSI target name, an IP address on which to expose the target, and a unique client token. In response, the gateway creates the volume and returns information about it. This information includes the volume Amazon Resource Name (ARN), its size, and the iSCSI target ARN that initiators can use to connect to the volume target.
Optionally, you can provide the ARN for an existing volume as the SourceVolumeARN for this cached volume, which creates an exact copy of the existing volume’s latest recovery point. The VolumeSizeInBytes value must be equal to or larger than the size of the copied volume, in bytes.
See also: AWS API Documentation
Request Syntax
client.create_cached_iscsi_volume(
GatewayARN='string',
VolumeSizeInBytes=123,
SnapshotId='string',
TargetName='string',
SourceVolumeARN='string',
NetworkInterfaceId='string',
ClientToken='string',
KMSEncrypted=True|False,
KMSKey='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
integer
[REQUIRED]
The size of the volume in bytes.
string
The snapshot ID (e.g. "snap-1122aabb") of the snapshot to restore as the new cached volume. Specify this field if you want to create the iSCSI storage volume from a snapshot otherwise do not include this field. To list snapshots for your account use DescribeSnapshots in the Amazon Elastic Compute Cloud API Reference .
string
[REQUIRED]
The name of the iSCSI target used by an initiator to connect to a volume and used as a suffix for the target ARN. For example, specifying TargetName as myvolume results in the target ARN of arn:aws:storagegateway:us-east-2:111122223333:gateway/sgw-12A3456B/target/iqn.1997-05.com.amazon:myvolume . The target name must be unique across all volumes on a gateway.
If you don't specify a value, Storage Gateway uses the value that was previously used for this volume as the new target name.
string
The ARN for an existing volume. Specifying this ARN makes the new volume into an exact copy of the specified existing volume's latest recovery point. The VolumeSizeInBytes value for this new volume must be equal to or larger than the size of the existing volume, in bytes.
string
[REQUIRED]
The network interface of the gateway on which to expose the iSCSI target. Only IPv4 addresses are accepted. Use DescribeGatewayInformation to get a list of the network interfaces available on a gateway.
Valid Values: A valid IP address.
string
[REQUIRED]
A unique identifier that you use to retry a request. If you retry a request, use the same ClientToken you specified in the initial request.
boolean
True to use Amazon S3 server side encryption with your own AWS KMS key, or false to use a key managed by Amazon S3. Optional.
string
The Amazon Resource Name (ARN) of the AWS KMS key used for Amazon S3 server side encryption. This value can only be set when KMSEncrypted is true. Optional.
list
A list of up to 50 tags that can be assigned to a cached volume. Each tag is a key-value pair.
Note
Valid characters for key and value are letters, spaces, and numbers representable in UTF-8 format, and the following special characters: + - = . _ : / @. The maximum length of a tag's key is 128 characters, and the maximum length for a tag's value is 256.
(dict) --
A key-value pair that helps you manage, filter, and search for your resource. Allowed characters: letters, white space, and numbers, representable in UTF-8, and the following characters: + - = . _ : /
Key (string) -- [REQUIRED]
Tag key (String). The key can't start with aws:.
Value (string) -- [REQUIRED]
Value of the tag key.
dict
Response Syntax
{
'VolumeARN': 'string',
'TargetARN': 'string'
}
Response Structure
(dict) --
VolumeARN (string) --
The Amazon Resource Name (ARN) of the configured volume.
TargetARN (string) --
The Amazon Resource Name (ARN) of the volume target, which includes the iSCSI name that initiators can use to connect to the target.
{'Tags': [{'Key': 'string', 'Value': 'string'}]}
Creates a volume on a specified gateway. This operation is only supported in the stored volume gateway type.
The size of the volume to create is inferred from the disk size. You can choose to preserve existing data on the disk, create volume from an existing snapshot, or create an empty volume. If you choose to create an empty gateway volume, then any existing data on the disk is erased.
In the request you must specify the gateway and the disk information on which you are creating the volume. In response, the gateway creates the volume and returns volume information such as the volume Amazon Resource Name (ARN), its size, and the iSCSI target ARN that initiators can use to connect to the volume target.
See also: AWS API Documentation
Request Syntax
client.create_stored_iscsi_volume(
GatewayARN='string',
DiskId='string',
SnapshotId='string',
PreserveExistingData=True|False,
TargetName='string',
NetworkInterfaceId='string',
KMSEncrypted=True|False,
KMSKey='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
string
[REQUIRED]
The unique identifier for the gateway local disk that is configured as a stored volume. Use ListLocalDisks to list disk IDs for a gateway.
string
The snapshot ID (e.g. "snap-1122aabb") of the snapshot to restore as the new stored volume. Specify this field if you want to create the iSCSI storage volume from a snapshot otherwise do not include this field. To list snapshots for your account use DescribeSnapshots in the Amazon Elastic Compute Cloud API Reference .
boolean
[REQUIRED]
Specify this field as true if you want to preserve the data on the local disk. Otherwise, specifying this field as false creates an empty volume.
Valid Values: true, false
string
[REQUIRED]
The name of the iSCSI target used by an initiator to connect to a volume and used as a suffix for the target ARN. For example, specifying TargetName as myvolume results in the target ARN of arn:aws:storagegateway:us-east-2:111122223333:gateway/sgw-12A3456B/target/iqn.1997-05.com.amazon:myvolume . The target name must be unique across all volumes on a gateway.
If you don't specify a value, Storage Gateway uses the value that was previously used for this volume as the new target name.
string
[REQUIRED]
The network interface of the gateway on which to expose the iSCSI target. Only IPv4 addresses are accepted. Use DescribeGatewayInformation to get a list of the network interfaces available on a gateway.
Valid Values: A valid IP address.
boolean
True to use Amazon S3 server side encryption with your own AWS KMS key, or false to use a key managed by Amazon S3. Optional.
string
The Amazon Resource Name (ARN) of the KMS key used for Amazon S3 server side encryption. This value can only be set when KMSEncrypted is true. Optional.
list
A list of up to 50 tags that can be assigned to a stored volume. Each tag is a key-value pair.
Note
Valid characters for key and value are letters, spaces, and numbers representable in UTF-8 format, and the following special characters: + - = . _ : / @. The maximum length of a tag's key is 128 characters, and the maximum length for a tag's value is 256.
(dict) --
A key-value pair that helps you manage, filter, and search for your resource. Allowed characters: letters, white space, and numbers, representable in UTF-8, and the following characters: + - = . _ : /
Key (string) -- [REQUIRED]
Tag key (String). The key can't start with aws:.
Value (string) -- [REQUIRED]
Value of the tag key.
dict
Response Syntax
{
'VolumeARN': 'string',
'VolumeSizeInBytes': 123,
'TargetARN': 'string'
}
Response Structure
(dict) --
A JSON object containing the following fields:
VolumeARN (string) --
The Amazon Resource Name (ARN) of the configured volume.
VolumeSizeInBytes (integer) --
The size of the volume in bytes.
TargetARN (string) --
The Amazon Resource Name (ARN) of the volume target, which includes the iSCSI name that initiators can use to connect to the target.
{'Tags': [{'Key': 'string', 'Value': 'string'}]}
Creates a virtual tape by using your own barcode. You write data to the virtual tape and then archive the tape. A barcode is unique and can not be reused if it has already been used on a tape . This applies to barcodes used on deleted tapes. This operation is only supported in the tape gateway type.
Note
Cache storage must be allocated to the gateway before you can create a virtual tape. Use the AddCache operation to add cache storage to a gateway.
See also: AWS API Documentation
Request Syntax
client.create_tape_with_barcode(
GatewayARN='string',
TapeSizeInBytes=123,
TapeBarcode='string',
KMSEncrypted=True|False,
KMSKey='string',
PoolId='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The unique Amazon Resource Name (ARN) that represents the gateway to associate the virtual tape with. Use the ListGateways operation to return a list of gateways for your account and region.
integer
[REQUIRED]
The size, in bytes, of the virtual tape that you want to create.
Note
The size must be aligned by gigabyte (1024*1024*1024 byte).
string
[REQUIRED]
The barcode that you want to assign to the tape.
Note
Barcodes cannot be reused. This includes barcodes used for tapes that have been deleted.
boolean
True to use Amazon S3 server side encryption with your own AWS KMS key, or false to use a key managed by Amazon S3. Optional.
string
The Amazon Resource Name (ARN) of the AWS KMS Key used for Amazon S3 server side encryption. This value can only be set when KMSEncrypted is true. Optional.
string
The ID of the pool that you want to add your tape to for archiving. The tape in this pool is archived in the S3 storage class that is associated with the pool. When you use your backup application to eject the tape, the tape is archived directly into the storage class (Glacier or Deep Archive) that corresponds to the pool.
Valid values: "GLACIER", "DEEP_ARCHIVE"
list
A list of up to 50 tags that can be assigned to a virtual tape that has a barcode. Each tag is a key-value pair.
Note
Valid characters for key and value are letters, spaces, and numbers representable in UTF-8 format, and the following special characters: + - = . _ : / @. The maximum length of a tag's key is 128 characters, and the maximum length for a tag's value is 256.
(dict) --
A key-value pair that helps you manage, filter, and search for your resource. Allowed characters: letters, white space, and numbers, representable in UTF-8, and the following characters: + - = . _ : /
Key (string) -- [REQUIRED]
Tag key (String). The key can't start with aws:.
Value (string) -- [REQUIRED]
Value of the tag key.
dict
Response Syntax
{
'TapeARN': 'string'
}
Response Structure
(dict) --
CreateTapeOutput
TapeARN (string) --
A unique Amazon Resource Name (ARN) that represents the virtual tape that was created.
{'Tags': [{'Key': 'string', 'Value': 'string'}]}
Creates one or more virtual tapes. You write data to the virtual tapes and then archive the tapes. This operation is only supported in the tape gateway type.
Note
Cache storage must be allocated to the gateway before you can create virtual tapes. Use the AddCache operation to add cache storage to a gateway.
See also: AWS API Documentation
Request Syntax
client.create_tapes(
GatewayARN='string',
TapeSizeInBytes=123,
ClientToken='string',
NumTapesToCreate=123,
TapeBarcodePrefix='string',
KMSEncrypted=True|False,
KMSKey='string',
PoolId='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The unique Amazon Resource Name (ARN) that represents the gateway to associate the virtual tapes with. Use the ListGateways operation to return a list of gateways for your account and region.
integer
[REQUIRED]
The size, in bytes, of the virtual tapes that you want to create.
Note
The size must be aligned by gigabyte (1024*1024*1024 byte).
string
[REQUIRED]
A unique identifier that you use to retry a request. If you retry a request, use the same ClientToken you specified in the initial request.
Note
Using the same ClientToken prevents creating the tape multiple times.
integer
[REQUIRED]
The number of virtual tapes that you want to create.
string
[REQUIRED]
A prefix that you append to the barcode of the virtual tape you are creating. This prefix makes the barcode unique.
Note
The prefix must be 1 to 4 characters in length and must be one of the uppercase letters from A to Z.
boolean
True to use Amazon S3 server side encryption with your own AWS KMS key, or false to use a key managed by Amazon S3. Optional.
string
The Amazon Resource Name (ARN) of the AWS KMS key used for Amazon S3 server side encryption. This value can only be set when KMSEncrypted is true. Optional.
string
The ID of the pool that you want to add your tape to for archiving. The tape in this pool is archived in the S3 storage class that is associated with the pool. When you use your backup application to eject the tape, the tape is archived directly into the storage class (Glacier or Deep Archive) that corresponds to the pool.
Valid values: "GLACIER", "DEEP_ARCHIVE"
list
A list of up to 50 tags that can be assigned to a virtual tape. Each tag is a key-value pair.
Note
Valid characters for key and value are letters, spaces, and numbers representable in UTF-8 format, and the following special characters: + - = . _ : / @. The maximum length of a tag's key is 128 characters, and the maximum length for a tag's value is 256.
(dict) --
A key-value pair that helps you manage, filter, and search for your resource. Allowed characters: letters, white space, and numbers, representable in UTF-8, and the following characters: + - = . _ : /
Key (string) -- [REQUIRED]
Tag key (String). The key can't start with aws:.
Value (string) -- [REQUIRED]
Value of the tag key.
dict
Response Syntax
{
'TapeARNs': [
'string',
]
}
Response Structure
(dict) --
CreateTapeOutput
TapeARNs (list) --
A list of unique Amazon Resource Names (ARNs) that represents the virtual tapes that were created.
(string) --
{'Ec2InstanceId': 'string', 'Ec2InstanceRegion': 'string'}
Returns metadata about a gateway such as its name, network interfaces, configured time zone, and the state (whether the gateway is running or not). To specify which gateway to describe, use the Amazon Resource Name (ARN) of the gateway in your request.
See also: AWS API Documentation
Request Syntax
client.describe_gateway_information(
GatewayARN='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
dict
Response Syntax
{
'GatewayARN': 'string',
'GatewayId': 'string',
'GatewayName': 'string',
'GatewayTimezone': 'string',
'GatewayState': 'string',
'GatewayNetworkInterfaces': [
{
'Ipv4Address': 'string',
'MacAddress': 'string',
'Ipv6Address': 'string'
},
],
'GatewayType': 'string',
'NextUpdateAvailabilityDate': 'string',
'LastSoftwareUpdate': 'string',
'Ec2InstanceId': 'string',
'Ec2InstanceRegion': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
Response Structure
(dict) --
A JSON object containing the following fields:
GatewayARN (string) --
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
GatewayId (string) --
The unique identifier assigned to your gateway during activation. This ID becomes part of the gateway Amazon Resource Name (ARN), which you use as input for other operations.
GatewayName (string) --
The name you configured for your gateway.
GatewayTimezone (string) --
A value that indicates the time zone configured for the gateway.
GatewayState (string) --
A value that indicates the operating state of the gateway.
GatewayNetworkInterfaces (list) --
A NetworkInterface array that contains descriptions of the gateway network interfaces.
(dict) --
Describes a gateway's network interface.
Ipv4Address (string) --
The Internet Protocol version 4 (IPv4) address of the interface.
MacAddress (string) --
The Media Access Control (MAC) address of the interface.
Note
This is currently unsupported and will not be returned in output.
Ipv6Address (string) --
The Internet Protocol version 6 (IPv6) address of the interface. Currently not supported .
GatewayType (string) --
The type of the gateway.
NextUpdateAvailabilityDate (string) --
The date on which an update to the gateway is available. This date is in the time zone of the gateway. If the gateway is not available for an update this field is not returned in the response.
LastSoftwareUpdate (string) --
The date on which the last software update was applied to the gateway. If the gateway has never been updated, this field does not return a value in the response.
Ec2InstanceId (string) --
The ID of the Amazon EC2 instance that was used to launch the gateway.
Ec2InstanceRegion (string) --
The AWS Region where the Amazon EC2 instance is located.
Tags (list) --
A list of up to 50 tags assigned to the gateway, sorted alphabetically by key name. Each tag is a key-value pair. For a gateway with more than 10 tags assigned, you can view all tags using the ListTagsForResource API operation.
(dict) --
A key-value pair that helps you manage, filter, and search for your resource. Allowed characters: letters, white space, and numbers, representable in UTF-8, and the following characters: + - = . _ : /
Key (string) --
Tag key (String). The key can't start with aws:.
Value (string) --
Value of the tag key.
{'DayOfMonth': 'integer'}
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.
See also: AWS API Documentation
Request Syntax
client.describe_maintenance_start_time(
GatewayARN='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
dict
Response Syntax
{
'GatewayARN': 'string',
'HourOfDay': 123,
'MinuteOfHour': 123,
'DayOfWeek': 123,
'DayOfMonth': 123,
'Timezone': 'string'
}
Response Structure
(dict) --
A JSON object containing the following fields:
DescribeMaintenanceStartTimeOutput$DayOfMonth
DescribeMaintenanceStartTimeOutput$DayOfWeek
DescribeMaintenanceStartTimeOutput$HourOfDay
DescribeMaintenanceStartTimeOutput$MinuteOfHour
DescribeMaintenanceStartTimeOutput$Timezone
GatewayARN (string) --
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
HourOfDay (integer) --
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 (integer) --
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.
DayOfWeek (integer) --
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.
DayOfMonth (integer) --
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.
Note
This value is only available for tape and volume gateways.
Timezone (string) --
A value that indicates the time zone that is set for the gateway. The start time and day of week specified should be in the time zone of the gateway.
{'Gateways': {'Ec2InstanceId': 'string', 'Ec2InstanceRegion': 'string'}}
Lists gateways owned by an AWS account in a region specified in the request. The returned list is ordered by gateway Amazon Resource Name (ARN).
By default, the operation returns a maximum of 100 gateways. This operation supports pagination that allows you to optionally reduce the number of gateways returned in a response.
If you have more gateways than are returned in a response (that is, the response returns only a truncated list of your gateways), the response contains a marker that you can specify in your next request to fetch the next page of gateways.
See also: AWS API Documentation
Request Syntax
client.list_gateways(
Marker='string',
Limit=123
)
string
An opaque string that indicates the position at which to begin the returned list of gateways.
integer
Specifies that the list of gateways returned be limited to the specified number of items.
dict
Response Syntax
{
'Gateways': [
{
'GatewayId': 'string',
'GatewayARN': 'string',
'GatewayType': 'string',
'GatewayOperationalState': 'string',
'GatewayName': 'string',
'Ec2InstanceId': 'string',
'Ec2InstanceRegion': 'string'
},
],
'Marker': 'string'
}
Response Structure
(dict) --
Gateways (list) --
An array of GatewayInfo objects.
(dict) --
Describes a gateway object.
GatewayId (string) --
The unique identifier assigned to your gateway during activation. This ID becomes part of the gateway Amazon Resource Name (ARN), which you use as input for other operations.
GatewayARN (string) --
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
GatewayType (string) --
The type of the gateway.
GatewayOperationalState (string) --
The state of the gateway.
Valid Values: DISABLED or ACTIVE
GatewayName (string) --
The name of the gateway.
Ec2InstanceId (string) --
The ID of the Amazon EC2 instance that was used to launch the gateway.
Ec2InstanceRegion (string) --
The AWS Region where the Amazon EC2 instance is located.
Marker (string) --
Use the marker in your next request to fetch the next set of gateways in the list. If there are no more gateways to list, this field does not appear in the response.
{'DayOfMonth': 'integer'}
Updates a gateway's weekly maintenance start time information, including day and time of the week. The maintenance time is the time in your gateway's time zone.
See also: AWS API Documentation
Request Syntax
client.update_maintenance_start_time(
GatewayARN='string',
HourOfDay=123,
MinuteOfHour=123,
DayOfWeek=123,
DayOfMonth=123
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.
integer
[REQUIRED]
The hour component of the maintenance start time represented as hh , where hh is the hour (00 to 23). The hour of the day is in the time zone of the gateway.
integer
[REQUIRED]
The minute component of the maintenance start time represented as mm , where mm is the minute (00 to 59). The minute of the hour is in the time zone of the gateway.
integer
The day of the week component of the maintenance start time week represented as an ordinal number from 0 to 6, where 0 represents Sunday and 6 Saturday.
integer
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.
Note
This value is only available for tape and volume gateways.
dict
Response Syntax
{
'GatewayARN': 'string'
}
Response Structure
(dict) --
A JSON object containing the of the gateway whose maintenance start time is updated.
GatewayARN (string) --
The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and region.