Vonage Ruby 服务器 SDK

这是 Vonage API 的 Ruby 服务器 SDK。要使用它，您需要一个 Vonage 账户。在 vonage.com 免费注册。

• 要求
• 安装
• 使用
  • 日志记录
  • 异常
  • 覆盖默认主机
  • JWT 认证
  • Webhook 签名
  • 分页
  • 消息 API
  • Verify API v2
  • 语音 API
    • NCCO 构建器
• 文档
• 支持的 API
• 其他 SDK 和工具
• 许可证
• 贡献

要求

Vonage Ruby 支持 MRI/CRuby（2.5 或更新版本）、JRuby（9.2.x）和 Truffleruby。

安装

使用 Rubygems 安装 Ruby 服务器 SDK：

gem install vonage

或者您可以克隆存储库：

git clone git@github.com:Vonage/vonage-ruby-sdk.git

使用

首先引入 Vonage 库：

require 'vonage'

然后使用您的密钥和密码构造一个客户端对象：

client = Vonage::Client.new(api_key: 'YOUR-API-KEY', api_secret: 'YOUR-API-SECRET')

现在您可以使用客户端对象调用 Vonage API。例如，发送短信：

client.sms.send(from: 'Ruby', to: '447700900000', text: 'Hello world')

在生产环境中，您可以指定 VONAGE_API_KEY 和 VONAGE_API_SECRET 环境变量，而不是显式指定密钥和密码，以保护您的凭据不被纳入源代码控制。

对于使用 JWT 进行认证的 API，您还需要向 Client 构造函数传递 application_id 和 private_key 参数，除了或替代 api_key 和 api_secret。请参阅 JWT 认证。

也可以在 Client 实例化时覆盖默认主机。请参阅 覆盖默认主机。

JWT 认证

要调用支持 JWT 认证的较新端点，如语音 API 和消息 API，您还需要指定 application_id 和 private_key 选项。例如：

client = Vonage::Client.new(application_id: application_id, private_key: private_key)

这两个参数的值应为字符串，对应于"创建应用程序"响应中返回的 id 和 private_key 值。这些凭据可以存储在数据库中、环境变量中、源代码控制之外的磁盘上，或某种密钥管理基础设施中。

默认情况下，库为每个请求生成一个短期 JWT。要生成用于多个请求的长期 JWT 或直接指定 JWT 声明，请使用 Vonage::JWT.generate 和 token 选项。例如：

claims = {
  application_id: application_id,
  private_key: 'path/to/private.key',
  nbf: 1483315200,
  ttl: 800
}

token = Vonage::JWT.generate(claims)

client = Vonage::Client.new(token: token)

Vonage Ruby JWT 生成器 gem 的文档可以在这里找到：https://www.rubydoc.info/gems/vonage-jwt

该文档概述了所有可用于自定义和构建令牌的可能参数。

日志记录

使用 logger 选项指定记录器。例如：

require 'logger'

logger = Logger.new(STDOUT)

client = Vonage::Client.new(logger: logger)

默认情况下，如果定义了 Rails.logger，库会将记录器设置为它。

要禁用日志记录，将记录器设置为 nil。

异常

当异常由 Vonage API 的错误响应引起时（HTTP 响应不在 2xx 或 3xx 范围内），Net::HTTPResponse 对象将作为 Exception 对象的属性通过 http_response getter 方法可用（如果没有与异常相关的 Net::HTTPResponse 对象，http_response 的值将为 nil）。

您可以捕获异常以访问 http_response，并使用为响应特定部分提供的其他 getter。例如：

begin
  verification_request = client.verify2.start_verification(
    brand: 'Acme',
    workflow: [{channel: 'sms', to: '44700000000'}]
  )
rescue Vonage::APIError => error
  if error.http_response
    error.http_response # => #<Net::HTTPUnauthorized 401 Unauthorized readbody=true>
    error.http_response_code # => "401"
    error.http_response_headers # => {"date"=>["Sun, 24 Sep 2023 11:08:47 GMT"], ...其余头部}
    error.http_response_body # => {"title"=>"Unauthorized", ...其余正文}
  end
end

对于某些旧版 API 产品，如 SMS API、Verify v1 API 和 Number Insight v1 API，即使在存在 API 相关错误的情况下也会收到 200 响应。对于在这些情况下引发的异常，Vonage::Response 对象（而不是 Net::HTTPResponse 对象）将作为异常的属性通过 response getter 方法可用。此对象的属性将取决于 API 端点提供的响应数据。例如：

