メニュー

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?

REST API: Twilio のレスポンス

レスポンスのフォーマット

ユーザーのリクエストに対し、Twilio はさまざまなフォーマットでレスポンスを返すことができます。 ここでは、最も一般的なものについて詳しく説明します。 特別なケースやその他のフォーマットについては、 Tips & Tricks のセクションを参照してください。

XML

デフォルトでは、Twilio の REST API は、ルート要素が <TwilioResponse> の XML を返却します。 たとえば、SMS メッセージのデフォルトの XML 表現は次のようになります。

GET /2010-04-01/Accounts/ACXXXXX.../Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f
<TwilioResponse>
    <SMSMessage>
        <Sid>SM1f0e8ae6ade43cb3c0ce4525424e404f</Sid>
        <DateCreated>Fri, 13 Aug 2010 01:16:24 +0000</DateCreated>
        <DateUpdated>Fri, 13 Aug 2010 01:16:24 +0000</DateUpdated>
        <DateSent/>
        <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
        <To>+13455431221</To>
        <From>+15104564545</From>
        <Body>A Test Message</Body>
        <Status>queued</Status>
        <Flags>
            <Flag>outbound</Flag>
        </Flags>
        <ApiVersion>2010-04-01</ApiVersion>
        <Price/>
        <Uri>
            /2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f
        </Uri>
    </SMSMessage>
</TwilioResponse>

JSON

Twilio は、リソース表現の JSON 形式の返却もサポートします。 リソース URI に拡張子 .json をつけるだけです。 同じリソースの JSON 表現は次のようになります。

GET /2010-04-01/Accounts/ACXXXXX.../Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f.json
{
    "sid": "SM1f0e8ae6ade43cb3c0ce4525424e404f",
    "date_created": "Fri, 13 Aug 2010 01:16:24 +0000",
    "date_updated": "Fri, 13 Aug 2010 01:16:24 +0000",
    "date_sent": null,
    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "to": "+15305431221",
    "from": "+15104564545",
    "body": "A Test Message",
    "status": "queued",
    "flags":["outbound"],
    "api_version": "2010-04-01",
    "price": null,
    "uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Messages\/SM1f0e8ae6ade43cb3c0ce4525424e404f.json"
}

その他

Twilio は CSV、HTML、その他の形式のレスポンスも返すことができます。 詳細は、Tips & Tricks のセクションを参照してください

例外

エラーが発生すると、Twilio は HTTP レスポンスのボディーの中で例外を返します。 XML では、例外は <TwilioResponse> 要素の中の <RestException> 要素として出現します。 例外には 4 つのプロパティがあります。

プロパティ 概要
Status この例外の HTTP ステータス コードです。
Message この例外に関する、より説明的なメッセージです。
Code (条件あり) この例外を解決する手がかりとなるエラー コードです。
MoreInfo (条件あり) このエラー コードが掲載されている Twilio ユーザー ドキュメントの URL です。

ステータス コード 400 (不正なリクエスト) とともに例外を受け取った場合、Code プロパティと MoreInfo プロパティを利用して、エラーをデバッグします。

サンプル

例 1

単純な 404 エラーの例です。

        
        
        
        
        例 2

        Call リソースに To パラメーターのない不正な POST リクエストを発行すると、次が返ります。

              
              
              
              

              ハイパーメディア参照

              REST の中核をなす原則の 1 つにアプリケーション状態エンジンとしてのハイパーメディア(HATEOAS : Hypermedia As The Engine Of Application State )。 これは通常、REST API リクエストで取得するすべてのリソース表現に、そのリソースおよび関連するリソースを特定する URI を含めなければならないことを意味します。 このため、Twilio REST API はさまざまな URI を含む表現を返却し、ユーザーはこれに従って API を操作します。

              すべての表現には、自己参照 URI (つまり、その表現を取得するための URI) が含まれます。 たとえば、OutgoingCallerId インスタンス リソースを GET した場合、このインスタンス リソースの URI がプロパティの 1 つとして返却されます。

                    
                    
                    
                    

                    リスト リソースのハイパーメディア

                    リスト リソース表現に含まれるページ情報に関連して、その他のハイパーメディア参照情報があります。 後述の ページ情報 のセクションを参照してください。

                    インスタンス リソースのハイパーメディア

                    インスタンス リソースにサブリソースがある場合、その表現には、これらのリソースの URI をサブリソース URI プロパティの中に含めます。 たとえば、Call インスタンス リソースを GET した時に返るサブリソースが、次のようになることに注意してください。

                          
                          
                          
                          

                          リスト リソース

                          リソースが、他のリソースのリストである場合があります。 たとえば、Calls リスト リソースは、通話のリストを返します。 これらのリストを使用し、操作するために知っておくべき重要な点がいくつかあります。

                          ページ情報

                          リストが長く、APIが一つのページに完全な情報を表示できない場合下記の情報を含みます。

                          プロパティ 概要
                          uri このページの URI です。
                          first_page_uri このリストの最初のページの URI です。
                          next_page_uri このリストの次のページの URI です。
                          previous_page_uri このリストの前のページの URI です。
                          page 現在のページ番号です。 ゼロから数えます。最初のページが 0 になります。
                          page_size 各ページの項目数です。

                          たとえば、次のようになります。

                                
                                
                                
                                

                                API リソースのページを移動する

                                API が返す結果のページを複数取得する場合は、受け取った nextpageuri パラメーターを使って、次のページの結果を取得します。 すべての Twilio Helper ライブラリ は、nextpageuri を使ってページを移動します。

                                The Page parameter (without an AfterSid or PageToken), along with numpages, total, start, end, and lastpageuri properties have been deprecated and will be removed on 8/31/2015.

                                Accounts created after 6/16/2015 will no longer have access to these properties by default. You should use the Twilio Helper Libraries or nextpageuri and previouspageuri to navigate through the resources.

                                ページのサイズは PageSize パラメーターで制御できます。

                                パラメーター 概要
                                PageSize 各リスト ページに返すリソースの数です。 デフォルトは 50、最大値は 1000 です。

                                たとえば、1 ページに返す通話の数を 5 に制限する場合は、次のようになります。

                                GET /2010-04-01/Accounts/{AccountSid}/Calls?PageSize=5

                                データ フォーマット

                                電話番号

                                Twilio のリクエストに含まれるすべての電話番号には、可能な場合は E.164 フォーマットが使用されます。 たとえば、(415) 555-4345 は、 ただし、Twilio が着信通話の発信者 ID を E.164 フォーマットに正規化できない場合があります。 その場合、Twilio は発信者 ID 文字列をそのまま通知します。

                                日付と時刻

                                Twilio からのリクエストに含まれるすべての日付と時刻には、 RFC 2822 フォーマットの GMT 時間が使用されます。 たとえば、2010 年 8 月 19 日午後 6 時 13 分 (太平洋夏時間) は、「Fri, 20 Aug 2010 01:13:42 +0000」となります。

                                Rate this page:

                                ヘルプが必要ですか?

                                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.