Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

メニュー

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Usage and Migration Guide for Twilio's Java Helper Library 7.x

サポート終了のお知らせ: ライブラリーの新機能は、今後新しいバージョン(Java 7.x)にのみ追加される予定です。 旧ライブラリー(Java 6.x)は廃止予定でTwilioは今後不具合修正を提供しません。 事象のデバッグに先立って、サポート担当がアップグレードを促すことがあります。

The Twilio Java SDK has undergone significant changes from version 6.x to 7.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 Java app for the first time, you can skip straight to the install page.

Javaバージョンの互換性

Twilio SDKのバージョン7.xは、Java Version 7以降に対応しています。

インポート

Twilio Java SDKの前バージョンでは、下記のようにクライアントをインポートされたことと思います。

import com.twilio.sdk.LookupsClient;
import com.twilio.sdk.TwilioIPMessagingClient;
import com.twilio.sdk.TwilioRestClient;

バージョン7.x以降では、Twilioはひとつのみ存在します。

import com.twilio.Twilio;

下記のように Twilio を初期化します:

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

アクション

バージョン7.xでのアクションの実行は、FetcherCreatorUpdaterDeleter、そしてReader という5つの個別の型に抽象化されました。

These actions can be created by calling the fetch, create, update, delete, and read static methods on the resource class. Only at this point HTTP requests are being made. This allows for better network efficiency and makes it clear when the library will perform HTTP requests.

Fetcher

リソースのインスタンスを取得するには、fetcher を使用します:

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
...

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
Message message = Message.fetcher("SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").fetch();

System.out.println("message sid: " + message.getSid());
// message sid: SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Creator

リソースの新規インスタンスを作成するには、creator を使用します:

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;
...

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
Message message = Message.creator(
    new PhoneNumber("+15558675309"),
    new PhoneNumber("+15017250604"),
    "Hello world!"
).create();

System.out.println("message body: " + message.getBody());
// message body: Hello world!

Updater

リソースのインスタンスを変更するには、updater を使用します:

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;
...

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

// First, create a new message we can work with:
Message message = Message.creator(
    new PhoneNumber("+15558675309"),
    new PhoneNumber("+15017250604"),
    "Hello world!"
).create();

System.out.println("message sid: " + message.getSid());
// message sid: SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

System.out.println("message body: " + message.getBody());
// message body: Hello world!

// Now use an updater to modify the body of the message
// (redacting the message with empty body)
Message updatedMessage = Message.updater(message.getSid())
    .setBody("")
    .update();

System.out.println("message sid: " + updatedMessage.getSid());
// message sid: SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

System.out.println("message body: " + updatedMessage.getBody());
// message body: 

Deleter

リソースのインスタンスを削除するには、Deleter を使用します:

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
...

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
boolean deleted = Message.deleter("SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").delete();

System.out.println(deleted);
// true

Reader

リソースを一覧するには、reader を使用します:

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
...

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
Iterable<Message> messages = Message.reader().read();
for (Message message : messages) {
   System.out.println("message sid: " + message.getSid());
   // message sid: SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
}

ページング

バージョン7.xでは、改ページ処理が自動で行われます。 Iterable でループを回すことで、 必要に応じて次のページを取得できます。 さらに追加で独自の処理を付け加えるには、Reader アクションで setPageSize を使用することで読み込まれる各ページのサイズを設定できます。

Builders

バージョン7.xでは、Builder パターンが使用されます。 リソースを作成 (Creating) または更新 (Updating) する際にどのようなパラメーターが使用されるかを公開するための型システムが使用されます。

旧バージョンのライブラリーでは、下記のような情報のみが提供されていました:

public void update(Map<String, String> params)

上記は問題なく動作するかもしれませんが、自己記述的とはいえません。 これでは、リクエストに何を渡しているのか皆目見当がつかないでしょう。 たとえば、このようにすることもできます:

Map<String, String> params = new HashMap<>();
params.put("foo", "bar");

resource.update(params);

旧バージョンのJava SDKでは、これはエラーにはなりませんが、実際には何も行わないHTTPリクエストしか発行しません。

Now, 7.x only allows you to pass parameters that are supported. For example, the Updater action for a Message has the following method:

public MessageUpdater setBody(String body)

This makes it clear that the only field you can update on an existing message is the Body field. On the other hand, the Creator has these methods:

public MessageCreator setStatusCallback(URI statusCallback)
public MessageCreator setStatusCallback(String statusCallback)
public MessageCreator setApplicationSid(String applicationSid)
public MessageCreator setMaxPrice(BigDecimal maxPrice)
public MessageCreator setProvideFeedback(Boolean provideFeedback)
public MessageCreator setFrom(PhoneNumber from)
public MessageCreator setMessagingServiceSid(String messagingServiceSid)
public MessageCreator setBody(String body)
public MessageCreator setMediaUrl(List<URI> mediaUrl)
public MessageCreator setMediaUrl(URI mediaUrl)
public MessageCreator setMediaUrl(String mediaUrl)