begin
  sms = client.sms.send(
    from: 'Vonage',
    to: '44700000000',
    text: 'Hello World!'
  )
rescue Vonage::Error => error
  if error.is_a? Vonage::ServiceError
    error.response # => #<Vonage::Response:0x0000555b2e49d4f8>
    error.response.messages.first.status # => "4"
    error.response.messages.first.error_text # => "Bad Credentials"
    error.response.http_response # => #<Net::HTTPOK 200 OK readbody=true>
  end
end

覆盖默认主机

要覆盖SDK用于HTTP请求的默认主机，你需要在客户端配置中指定api_host、rest_host或两者。例如：

client = Vonage::Client.new(
  api_host: 'api-sg-1.nexmo.com',
  rest_host: 'rest-sg-1.nexmo.com'
)

默认情况下，主机分别设置为api.nexmo.com和rest.nexmo.com。

Webhook签名

某些Vonage API提供签名webhooks作为验证webhooks来源的方法。具体的签名机制因API而异。

请求体中的签名

SMS API使用哈希摘要对webhook请求进行签名。这被分配给请求体中的sig参数。

你可以使用Vonage::SMS#verify_webhook_sig方法验证webhook请求。除了接收到的webhook的请求参数外，该方法还需要访问与Vonage帐户关联的签名密钥（可从Vonage仪表板获得），以及用于签名的签名方法（例如sha512），这同样基于仪表板中的设置。

有几种不同的方法可以向该方法提供这些值：

1. 将所有值传递给方法调用。

client = Vonage::Client.new

client.sms.verify_webhook_sig(
  webhook_params: params,
  signature_secret: 'secret',
  signature_method: 'sha512'
) # => 如果签名有效则返回true，否则返回false

2. 在Client实例化时设置signature_secret和signature_method。

client = Vonage::Client.new(
  signature_secret: 'secret',
  signature_method: 'sha512'
)

client.sms.verify_webhook_sig(webhook_params: params) # => 如果签名有效则返回true，否则返回false

3. 在Config对象上设置signature_secret和signature_method。

client = Vonage::Client.new
client.config.signature_secret = 'secret'
client.config.signature_method = 'sha512'

client.sms.verify_webhook_sig(webhook_params: params) # => 如果签名有效则返回true，否则返回false

4. 将signature_secret和signature_method设置为名为VONAGE_SIGNATURE_SECRET和VONAGE_SIGNATURE_METHOD的环境变量

client = Vonage::Client.new

client.sms.verify_webhook_sig(webhook_params: params) # => 如果签名有效则返回true，否则返回false

注意： SMS API的webhook签名默认情况下未开启。你需要联系support@vonage.com以在你的帐户上启用消息签名。

头部中的签名JWT

Voice API和Messages API都在其webhook请求中包含一个Authorization头。该头的值包括一个使用与你的Vonage帐户关联的签名密钥签名的JSON Web Token (JWT)。

Vonage::Voice和Vonage::Messaging类都定义了一个verify_webhook_token方法，可用于验证在webhook Authorization头中接收到的JWT。

要验证JWT，你首先需要从Authorization头中提取它。头的值看起来类似于以下内容：

"Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1OTUyN" # 为简洁起见，省略了令牌的其余部分

注意：我们只对令牌本身感兴趣，它在单词Bearer和空格之后。

一旦你提取了令牌，你可以将其传递给verify_webhook_token方法以验证它。

该方法还需要访问与Vonage帐户关联的签名密钥（可从Vonage仪表板获得）。有几种不同的方法可以向该方法提供这个值：

1. 将所有值传递给方法调用。

client = Vonage::Client.new

client.voice.verify_webhook_token(
  token: extracted_token,
  signature_secret: 'secret'
) # => 如果令牌有效则返回true，否则返回false

2. 在Client实例化时设置signature_secret。

client = Vonage::Client.new(
  signature_secret: 'secret'
)

client.voice.verify_webhook_token(token: extracted_token) # => 如果令牌有效则返回true，否则返回false

3. 在Config对象上设置signature_secret。

client = Vonage::Client.new
client.config.signature_secret = 'secret'
client.config.signature_method = 'sha512'

client.voice.verify_webhook_token(token: extracted_token) # => 如果令牌有效则返回true，否则返回false

4. 将signature_secret设置为名为VONAGE_SIGNATURE_SECRET的环境变量

