Usage and Migration Guide for Twilio's Ruby Helper Library 5.x
Deprecation notice: New functionality will only be added to the new library (Ruby Helper Library 5.x). The old library (4.x) is deprecated and Twilio will no longer provide bug fixes. Support might ask you to upgrade before debugging issues.
The Twilio Ruby Helper Library has undergone a number of changes from version 4.x to 5.x - we'll break down the major changes here to make migrating to the new version as painless as possible. If you're integrating Twilio in your Ruby app for the first time, you can skip straight to the install page.
Rubyバージョンサポート
Note: twilio-ruby 5.x only supports Ruby 2.0+ due to both 1.8.x/1.9.x reaching End of Life.
リソースへのアクセス
# Old call = @client.account.calls.get('CA123xxx') # New call = @client.api.v2010.account.calls('CA123xxx').fetch ## OR call = @client.api.account.calls('CA123xxx').fetch
新しいライブラリーでは、TwilioのAPIサブドメイン（Lookups、Trunking、Monitorなど）は一級市民です。 またTwilio APIへのインスタンスを特定のAPIのバージョンにつなぎとめておくこともできるようになりました（すなわち、.v2010.は常にAPIの2010-04-01バージョンとやりとりすることを保証します）。 こうすることで、ライブラリーの更新時にフルにアップグレードを行うことなく、コードの一部分のみを将来のバージョンに独立して移行することができます。
また、実際のCallインスタンスの取得の最後でfetchを呼び出す必要がある点にもお気づきでしょう。 これは、.calls('CAxxx')が「コンテキスト」を返すためです。 これによって、その後fetchを呼び出してインスタンスを、付随する全プロパティーを伴って受け取ることができます。 こうすることでネットワーク効率が向上し、ライブラリーが実際にHTTPインタラクションを処理するタイミングが明確になります。
> workspace = @client.taskrouter.workspaces('WSxxx') #=> <WorkspaceContext ...> > workspace.fetch #=> <WorkspaceInstance status='active'...>
リソースの一覧
リソースの一覧を取得する方法が2種類になりました: listとstreamです。
- リストについてはこれまでどおり機能します。 リソースの
Instances(インスタンス) を含むArray(配列) を返します。
> @client.api.account.messages.list #=> [#<MessageInstance ..>, #<MessageInstance ..>, ...]
streamブロックに渡すことができるEnumerableを返し、これは事実上リソースの一覧のページング処理を行い、インスタンスの最大数（limitが設定されていない場合は全リソースの一覧）をブロックに渡します。
> @client.api.account.messages.stream(limit: 5) {|m| puts m.sid} MS111xxx MS222xxx MS333xxx MS444xxx MS555xxx
ページング
ライブラリーは自動でページング処理をしてくれるようになりました！ listおよびstreamでは取得したいインスタンスの数 (limit) 、各ページで表示したい最大数 (page_size) 、そして取得するページの最大数 (page_limit) を指定できるようになりました。 後のことはライブラリーが（最大限効率よく）処理を行います。
@client.api.account.incoming_phone_numbers.stream(limit: 3000, page_size: 100) do |number| puts number.phone_number end
> @client.conversations.completed.list(page_size: 100, page_limit: 10).size #=> 1000
正しい型
twilio-rubyリソースは適切な型にシリアル化、逆シリアル化されるようになりました。 たとえば、バージョン4.xではdateはStringとして表され、文字列を使用可能な型へのシリアル化、逆シリアル化する実装についてはユーザーに委ねられていました。 バージョン5.xでは、TimeおよびDateオブジェクトに対処します。
# Old feedback = @client.account.calls.feedback_summary.create(start_date: '2016-01-01', end_date: '2016-01-05') feedback.start_date #=> "2016-01-01" # New feedback = @client.api.account.calls.feedback_summary.create(start_date: Date.new(2016, 1, 1), end_date: Date.new(2016, 1, 5)) feedback.start_date #=> #<Date 2016-01-01 ..>
構成可能なHTTPクライアント
独自のHTTPクライアントをTwilio::RESTクライアントに接続できるようになりました！ Twilio::HTTP::HttpClient インターフェイスに適合するラッパーを作成するだけです。 続いて、初期化済みのオブジェクトをTwilio::REST::Clientオブジェクトに渡します。
custom_client = MyCustomClient.new @client = Twilio::REST::Client.new('ACxxx', 'AUTHTOKEN', http_client: custom_client)
既定ではFaradayが使用されるため、任意のFaradayアダプターをプラグインすることも可能です。
@client.http_client.adapter = :typhoeus
See a complete example of creating a custom client in the Twilio helper library.
エラー処理
エラーの処理に役立つ新しいクラスも用意されています。 新しいライブラリーはTwilio::REST::RestErrorクラスを使用するようになりました。
# Old begin call = @client.account.calls.get('CA123xxx') rescue Twilio::REST::RequestError => e logger.log(e.message) end # New begin call = @client.account.calls('CA123xxx').fetch rescue Twilio::REST::RestError => e logger.log(e.message) end
TwiML生成
簡単なTwiMLの出力するため、呼び出しをチェインすることができます。 下記に例を示します:
require 'twilio-ruby' response = Twilio::TwiML::VoiceResponse.new def output_quick_polite_twiml(): VoiceResponse.say('Hello!').hangup
また、出力したいレスポンスの種類に応じて、2つのレスポンスタイプがあります。 VoiceResponseは音声通話関連のすべての動詞、MessagingResponseはメッセージ関連のすべての動詞に対するものです。
VoiceResponseインスタンスのメソッドとして、音声通話関連の動詞が用意されています。 また、キーワード引数を使用してこれらの動詞に対して任意の属性を設定できます。 これらすべてはアンダースコア記法を使用します。
入れ子にされた動詞はwithを使用する必要はなくなり、代わりにappendが親要素となります。
同様の変更はMessagingResponseにも当てはまります。
入れ子にされた例です:
APIリクエストのデバッグ
デバッグを容易にするため、ライブラリーでは内部的に使用されるリクエストおよびレスポンスのオブジェクトへのアクセスが行えるようになっています。 この機能はライブラリーに内蔵されている既定のHTTPクライアントに内蔵されています。
たとえば、下記のようにして直前のレスポンスのステータスコードを取得できます:
require 'rubygems' # not necessary with ruby 1.9 but included for completeness require 'twilio-ruby' # put your own credentials here account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' auth_token = 'your_auth_token' # set up a client to talk to the Twilio REST API @client = Twilio::REST::Client.new(account_sid, auth_token) @message = @client.messages.create( to: '+14158675309', from: '+14258675310', body: 'Ahoy!' ) # Retrieve the status code of the last response from the HTTP client puts @client.http_client.last_response.status_code
関連トピックとサポート
すべてのクイックスタート、チュートリアル、およびAPIリファレンスのドキュメントには、古い4.xライブラリと新しい5.xライブラリの両方のサンプルコードが含まれています。 コピー＆ペーストで活用できるサンプルが数多くあります。
The Twilio Ruby helper library is open source software. Please visit us on GitHub to view the source, open issues, or submit pull requests.
Finally, know we are always ready to help! Just contact us directly for support.
ヘルプが必要ですか？
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.