You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 3 documentation can be found here.

Class: Aws::SavingsPlans::Client

Inherits:
Seahorse::Client::Base show all
Defined in:
(unknown)

Overview

An API client for AWS Savings Plans. To construct a client, you need to configure a :region and :credentials.

savingsplans = Aws::SavingsPlans::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'] and ENV['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::SavingsPlans::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.

Attribute Summary collapse

Instance Attribute Summary

Attributes inherited from Seahorse::Client::Base

#config, #handlers

Constructor collapse

API Operations collapse

Instance Method Summary collapse

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::SavingsPlans::Client

Constructs an API client.

Options Hash (options):

  • :access_key_id (String) —

    Used to set credentials statically. See Plugins::RequestSigner for more details.

  • :active_endpoint_cache (Boolean) —

    When set to true, a thread polling for endpoints will be running in the background every 60 secs (default). Defaults to false. See Plugins::EndpointDiscovery for more details.

  • :convert_params (Boolean) — default: true —

    When true, an attempt is made to coerce request parameters into the required types. See Plugins::ParamConverter for more details.

  • :credentials (required, Credentials) —

    Your AWS credentials. The following locations will be searched in order for credentials:

    • :access_key_id, :secret_access_key, and :session_token options
    • ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY']
    • HOME/.aws/credentials shared credentials file
    • EC2 instance profile credentials See Plugins::RequestSigner for more details.
  • :disable_host_prefix_injection (Boolean) —

    Set to true to disable SDK automatically adding host prefix to default service endpoint when available. See Plugins::EndpointPattern for more details.

  • :endpoint (String) —

    A default endpoint is constructed from the :region. See Plugins::RegionalEndpoint for more details.

  • :endpoint_cache_max_entries (Integer) —

    Used for the maximum size limit of the LRU cache storing endpoints data for endpoint discovery enabled operations. Defaults to 1000. See Plugins::EndpointDiscovery for more details.

  • :endpoint_cache_max_threads (Integer) —

    Used for the maximum threads in use for polling endpoints to be cached, defaults to 10. See Plugins::EndpointDiscovery for more details.

  • :endpoint_cache_poll_interval (Integer) —

    When :endpoint_discovery and :active_endpoint_cache is enabled, Use this option to config the time interval in seconds for making requests fetching endpoints information. Defaults to 60 sec. See Plugins::EndpointDiscovery for more details.

  • :endpoint_discovery (Boolean) —

    When set to true, endpoint discovery will be enabled for operations when available. Defaults to false. See Plugins::EndpointDiscovery for more details.

  • :http_continue_timeout (Float) — default: 1 —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :http_idle_timeout (Integer) — default: 5 —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :http_open_timeout (Integer) — default: 15 —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :http_proxy (String) —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :http_read_timeout (Integer) — default: 60 —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :http_wire_trace (Boolean) — default: false —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :log_level (Symbol) — default: :info —

    The log level to send messages to the logger at. See Plugins::Logging for more details.

  • :log_formatter (Logging::LogFormatter) —

    The log formatter. Defaults to Seahorse::Client::Logging::Formatter.default. See Plugins::Logging for more details.

  • :logger (Logger) — default: nil —

    The Logger instance to send log messages to. If this option is not set, logging will be disabled. See Plugins::Logging for more details.

  • :profile (String) —

    Used when loading credentials from the shared credentials file at HOME/.aws/credentials. When not specified, 'default' is used. See Plugins::RequestSigner for more details.

  • :raise_response_errors (Boolean) — default: true —

    When true, response errors are raised. See Seahorse::Client::Plugins::RaiseResponseErrors for more details.

  • :region (required, String) —

    The AWS region to connect to. The region is used to construct the client endpoint. Defaults to ENV['AWS_REGION']. Also checks AMAZON_REGION and AWS_DEFAULT_REGION. See Plugins::RegionalEndpoint for more details.

  • :retry_limit (Integer) — default: 3 —

    The maximum number of times to retry failed requests. Only ~ 500 level server errors and certain ~ 400 level client errors are retried. Generally, these are throttling errors, data checksum errors, networking errors, timeout errors and auth errors from expired credentials. See Plugins::RetryErrors for more details.

  • :secret_access_key (String) —

    Used to set credentials statically. See Plugins::RequestSigner for more details.

  • :session_token (String) —

    Used to set credentials statically. See Plugins::RequestSigner for more details.

  • :ssl_ca_bundle (String) —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :ssl_ca_directory (String) —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :ssl_ca_store (String) —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :ssl_verify_peer (Boolean) — default: true —

    See Seahorse::Client::Plugins::NetHttp for more details.

  • :stub_responses (Boolean) — default: false —

    Causes the client to return stubbed responses. By default fake responses are generated and returned. You can specify the response data to return or errors to raise by calling ClientStubs#stub_responses. See ClientStubs for more information.

    Please note When response stubbing is enabled, no HTTP requests are made, and retries are disabled. See Plugins::StubResponses for more details.

  • :validate_params (Boolean) — default: true —

    When true, request parameters are validated before sending the request. See Plugins::ParamValidator for more details.