client = Vonage::Client.new

client.voice.verify_webhook_token(token: extracted_token) # => 如果令牌有效则返回true，否则返回false

分页

Vonage API对列表请求进行分页。这意味着如果请求的集合大于API默认值，API将返回集合中的第一页项目。Ruby SDK提供了一个auto_advance参数，它将遍历所有页面并在一个响应对象中返回所有结果。

以下API的auto_advance参数默认设置为true：

• Account API
• Application API
• Conversation API
• Voice API

要修改auto_advance行为，你可以在方法中指定它：

client.applications.list(auto_advance: false)

Messages API

Vonage Messages API允许你通过多个不同的渠道发送消息，以及每个渠道内的各种消息类型。请查看Vonage开发者文档以获取列出所有渠道和消息类型组合的完整API参考。 Ruby SDK 允许您为特定的消息渠道构建消息数据。除了短信（只有一种类型 -- 文本）之外，您需要将消息的:type以及:message本身作为参数传递给相应的消息方法，同时还可以根据需要传递任何可选属性。

# 创建短信消息
message = Vonage::Messaging::Message.sms(message: 'Hello world!')

# 创建 WhatsApp 文本消息
message = Vonage::Messaging::Message.whatsapp(type: 'text', message: 'Hello world!')

# 创建 WhatsApp 图片消息
message = Vonage::Messaging::Message.whatsapp(type: 'image', message: { url: 'https://example.com/image.jpg' })

# 创建带有可选属性的 MMS 音频消息
message = Vonage::Messaging::Message.mms(type: 'audio', message: { url: 'https://example.com/audio.mp3' }, opts: {client_ref: "abc123"})

一旦创建了消息数据，您就可以发送该消息。

response = client.messaging.send(to: "447700900000", from: "447700900001", **message)

Verify API v2

Vonage Verify API v2 允许您通过多种不同的渠道（如短信、WhatsApp、WhatsApp 交互式、语音、电子邮件和静默认证）管理双因素认证验证流程，可以单独使用或组合使用这些渠道。请参阅 Vonage 开发者文档以获取完整的 API 参考，其中列出了所有的渠道、验证选项和回调类型。

Ruby SDK 提供了两种与 Verify v2 API 交互的方法：

• Verify2#start_verification：启动新的验证请求。在这里，您可以为请求指定选项和要使用的工作流程。
• Verify2#check_code：对于向最终用户发送一次性代码的渠道，此方法用于根据由 start_verification 方法创建的验证请求的 request_id 验证代码。

创建 Verify2 对象

verify = client.verify2

发起验证请求

对于简单的请求，您可能更喜欢手动设置 workflow 的值（一个或多个包含特定渠道设置的哈希数组）和任何可选参数。

带有必需的 :brand 和 :workflow 参数的示例：

verification_request = verify.start_verification(
  brand: 'Acme',
  workflow: [{channel: 'sms', to: '447000000000'}]
)

带有必需的 :brand 和 :workflow 参数，以及可选的 code_length 的示例：

verification_request = verify.start_verification(
  brand: 'Acme',
  workflow: [{channel: 'sms', to: '447000000000'}],
  code_length: 6
)

对于更复杂的请求（例如具有多个工作流程渠道或额外选项），或者要利用内置的输入验证，您可以使用 StartVerificationOptions 对象以及 Workflow 和各种渠道对象或 WorkflowBuilder：

使用 StartVerificationOptions 对象创建选项

opts = verify.start_verification_options(
  locale: 'fr-fr',
  code_length: 6,
  client_ref: 'abc-123'
).to_h

verification_request = verify.start_verification(
  brand: 'Acme',
  workflow: [{channel: 'email', to: 'alice.example.com'}],
  **opts
)

使用 Workflow 和 Channel 对象创建工作流程

# 实例化一个 Workflow 对象
workflow = verify.workflow

# 向工作流程添加渠道
workflow << workflow.sms(to: '447000000000')
workflow << workflow.email(to: 'alice.example.com')

# 渠道数据被封装在存储在 Workflow 列表数组中的渠道对象中
workflow.list
# => [ #<Vonage::Verify2::Channels::SMS:0x0000561474a74778 @channel="sms", @to="447000000000">,
  #<Vonage::Verify2::Channels::Email:0x0000561474c51a28 @channel="email", @to="alice.example.com">]

