Usage and Migration Guide for Twilio's Node.js Helper Library 3.x
Deprecation notice: New functionality will only be added to the new library (Node Helper Library 3.x). The old library (2.x) is deprecated and Twilio will no longer provide bug fixes. Support might ask you to upgrade before debugging issues.
The Twilio Node Helper Library has undergone a number of changes from version 2.x to 3.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 Node app for the first time, you can skip straight to the install page.
ライブラリーのインポート
twilio-node
2.xでは、使用する各クライアントのインスタンスを作成することが必要でした。
var Twilio = require('twilio'); var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; var authToken = 'your_auth_token'; var ipmClient = new Twilio.IpMessagingClient(accountSid, authToken); var lookupsClient = new Twilio.LookupsClient(accountSid, authToken);
twilio-node
3.xでは今や、インポート、初期化すべきオブジェクトはただひとつです。
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; var authToken = 'your_auth_token'; var Twilio = require('twilio'); var twilio = new Twilio(accountSid, authToken);
リソースへのアクセス
// Old client.messages('SM123').get(function(err, message) { console.log(message.sid); //=> SM123 }); // New client.api.v2010.account.messages('SM123').fetch(function(err, message) { console.log(message.sid); //=> SM123 }); // (or) client.messages('SM123').fetch(function(err, message) { console.log(message.sid); //=> SM123 });
新しいライブラリーでは、TwilioのAPIサブドメイン(Lookups、Trunking、Monitorなど)は一級市民です。 またTwilio APIへのインスタンスを特定のAPIのバージョンにつなぎとめておくこともできるようになりました(v2010は常にAPIの2010-04-01バージョンとやりとりすることを保証します)。 こうすることで、ライブラリーの更新時にフルにアップグレードを行うことなく、コードの一部分のみを将来のバージョンに独立して移行することができます。
また、get
がfetch
に更新されたことにも気づかれるでしょう。 実行されているアクションがより明確になるよう、fetch
、create
、update
、およびremove
を使用するようライブラリーが更新されました。
Promises
またtwilio-node
とのやり取りにプロミスを使用することもできます。
var promise = twilio.messages('SM123').fetch(); promise.then(function(message) { console.log(message.sid); });
リソースの一覧
リソースの一覧を取得する方法が2種類になりました: list
とeach
です。
list
はリソースのコレクション全体を取得し、リソースのインスタンスを含む配列として解決します。
var promise = twilio.messages.list(); promise.then(function(messages) { console.log(messages); //=> [MessageInstance, MessageInstance, MessageInstance, ...] });
each
はリソースの一覧をページ処理し、各インスタンス、それからdone
関数を渡すcallback
関数を呼び出します。 任意の時点で反復処理を停止するには、done
関数を呼び出します。
twilio.messages.each(function(message) { console.log(message.sid); //=> 'SM123' }); var i = 0; twilio.messages.each(function(message, done) { console.log(message.sid); i++; // break after 10 messages if (i >= 10) { done(); } });
ページング
twilio-node
3.xの最大の利点のひとつは、ページ処理を自動で行ってくれることです! list
およびeach
では、取得するインスタンスの最大数をlimit
で、ページサイズをpageSize
で指定できます。 後のことはみんなライブラリーにおまかせです。
twilio.messages.each({limit: 10}, function(message) { console.log(message.sid); }); var promise = twilio.messages.list(); promise.then(function(messages) { console.log(messages.length); //=> 125 }); promise = twilio.messages.list({ limit: 100 }); promise.then(function(messages) { console.log(messages.length); //=> 100 });
構成可能なHTTPクライアント
独自のHTTPクライアントをTwilio
クライアントに接続できるようになりました! RequestClient
インターフェイスに適合したクライアントを、Twilio
の初期化時に渡すだけです。
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; var authToken = 'your_auth_token'; var client = new CustomClient(); var twilio = new Twilio(accountSid, authToken, client);
TwiML
各TwiMLのタイプ、つまりVoiceおよびMessageごとに専用のコンストラクターを使用するようになりました。
// Old var TwimlResponse = require('twilio').TwimlResponse; var twiml = new TwimlResponse(); // New var MessagingResponse = require('twilio').twiml.MessagingResponse; var messagingResponse = new MessagingResponse(); var VoiceResponse = require('twilio').twiml.VoiceResponse; var voiceResponse = new VoiceResponse();
基本的なVoiceResponse
については、パラメーターの順序の変更のみです:
入れ子にされた動詞は、下記の例のようにコールバック内部で定義される必要はなくなりました。
同様のことは、基本的なMessagingResponse
にも当てはまります。
また、こちらは入れ子にされた動詞を含むMessagingResponse
の例です:
capabilityToken
新しいバージョンでは、新しい機能ごとに専用のコンストラクターが用意されています。
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; var authToken = 'your_auth_token'; // Old var capability = new twilio.Capability(accountSid, authToken); capability.allowClientIncoming('Identity'); capability.allowClientOutgoing(TWILIO_TWIML_APP_SID); var token = capability.generate(); // New var ClientCapability = require('twilio').jwt.ClientCapability; var capability = new ClientCapability({ accountSid: accountSid, authToken: authToken }); capability.addScope(new ClientCapability.IncomingClientScope('Identity')); capability.addScope(new ClientCapability.OutgoingClientScope({ applicationSid: config.twimlAppSid, clientName: identity })); var token = capability.toJwt();
APIリクエストのデバッグ
デバッグを容易にするため、ライブラリーでは内部的に使用されるリクエストおよびレスポンスのオブジェクトへのアクセスが行えるようになっています。 この機能はライブラリーに内蔵されている既定のHTTPクライアントに内蔵されています。
たとえば、下記のようにして直前のレスポンスのステータスコードを取得できます:
// Twilio Credentials const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; const authToken = 'your_auth_token'; // require the Twilio module and create a REST client const client = require('twilio')(accountSid, authToken); client.messages .create({ to: '+14158675309', from: '+14258675310', body: 'Ahoy!', }) .then(() => console.log(client.httpClient.lastResponse.statusCode));
例外
3.x has added more descriptive exception handlers.
Now, the exceptions can be caught with the catch()
statement.
client.messages.create({ body: 'Hello from Node', to: '+12345678901', from: '+12345678901' }).then(message => console.log(message)) // here you can implement your fallback code .catch(error => console.log(error))
関連トピックとサポート
すべてのクイックスタート、チュートリアル、APIリファレンスドキュメントで、旧2.xライブラリーおよび新3.xライブラリー双方のコード例が提供されるようになりました。 すぐにコピー、ペースト、編集できる何百というサンプルがご利用いただけます。
The Twilio Node helper library is open source software. Please visit us on GitHub to view the source, open issues, or submit pull requests.
最後に、弊社はいつでもお手伝いに労を惜しみません。サポートに直接お問い合わせください。
ヘルプが必要ですか?
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。