Instance Method Details

#create_savings_plan(options = {}) ⇒ Types::CreateSavingsPlanResponse

Creates a Savings Plan.

Examples:

Request syntax with placeholder values


resp = client.create_savings_plan({
  savings_plan_offering_id: "SavingsPlanOfferingId", # required
  commitment: "Amount", # required
  upfront_payment_amount: "Amount",
  purchase_time: Time.now,
  client_token: "ClientToken",
  tags: {
    "TagKey" => "TagValue",
  },
})

Response structure


resp.savings_plan_id #=> String

Options Hash (options):

  • :savings_plan_offering_id (required, String) —

    The ID of the offering.

  • :commitment (required, String) —

    The hourly commitment, in USD. This is a value between 0.001 and 1 million. You cannot specify more than three digits after the decimal point.

  • :upfront_payment_amount (String) —

    The up-front payment amount. This is a whole number between 50 and 99 percent of the total value of the Savings Plan. This parameter is supported only if the payment option is Partial Upfront.

  • :purchase_time (Time) —

    The time at which to purchase the Savings Plan, in UTC format (YYYY-MM-DDTHH:MM:SSZ).

  • :client_token (String) —

    This parameter will be auto-filled on your behalf with a random UUIDv4 when no value is provided. Unique, case-sensitive identifier that you provide to ensure the idempotency of the request.

  • :tags (Hash<String,String>) —

    One or more tags.

Returns:

See Also:

#delete_queued_savings_plan(options = {}) ⇒ Struct

Deletes the queued purchase for the specified Savings Plan.

Examples:

Request syntax with placeholder values


resp = client.delete_queued_savings_plan({
  savings_plan_id: "SavingsPlanId", # required
})

Options Hash (options):

  • :savings_plan_id (required, String) —

    The ID of the Savings Plan.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#describe_savings_plan_rates(options = {}) ⇒ Types::DescribeSavingsPlanRatesResponse

Describes the specified Savings Plans rates.

Examples:

Request syntax with placeholder values


resp = client.describe_savings_plan_rates({
  savings_plan_id: "SavingsPlanId", # required
  filters: [
    {
      name: "region", # accepts region, instanceType, productDescription, tenancy, productType, serviceCode, usageType, operation
      values: ["String"],
    },
  ],
  next_token: "PaginationToken",
  max_results: 1,
})

Response structure


resp.savings_plan_id #=> String
resp.search_results #=> Array
resp.search_results[0].rate #=> String
resp.search_results[0].currency #=> String, one of "CNY", "USD"
resp.search_results[0].unit #=> String, one of "Hrs", "Lambda-GB-Second", "Request"
resp.search_results[0].product_type #=> String, one of "EC2", "Fargate", "Lambda"
resp.search_results[0].service_code #=> String, one of "AmazonEC2", "AmazonECS", "AWSLambda"
resp.search_results[0].usage_type #=> String
resp.search_results[0].operation #=> String
resp.search_results[0].properties #=> Array
resp.search_results[0].properties[0].name #=> String, one of "region", "instanceType", "instanceFamily", "productDescription", "tenancy"
resp.search_results[0].properties[0].value #=> String
resp.next_token #=> String

