You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 3 documentation can be found here.
Class: Aws::Snowball::Client
- Inherits:
-
Seahorse::Client::Base
- Object
- Seahorse::Client::Base
- Aws::Snowball::Client
- Defined in:
- (unknown)
Overview
An API client for Amazon Import/Export Snowball. To construct a client, you need to configure a :region
and :credentials
.
snowball = Aws::Snowball::Client.new(
region: region_name,
credentials: credentials,
# ...
)
See #initialize for a full list of supported configuration options.
Region
You can configure a default region in the following locations:
ENV['AWS_REGION']
Aws.config[:region]
Go here for a list of supported regions.
Credentials
Default credentials are loaded automatically from the following locations:
ENV['AWS_ACCESS_KEY_ID']
andENV['AWS_SECRET_ACCESS_KEY']
Aws.config[:credentials]
- The shared credentials ini file at
~/.aws/credentials
(more information) - From an instance profile when running on EC2
You can also construct a credentials object from one of the following classes:
Alternatively, you configure credentials with :access_key_id
and
:secret_access_key
:
# load credentials from disk
creds = YAML.load(File.read('/path/to/secrets'))
Aws::Snowball::Client.new(
access_key_id: creds['access_key_id'],
secret_access_key: creds['secret_access_key']
)
Always load your credentials from outside your application. Avoid configuring credentials statically and never commit them to source control.
Instance Attribute Summary
Attributes inherited from Seahorse::Client::Base
Constructor collapse
-
#initialize(options = {}) ⇒ Aws::Snowball::Client
constructor
Constructs an API client.
API Operations collapse
-
#cancel_cluster(options = {}) ⇒ Struct
Cancels a cluster job.
-
#cancel_job(options = {}) ⇒ Struct
Cancels the specified job.
-
#create_address(options = {}) ⇒ Types::CreateAddressResult
Creates an address for a Snow device to be shipped to.
-
#create_cluster(options = {}) ⇒ Types::CreateClusterResult
Creates an empty cluster.
-
#create_job(options = {}) ⇒ Types::CreateJobResult
Creates a job to import or export data between Amazon S3 and your on-premises data center.
-
#create_return_shipping_label(options = {}) ⇒ Types::CreateReturnShippingLabelResult
Creates a shipping label that will be used to return the Snow device to AWS.
.
-
#describe_address(options = {}) ⇒ Types::DescribeAddressResult
Takes an
AddressId
and returns specific details about that address in the form of anAddress
object..
-
#describe_addresses(options = {}) ⇒ Types::DescribeAddressesResult
Returns a specified number of
ADDRESS
objects. -
#describe_cluster(options = {}) ⇒ Types::DescribeClusterResult
Returns information about a specific cluster including shipping information, cluster status, and other important metadata.
.
-
#describe_job(options = {}) ⇒ Types::DescribeJobResult
Returns information about a specific job including shipping information, job status, and other important metadata.
-
#describe_return_shipping_label(options = {}) ⇒ Types::DescribeReturnShippingLabelResult
Information on the shipping label of a Snow device that is being returned to AWS.
.
-
#get_job_manifest(options = {}) ⇒ Types::GetJobManifestResult
Returns a link to an Amazon S3 presigned URL for the manifest file associated with the specified
JobId
value. -
#get_job_unlock_code(options = {}) ⇒ Types::GetJobUnlockCodeResult
Returns the
UnlockCode
code value for the specified job. -
#get_snowball_usage(options = {}) ⇒ Types::GetSnowballUsageResult
Returns information about the Snow Family service limit for your account, and also the number of Snow devices your account has in use.
The default service limit for the number of Snow devices that you can have at one time is 1.
-
#get_software_updates(options = {}) ⇒ Types::GetSoftwareUpdatesResult
Returns an Amazon S3 presigned URL for an update file associated with a specified
JobId
..
-
#list_cluster_jobs(options = {}) ⇒ Types::ListClusterJobsResult
Returns an array of
JobListEntry
objects of the specified length. -
#list_clusters(options = {}) ⇒ Types::ListClustersResult
Returns an array of
ClusterListEntry
objects of the specified length. -
#list_compatible_images(options = {}) ⇒ Types::ListCompatibleImagesResult
This action returns a list of the different Amazon EC2 Amazon Machine Images (AMIs) that are owned by your AWS account that would be supported for use on a Snow device.
-
#list_jobs(options = {}) ⇒ Types::ListJobsResult
Returns an array of
JobListEntry
objects of the specified length. -
#update_cluster(options = {}) ⇒ Struct
While a cluster's
ClusterState
value is in theAwaitingQuorum
state, you can update some of the information associated with a cluster. -
#update_job(options = {}) ⇒ Struct
While a job's
JobState
value isNew
, you can update some of the information associated with a job. -
#update_job_shipment_state(options = {}) ⇒ Struct
Updates the state when a the shipment states changes to a different state.
.
Instance Method Summary collapse
-
#wait_until(waiter_name, params = {}) {|waiter| ... } ⇒ Boolean
Waiters polls an API operation until a resource enters a desired state.
-
#waiter_names ⇒ Array<Symbol>
Returns the list of supported waiters.
Methods inherited from Seahorse::Client::Base
add_plugin, api, #build_request, clear_plugins, define, new, #operation, #operation_names, plugins, remove_plugin, set_api, set_plugins
Methods included from Seahorse::Client::HandlerBuilder
#handle, #handle_request, #handle_response
Constructor Details
#initialize(options = {}) ⇒ Aws::Snowball::Client
Constructs an API client.
Instance Method Details
#cancel_cluster(options = {}) ⇒ Struct
Cancels a cluster job. You can only cancel a cluster job while it's in the AwaitingQuorum
status. You'll have at least an hour after creating a cluster job to cancel it.
#cancel_job(options = {}) ⇒ Struct
Cancels the specified job. You can only cancel a job before its JobState
value changes to PreparingAppliance
. Requesting the ListJobs
or DescribeJob
action returns a job's JobState
as part of the response element data returned.
#create_address(options = {}) ⇒ Types::CreateAddressResult
Creates an address for a Snow device to be shipped to. In most regions, addresses are validated at the time of creation. The address you provide must be located within the serviceable area of your region. If the address is invalid or unsupported, then an exception is thrown.
#create_cluster(options = {}) ⇒ Types::CreateClusterResult
Creates an empty cluster. Each cluster supports five nodes. You use the CreateJob action separately to create the jobs for each of these nodes. The cluster does not ship until these five node jobs have been created.
#create_job(options = {}) ⇒ Types::CreateJobResult
Creates a job to import or export data between Amazon S3 and your on-premises data center. Your AWS account must have the right trust policies and permissions in place to create a job for a Snow device. If you're creating a job for a node in a cluster, you only need to provide the clusterId
value; the other job attributes are inherited from the cluster.
#create_return_shipping_label(options = {}) ⇒ Types::CreateReturnShippingLabelResult
Creates a shipping label that will be used to return the Snow device to AWS.
#describe_address(options = {}) ⇒ Types::DescribeAddressResult
Takes an AddressId
and returns specific details about that address in the form of an Address
object.
#describe_addresses(options = {}) ⇒ Types::DescribeAddressesResult
Returns a specified number of ADDRESS
objects. Calling this API in one of the US regions will return addresses from the list of all addresses associated with this account in all US regions.
#describe_cluster(options = {}) ⇒ Types::DescribeClusterResult
Returns information about a specific cluster including shipping information, cluster status, and other important metadata.
#describe_job(options = {}) ⇒ Types::DescribeJobResult
Returns information about a specific job including shipping information, job status, and other important metadata.
#describe_return_shipping_label(options = {}) ⇒ Types::DescribeReturnShippingLabelResult
Information on the shipping label of a Snow device that is being returned to AWS.
#get_job_manifest(options = {}) ⇒ Types::GetJobManifestResult
Returns a link to an Amazon S3 presigned URL for the manifest file associated with the specified JobId
value. You can access the manifest file for up to 60 minutes after this request has been made. To access the manifest file after 60 minutes have passed, you'll have to make another call to the GetJobManifest
action.
The manifest is an encrypted file that you can download after your job enters the WithCustomer
status. The manifest is decrypted by using the UnlockCode
code value, when you pass both values to the Snow device through the Snowball client when the client is started for the first time.
As a best practice, we recommend that you don't save a copy of an UnlockCode
value in the same location as the manifest file for that job. Saving these separately helps prevent unauthorized parties from gaining access to the Snow device associated with that job.
The credentials of a given job, including its manifest file and unlock code, expire 90 days after the job is created.
#get_job_unlock_code(options = {}) ⇒ Types::GetJobUnlockCodeResult
Returns the UnlockCode
code value for the specified job. A particular UnlockCode
value can be accessed for up to 90 days after the associated job has been created.
The UnlockCode
value is a 29-character code with 25 alphanumeric characters and 4 hyphens. This code is used to decrypt the manifest file when it is passed along with the manifest to the Snow device through the Snowball client when the client is started for the first time.
As a best practice, we recommend that you don't save a copy of the UnlockCode
in the same location as the manifest file for that job. Saving these separately helps prevent unauthorized parties from gaining access to the Snow device associated with that job.
#get_snowball_usage(options = {}) ⇒ Types::GetSnowballUsageResult
Returns information about the Snow Family service limit for your account, and also the number of Snow devices your account has in use.
The default service limit for the number of Snow devices that you can have at one time is 1. If you want to increase your service limit, contact AWS Support.
#get_software_updates(options = {}) ⇒ Types::GetSoftwareUpdatesResult
Returns an Amazon S3 presigned URL for an update file associated with a specified JobId
.
#list_cluster_jobs(options = {}) ⇒ Types::ListClusterJobsResult
Returns an array of JobListEntry
objects of the specified length. Each JobListEntry
object is for a job in the specified cluster and contains a job's state, a job's ID, and other information.
#list_clusters(options = {}) ⇒ Types::ListClustersResult
Returns an array of ClusterListEntry
objects of the specified length. Each ClusterListEntry
object contains a cluster's state, a cluster's ID, and other important status information.
#list_compatible_images(options = {}) ⇒ Types::ListCompatibleImagesResult
This action returns a list of the different Amazon EC2 Amazon Machine Images (AMIs) that are owned by your AWS account that would be supported for use on a Snow device. Currently, supported AMIs are based on the CentOS 7 (x86_64) - with Updates HVM, Ubuntu Server 14.04 LTS (HVM), and Ubuntu 16.04 LTS - Xenial (HVM) images, available on the AWS Marketplace.
#list_jobs(options = {}) ⇒ Types::ListJobsResult
Returns an array of JobListEntry
objects of the specified length. Each JobListEntry
object contains a job's state, a job's ID, and a value that indicates whether the job is a job part, in the case of export jobs. Calling this API action in one of the US regions will return jobs from the list of all jobs associated with this account in all US regions.
#update_cluster(options = {}) ⇒ Struct
While a cluster's ClusterState
value is in the AwaitingQuorum
state, you can update some of the information associated with a cluster. Once the cluster changes to a different job state, usually 60 minutes after the cluster being created, this action is no longer available.
#update_job(options = {}) ⇒ Struct
While a job's JobState
value is New
, you can update some of the information associated with a job. Once the job changes to a different job state, usually within 60 minutes of the job being created, this action is no longer available.
#update_job_shipment_state(options = {}) ⇒ Struct
Updates the state when a the shipment states changes to a different state.
#wait_until(waiter_name, params = {}) {|waiter| ... } ⇒ Boolean
Waiters polls an API operation until a resource enters a desired state.
Basic Usage
Waiters will poll until they are succesful, they fail by entering a terminal state, or until a maximum number of attempts are made.
# polls in a loop, sleeping between attempts client.waiter_until(waiter_name, params)
Configuration
You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. You configure waiters by passing a block to #wait_until:
# poll for ~25 seconds
client.wait_until(...) do |w|
w.max_attempts = 5
w.delay = 5
end
Callbacks
You can be notified before each polling attempt and before each
delay. If you throw :success
or :failure
from these callbacks,
it will terminate the waiter.
started_at = Time.now
client.wait_until(...) do |w|
# disable max attempts
w.max_attempts = nil
# poll for 1 hour, instead of a number of attempts
w.before_wait do |attempts, response|
throw :failure if Time.now - started_at > 3600
end
end
Handling Errors
When a waiter is successful, it returns true
. When a waiter
fails, it raises an error. All errors raised extend from
Waiters::Errors::WaiterFailed.
begin
client.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
# resource did not enter the desired state in time
end
#waiter_names ⇒ Array<Symbol>
Returns the list of supported waiters. The following table lists the supported waiters and the client method they call:
Waiter Name | Client Method | Default Delay: | Default Max Attempts: |
---|