# 要在 `start_verification` 请求调用中将列表用作 `:workflow` 的值，
# 必须将对象转换为哈希形式
workflow_list = workflow.hashified_list
# => [{:channel=>"sms", :to=>"447000000000"}, {:channel=>"email", :to=>"alice.example.com"}]

verification_request = verify.start_verification(brand: 'Acme', workflow: workflow_list)

使用 WorkflowBuilder 创建工作流程

workflow = verify.workflow_builder.build do |builder|
  builder.add_voice(to: '447000000001')
  builder.add_whatsapp(to: '447000000000')
end

workflow_list = workflow.hashified_list
# => [{:channel=>"voice", :to=>"447000000001"}, {:channel=>"whatsapp", :to=>"447000000000"}]

verification_request = verify.start_verification(brand: 'Acme', workflow: workflow_list)

取消请求

您可以取消正在进行的验证请求

# 从 `start_verification` 方法调用返回的 Vonage#Response 对象中获取 `request_id`
request_id = verification_request.request_id

verify.cancel_verification_request(request_id: request_id)

检查代码

# 从 `start_verification` 方法调用返回的 Vonage#Response 对象中获取 `request_id`
request_id = verification_request.request_id

# 通过用户输入获取一次性代码
# 例如，从表单输入的路由处理程序或控制器操作的参数中获取
code = params[:code]

begin
  code_check = verify.check_code(request_id: request_id, code: code)
rescue => error
  # 无效的代码将引发 Vonage::ClientError 类型的异常
end

if code_check.http_response.code == '200'
  # 代码有效
end

Voice API

Vonage Voice API 允许您通过创建通话、流式传输音频、播放文字转语音、播放 DTMF 音调和其他操作来自动化语音交互。请参阅 Vonage 开发者文档以获取完整的 API 参考，其中列出了所有 Voice API 的功能。

Ruby SDK 提供了多种与 Voice v2 API 交互的方法。以下是使用 create 方法进行外呼文字转语音通话的示例：

response = client.voice.create(
  to: [{
    type: 'phone',
    number: '447700900000'
  }],
  from: {
    type: 'phone',
    number: '447700900001'
  },
  answer_url: [
    'https://raw.githubusercontent.com/nexmo-community/ncco-examples/gh-pages/text-to-speech.json'
  ]
)

NCCO 构建器

Vonage语音API通过称为NCCO的JSON对象接受指令。每个NCCO可以由多个按书写顺序执行的操作组成。Vonage API开发者门户包含一个NCCO参考，其中提供了所有可能参数的说明和信息。

SDK包含一个NCCO构建器，您可以用它为您的语音API方法构建NCCO。

例如，要构建talk和input NCCO操作，然后将它们合并为单个NCCO，您可以执行以下操作：

talk = Vonage::Voice::Ncco.talk(text: 'Hello World!')
input = Vonage::Voice::Ncco.input(type: ['dtmf'], dtmf: { bargeIn: true })
ncco = Vonage::Voice::Ncco.build(talk, input)

# => [{:action=>"talk", :text=>"Hello World!"}, {:action=>"input", :type=>["dtmf"], :dtmf=>{:bargeIn=>true}}]

构建好NCCO后，您可以在语音API请求中使用它：

response = client.voice.create({
  to: [{type: 'phone', number: '14843331234'}],
  from: {type: 'phone', number: '14843335555'},
  ncco: ncco
})

文档

Vonage Ruby SDK文档：https://www.rubydoc.info/gems/vonage

Vonage Ruby SDK代码示例：https://github.com/Vonage/vonage-ruby-code-snippets

Vonage APIs API参考：https://developer.vonage.com/api

支持的API

以下是Ruby SDK当前支持的Vonage API列表：

• 账户API
• 应用API
• 对话API
• 会议API
• 消息API
• 网络号码验证API
• 网络SIM卡交换API
• 号码洞察API
• 号码API
• 主动连接API *
• 编辑API
• 短信API
• 子账户API
• 验证API
• 语音API

* SDK部分支持主动连接API。具体来说，支持事件、项目和列表端点。

其他SDK和工具

您可以在我们的开发者门户上找到有关其他Vonage SDK和工具的信息。

许可证

该库在Apache 2.0许可证下发布

欢迎贡献！

我们:heart:欢迎对这个库的贡献！

如果您计划添加任何新功能，最好先与我们沟通。 否则，我们始终欢迎错误报告、 错误修复以及对库的反馈。