Options Hash (options):

  • :savings_plan_id (required, String) —

    The ID of the Savings Plan.

  • :filters (Array<Types::SavingsPlanRateFilter>) —

    The filters.

  • :next_token (String) —

    The token for the next page of results.

  • :max_results (Integer) —

    The maximum number of results to return with a single call. To retrieve additional results, make another call with the returned token value.

Returns:

See Also:

#describe_savings_plans(options = {}) ⇒ Types::DescribeSavingsPlansResponse

Describes the specified Savings Plans.

Examples:

Request syntax with placeholder values


resp = client.describe_savings_plans({
  savings_plan_arns: ["SavingsPlanArn"],
  savings_plan_ids: ["SavingsPlanId"],
  next_token: "PaginationToken",
  max_results: 1,
  states: ["payment-pending"], # accepts payment-pending, payment-failed, active, retired, queued, queued-deleted
  filters: [
    {
      name: "region", # accepts region, ec2-instance-family, commitment, upfront, term, savings-plan-type, payment-option, start, end
      values: ["String"],
    },
  ],
})

Response structure


resp.savings_plans #=> Array
resp.savings_plans[0].offering_id #=> String
resp.savings_plans[0].savings_plan_id #=> String
resp.savings_plans[0].savings_plan_arn #=> String
resp.savings_plans[0].description #=> String
resp.savings_plans[0].start #=> String
resp.savings_plans[0].end #=> String
resp.savings_plans[0].state #=> String, one of "payment-pending", "payment-failed", "active", "retired", "queued", "queued-deleted"
resp.savings_plans[0].region #=> String
resp.savings_plans[0].ec2_instance_family #=> String
resp.savings_plans[0].savings_plan_type #=> String, one of "Compute", "EC2Instance"
resp.savings_plans[0].payment_option #=> String, one of "All Upfront", "Partial Upfront", "No Upfront"
resp.savings_plans[0].product_types #=> Array
resp.savings_plans[0].product_types[0] #=> String, one of "EC2", "Fargate", "Lambda"
resp.savings_plans[0].currency #=> String, one of "CNY", "USD"
resp.savings_plans[0].commitment #=> String
resp.savings_plans[0].upfront_payment_amount #=> String
resp.savings_plans[0].recurring_payment_amount #=> String
resp.savings_plans[0].term_duration_in_seconds #=> Integer
resp.savings_plans[0].tags #=> Hash
resp.savings_plans[0].tags["TagKey"] #=> String
resp.next_token #=> String

Options Hash (options):

  • :savings_plan_arns (Array<String>) —

    The Amazon Resource Names (ARN) of the Savings Plans.

  • :savings_plan_ids (Array<String>) —

    The IDs of the Savings Plans.

  • :next_token (String) —

    The token for the next page of results.

  • :max_results (Integer) —

    The maximum number of results to return with a single call. To retrieve additional results, make another call with the returned token value.

  • :states (Array<String>) —

    The states.

  • :filters (Array<Types::SavingsPlanFilter>) —

    The filters.

Returns:

See Also:

#describe_savings_plans_offering_rates(options = {}) ⇒ Types::DescribeSavingsPlansOfferingRatesResponse

Describes the specified Savings Plans offering rates.

Examples:

Request syntax with placeholder values


resp = client.describe_savings_plans_offering_rates({
  savings_plan_offering_ids: ["UUID"],
  savings_plan_payment_options: ["All Upfront"], # accepts All Upfront, Partial Upfront, No Upfront
  savings_plan_types: ["Compute"], # accepts Compute, EC2Instance
  products: ["EC2"], # accepts EC2, Fargate, Lambda
  service_codes: ["AmazonEC2"], # accepts AmazonEC2, AmazonECS, AWSLambda
  usage_types: ["SavingsPlanRateUsageType"],
  operations: ["SavingsPlanRateOperation"],
  filters: [
    {
      name: "region", # accepts region, instanceFamily, instanceType, productDescription, tenancy, productId
      values: ["JsonSafeFilterValueString"],
    },
  ],
  next_token: "PaginationToken",
  max_results: 1,
})

