REST API: Twilio のレスポンス

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

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

XML

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

GET /2010-04-01/Accounts/AC228b9.../SMS/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>AC228b97a5fe4138be081eaff3c44180f3</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/AC228b97a5fe4138be081eaff3c44180f3/SMS/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f
        </Uri>
    </SMSMessage>
</TwilioResponse>

JSON

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

GET /2010-04-01/Accounts/AC228b9.../SMS/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": "AC228b97a5fe4138be081eaff3c44180f3",
    "to": "+15305431221",
    "from": "+15104564545",
    "body": "A Test Message",
    "status": "queued",
    "flags":["outbound"],
    "api_version": "2010-04-01",
    "price": null,
    "uri": "\/2010-04-01\/Accounts\/AC228ba7a5fe4238be081ea6f3c44186f3\/SMS\/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 エラーの例です。

Loading Code Sample...

出力を表示

出力

リクエストしたリソースが見つからない

例 2

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

Loading Code Sample...

出力を表示

出力

レスポンスの例外の例 2

ハイパーメディア参照

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

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

Loading Code Sample...

出力を表示

出力

ハイパーメディア参照

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

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

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

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

Loading Code Sample...

出力を表示

出力

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

リストリソース

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

ページ情報

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

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

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

Loading Code Sample...

出力を表示

出力

ページ情報

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」となります。

ヘルプが必要ですか？

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.

Loading Code Sample...

出力