Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Waiter

Waiter 是实用程序方法，用于轮询客户端上出现的特定状态。按为服务客户端定义的轮询间隔尝试多次后，Waiter 可能会失败。有关如何使用 Waiter 的示例，请参阅 Amazon 代码示例存储库中的 Amazon DynamoDB Encryption Client 的 create_table 方法。

调用 Waiter

要调用 Waiter，请在服务客户端上调用 wait_until。在以下示例中，Waiter 一直等到实例 i-12345678 运行后才继续。

ec2 = Aws::EC2::Client.new

begin
  ec2.wait_until(:instance_running, instance_ids:['i-12345678'])
  puts "instance running"
rescue Aws::Waiters::Errors::WaiterFailed => error
  puts "failed waiting for instance running: #{error.message}"
end

第一个参数是 Waiter 名称，这特定于服务客户端并指示正在等待哪个操作。第二个参数是传递给 Waiter 所调用的客户端方法的参数的哈希，这因 Waiter 名称而异。

有关可等待的操作和为每个操作调用的客户端方法的列表，请参阅您所使用的客户端的 waiter_names 和 wait_until 域文档。

等待失败

Waiter 可能会失败并出现以下任何异常。

除 NoSuchWaiterError 以外的所有其他错误都基于 WaiterFailed。要捕获 Waiter 中的错误，请使用 WaiterFailed，如以下示例所示。

rescue Aws::Waiters::Errors::WaiterFailed => error
  puts "failed waiting for instance running: #{error.message}"
end

配置 Waiter

每个 Waiter 都具有默认轮询间隔和它在将控制权返还给您的程序之前将进行尝试的最大次数。要设置这些值，请在您的 max_attempts 调用中使用 delay: 和 wait_until 参数。以下示例最多等待 25 秒，每隔 5 秒轮询一次。

# Poll for ~25 seconds
client.wait_until(...) do |w|
  w.max_attempts = 5
  w.delay = 5
end

要禁用等待失败，请将其中任一个参数的值设置为 nil。

扩展 Waiter

要修改 Waiter 的行为，您可以注册在每个轮询尝试之前和等待之前触发的回调。

以下示例通过使每次尝试后的等待时间长度翻倍，在 Waiter 中实现指数回退。

ec2 = Aws::EC2::Client.new

ec2.wait_until(:instance_running, instance_ids:['i-12345678']) do |w|
  w.interval = 0 # disable normal sleep
  w.before_wait do |n, resp|
    sleep(n ** 2)
  end
end

以下示例禁用了最大尝试次数，而在失败前等待 1 小时（3600 秒）。

started_at = Time.now
client.wait_until(...) do |w|
  # Disable max attempts
  w.max_attempts = nil

  # Poll for one hour, instead of a number of attempts
  w.before_wait do |attempts, response|
    throw :failure if Time.now - started_at > 3600
  end
end