Response structure


resp.search_results #=> Array
resp.search_results[0].savings_plan_offering.offering_id #=> String
resp.search_results[0].savings_plan_offering.payment_option #=> String, one of "All Upfront", "Partial Upfront", "No Upfront"
resp.search_results[0].savings_plan_offering.plan_type #=> String, one of "Compute", "EC2Instance"
resp.search_results[0].savings_plan_offering.duration_seconds #=> Integer
resp.search_results[0].savings_plan_offering.currency #=> String, one of "CNY", "USD"
resp.search_results[0].savings_plan_offering.plan_description #=> String
resp.search_results[0].rate #=> String
resp.search_results[0].unit #=> String, one of "Hrs", "Lambda-GB-Second", "Request"
resp.search_results[0].product_type #=> String, one of "EC2", "Fargate", "Lambda"
resp.search_results[0].service_code #=> String, one of "AmazonEC2", "AmazonECS", "AWSLambda"
resp.search_results[0].usage_type #=> String
resp.search_results[0].operation #=> String
resp.search_results[0].properties #=> Array
resp.search_results[0].properties[0].name #=> String
resp.search_results[0].properties[0].value #=> String
resp.next_token #=> String

Options Hash (options):

  • :savings_plan_offering_ids (Array<String>) —

    The IDs of the offerings.

  • :savings_plan_payment_options (Array<String>) —

    The payment options.

  • :savings_plan_types (Array<String>) —

    The plan types.

  • :products (Array<String>) —

    The AWS products.

  • :service_codes (Array<String>) —

    The services.

  • :usage_types (Array<String>) —

    The usage details of the line item in the billing report.

  • :operations (Array<String>) —

    The specific AWS operation for the line item in the billing report.

  • :filters (Array<Types::SavingsPlanOfferingRateFilterElement>) —

    The filters.

  • :next_token (String) —

    The token for the next page of results.

  • :max_results (Integer) —

    The maximum number of results to return with a single call. To retrieve additional results, make another call with the returned token value.

Returns:

See Also:

#describe_savings_plans_offerings(options = {}) ⇒ Types::DescribeSavingsPlansOfferingsResponse

Describes the specified Savings Plans offerings.

Examples:

Request syntax with placeholder values


resp = client.describe_savings_plans_offerings({
  offering_ids: ["UUID"],
  payment_options: ["All Upfront"], # accepts All Upfront, Partial Upfront, No Upfront
  product_type: "EC2", # accepts EC2, Fargate, Lambda
  plan_types: ["Compute"], # accepts Compute, EC2Instance
  durations: [1],
  currencies: ["CNY"], # accepts CNY, USD
  descriptions: ["SavingsPlanDescription"],
  service_codes: ["SavingsPlanServiceCode"],
  usage_types: ["SavingsPlanUsageType"],
  operations: ["SavingsPlanOperation"],
  filters: [
    {
      name: "region", # accepts region, instanceFamily
      values: ["JsonSafeFilterValueString"],
    },
  ],
  next_token: "PaginationToken",
  max_results: 1,
})

Response structure


resp.search_results #=> Array
resp.search_results[0].offering_id #=> String
resp.search_results[0].product_types #=> Array
resp.search_results[0].product_types[0] #=> String, one of "EC2", "Fargate", "Lambda"
resp.search_results[0].plan_type #=> String, one of "Compute", "EC2Instance"
resp.search_results[0].description #=> String
resp.search_results[0].payment_option #=> String, one of "All Upfront", "Partial Upfront", "No Upfront"
resp.search_results[0].duration_seconds #=> Integer
resp.search_results[0].currency #=> String, one of "CNY", "USD"
resp.search_results[0].service_code #=> String
resp.search_results[0].usage_type #=> String
resp.search_results[0].operation #=> String
resp.search_results[0].properties #=> Array
resp.search_results[0].properties[0].name #=> String, one of "region", "instanceFamily"
resp.search_results[0].properties[0].value #=> String
resp.next_token #=> String