ここでは、 Creator のインスタンスを作成し、希望のパラメーターを設定、そして Create  を呼び出す方法についてのコード例を示します。

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;
...

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
Message message = Message.creator(
        new PhoneNumber("+15558675309"),
        new PhoneNumber("+15017250604"),
        "This is the ship that made the Kessel Run in fourteen parsecs?"
        )
    .setMediaUrl("https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg")
    .create();

公開されるアクション

バージョン7.xでは、Resource のサポートするアクションのみが公開されています。 たとえば、下記のリクエストは旧バージョンでは有効なものでした:

LookupsClient lc = new LookupsClient(ACCOUNT_SID, AUTH_TOKEN);
PhoneNumber number = lc.getPhoneNumber("+18089263410");
number.update(new HashMap<String, String>());

Twilio API経由での PhoneNumber の更新は許可されていないため、このリクエストは例外をスローします。

In 7.x, this is not allowed because there is no Updater for the PhoneNumber class.

TwiML

バージョン7.xではまた、TwiMLの生成をビルダー・パターンに移行しました。

属性

TwiML リソースによってサポートされる属性のみが設定できるようになっています。 旧バージョンのSDKでは、アクションの発生につながるかどうかにかかわらず、要素に対して任意の属性を設定することができていました。 たとえば、旧バージョンのライブラリーでは以下はエラーなく実行されます:

Say say = new Say();
say.set("foo", "bar");

バージョン7.xのビルダーでは、Say動詞に対して有効な属性のみがサポートされます。

public static class Builder {
    public Builder loop(int loop)
    public Builder language(Language language)
    public Builder voice(Voice voice)
    public Say build()
}

要素

ビルダー・パターンの使用により、有効な子要素をコンパイル時に保証できるようになります。 これでもう、子要素の追加が原因で TwiMLExceptions が発生する可能性にさいなまされることがなくなります。

音声通話 TwiML

The TwiMLResponse class has been replaced by VoiceResponse and MessagingResponse, each one encapsulating the relevant functionality for voice and messaging TwiML generation.

