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.
最後に、弊社はいつでもお手伝いに労を惜しみません。サポートに直接お問い合わせください。
ヘルプが必要ですか？
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.