Options Hash (options):

  • :offering_ids (Array<String>) —

    The IDs of the offerings.

  • :payment_options (Array<String>) —

    The payment options.

  • :product_type (String) —

    The product type.

  • :plan_types (Array<String>) —

    The plan type.

  • :durations (Array<Integer>) —

    The durations, in seconds.

  • :currencies (Array<String>) —

    The currencies.

  • :descriptions (Array<String>) —

    The descriptions.

  • :service_codes (Array<String>) —

    The services.

  • :usage_types (Array<String>) —

    The usage details of the line item in the billing report.

  • :operations (Array<String>) —

    The specific AWS operation for the line item in the billing report.

  • :filters (Array<Types::SavingsPlanOfferingFilterElement>) —

    The filters.

  • :next_token (String) —

    The token for the next page of results.

  • :max_results (Integer) —

    The maximum number of results to return with a single call. To retrieve additional results, make another call with the returned token value.

Returns:

See Also:

#list_tags_for_resource(options = {}) ⇒ Types::ListTagsForResourceResponse

Lists the tags for the specified resource.

Examples:

Request syntax with placeholder values


resp = client.list_tags_for_resource({
  resource_arn: "SavingsPlanArn", # required
})

Response structure


resp.tags #=> Hash
resp.tags["TagKey"] #=> String

Options Hash (options):

  • :resource_arn (required, String) —

    The Amazon Resource Name (ARN) of the resource.

Returns:

See Also:

#tag_resource(options = {}) ⇒ Struct

Adds the specified tags to the specified resource.

Examples:

Request syntax with placeholder values


resp = client.tag_resource({
  resource_arn: "SavingsPlanArn", # required
  tags: { # required
    "TagKey" => "TagValue",
  },
})

Options Hash (options):

  • :resource_arn (required, String) —

    The Amazon Resource Name (ARN) of the resource.

  • :tags (required, Hash<String,String>) —

    One or more tags. For example, { \"tags\": \"key2\":\"value2\" }.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#untag_resource(options = {}) ⇒ Struct

Removes the specified tags from the specified resource.

Examples:

Request syntax with placeholder values


resp = client.untag_resource({
  resource_arn: "SavingsPlanArn", # required
  tag_keys: ["TagKey"], # required
})

Options Hash (options):

  • :resource_arn (required, String) —

    The Amazon Resource Name (ARN) of the resource.

  • :tag_keys (required, Array<String>) —

    The tag keys.

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#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

Parameters:

  • waiter_name (Symbol) —

    The name of the waiter. See #waiter_names for a full list of supported waiters.

  • params (Hash) (defaults to: {}) —

    Additional request parameters. See the #waiter_names for a list of supported waiters and what request they call. The called request determines the list of accepted parameters.

Yield Parameters:

Returns:

  • (Boolean) —

    Returns true if the waiter was successful.

Raises:

  • (Errors::FailureStateError) —

    Raised when the waiter terminates because the waiter has entered a state that it will not transition out of, preventing success.

  • (Errors::TooManyAttemptsError) —

    Raised when the configured maximum number of attempts have been made, and the waiter is not yet successful.

  • (Errors::UnexpectedError) —

    Raised when an error is encounted while polling for a resource that is not expected.

  • (Errors::NoSuchWaiterError) —

    Raised when you request to wait for an unknown state.

#waiter_names ⇒ Array<Symbol>

Returns the list of supported waiters. The following table lists the supported waiters and the client method they call:

Waiter NameClient MethodDefault Delay:Default Max Attempts:

Returns:

  • (Array<Symbol>) —

    the list of supported waiters.