ビルダーのパターンに加えて、バージョン7.xでのTwiMLに関する他の変更点は、特定の属性に列挙型 (enum) を使用するようになったことです。 下記に、基本的なSayのTwiML VoiceResponseの例を示します:

        
        
        
        

        入れ子にされた動詞についてもビルダーパターンの利点が活かせるようになっています。 下記の例をご覧ください。

              
              
              
              

              メッセージング TwiML

              MessagingResponseもVoiceResponseと同様に機能します。 下記に例を示します。

                    
                    
                    
                    

                    もうひとつ、入れ子にされた動詞の例をご紹介します。

                          
                          
                          
                          

                          例外

                          7.x has added more descriptive exception types.

                          Twilio クライアント

                          バージョン6.xでは、クライアント認証の問題はTwilioRestExceptionジェネリックで処理され、API呼び出しが行われた時のみ発生していました。

                          import com.twilio.sdk.TwilioRestClient;
                          import com.twilio.sdk.resource.instance.*;
                          import com.twilio.sdk.TwilioRestException;
                          
                          public class Example { 
                          
                            private static final String ACCOUNT_SID = "ACXXX";
                            private static final String AUTH_TOKEN = "xxxxx";
                          
                            Account getAccount() throws TwilioRestException {
                               TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);
                          
                               return client.getAccount();
                            } 
                          } 
                          

                          バージョン7.xでは、AuthenticationExceptionでクライアントを初期化する際に認証の例外を処理できるようになったことに気づかれるでしょう。

                          import com.twilio.Twilio;
                          import com.twilio.exception.AuthenticationException;
                          
                          public class Example { 
                          
                            private static final String ACCOUNT_SID = "ACXXX";
                            private static final String AUTH_TOKEN = "xxxxx";
                          
                            void setupClient() throws AuthenticationException { 
                               Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
                            } 
                          } 
                          

                          アクション

                          バージョン6.xTwilioRestClientと同様、ファクトリーは同じTwilioRestExceptionを使用します。 バージョン7.xでは、さらに細分化された例外が利用可能なことがわかります。 この場合は、Message.creatorTwilioExceptionをスローします。

                          import com.twilio.Twilio;
                          import com.twilio.exception.AuthenticationException;
                          import com.twilio.exception.TwilioException;
                          import com.twilio.rest.api.v2010.account.Message;
                          import com.twilio.type.PhoneNumber;
                          
                          public class Example { 
                          
                            private static final String ACCOUNT_SID = "ACXXX";
                            private static final String AUTH_TOKEN = "xxxxx";
                          
                            void sendMessage() throws AuthenticationException, TwilioException { 
                               Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
                          
                               Message message = Message.creator(
                                   new PhoneNumber("+15558675309"),
                                   new PhoneNumber("+15017250604"),
                                   "Hello world!"
                               ).create();
                            } 
                          } 
                          

                          ClientCapabilty

                          TwilioCapability は、CapabilityTokenに置き換わりました。 TwilioCapabilityは通常、DomainExceptionジェネリックをスローします。 バージョン7.xには、より分かりやすい例外 JwtEncodingException があります。

                          import com.twilio.sdk.client.TwilioCapability;
                          import com.twilio.jwt.Jwt;
                          import java.util.List;
                          import javax.servlet.http.HttpServlet;
                          import javax.servlet.http.HttpServletRequest;
                          import javax.servlet.http.HttpServletResponse;
                          import java.io.IOException;
                          
                          public class TwilioServlet extends HttpServlet {
                          
                              private static final String ACCOUNT_SID = "ACXX";
                              private static final String AUTH_TOKEN = "your_auth_token";
                          
                              public void service(
                                      HttpServletRequest request,
                                      HttpServletResponse response
                                  ) throws JwtEncodingException, IOException {
                          
                                  List<Scope> scopes = Lists.newArrayList(
                                      new IncomingClientScope("joey")
                                  );
                                  Jwt jwt = new ClientCapability.Builder(ACCOUNT_SID, SECRET)
                                                .scopes(scopes).build();
                          
                                  Claims claims = Jwts.parser()
                                                      .setSigningKey(SECRET.getBytes())
                                                      .parseClaimsJws(jwt.toJwt())
                                                      .getBody();
                          
                                  String token = capability.generateToken();
                          
                                  response.setContentType("application/jwt");
                                  response.getWriter().print(token);
                              }
                          }
                          

                          TwiML

                          6.xおよび7.x、両バージョンのTwiMLビルダークラスは、同一の例外、TwimlException を使用します。

                          import com.twilio.sdk.client.TwilioCapability;
                          import com.twilio.jwt.Jwt;
                          import com.twilio.twiml.voice.Say;
                          import com.twilio.twiml.TwiMLException;
                          import com.twilio.twiml.VoiceResponse;
                          import java.util.List;
                          import javax.servlet.http.HttpServlet;
                          import javax.servlet.http.HttpServletRequest;
                          import javax.servlet.http.HttpServletResponse;
                          
                          public class TwilioServlet extends HttpServlet {
                          
                              private static final String ACCOUNT_SID = "ACXX";
                              private static final String AUTH_TOKEN = "your_auth_token";
                          
                              public void service(
                                      HttpServletRequest request,
                                      HttpServletResponse response
                                  ) throws TwimlException {
                                  Say say = new Say.Builder("Hello World!")
                                      .voice(Say.Voice.MAN)
                                      .loop(5)
                                      .build();
                          
                                  VoiceResponse voiceResponse = new VoiceResponse.Builder()
                                      .say(say)
                                      .build();
                          
                                  response.setContentType("application/xml");
                                  response.getWriter().print(voiceResponse.toXml());
                              }
                          }
                          

                          APIリクエストのデバッグ

                          デバッグを容易にするため、ライブラリーでは内部的に使用されるリクエストおよびレスポンスのオブジェクトへのアクセスが行えるようになっています。 この機能はライブラリーに内蔵されている既定のHTTPクライアントに内蔵されています。

                          たとえば、下記のようにして直前のレスポンスのステータスコードを取得できます:

                          // Install the Java helper library from twilio.com/docs/java/install
                          import com.twilio.Twilio;
                          import com.twilio.rest.api.v2010.account.Message;
                          import com.twilio.type.PhoneNumber;
                          
                          public class Example {
                              // Find your Account Sid and Token at twilio.com/user/account
                              public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
                              public static final String AUTH_TOKEN = "your_auth_token";
                          
                              public static void main(String[] args) {
                                  Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
                          
                                  Message message = Message
                                          .creator(new PhoneNumber("+14158675309"),
                                                   new PhoneNumber("+14258675310"),
                                                   "Ahoy!")
                                          .create();
                          
                                  // Retrieve the status code of the last response from the HTTP client
                                  int statusCode = Twilio.getRestClient().getHttpClient().getLastResponse()
                                          .getStatusCode();
                          
                                  System.out.println(statusCode);
                              }
                          }
                          
                          Rate this page:

                          ヘルプが必要ですか?

                          誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。