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 リソースのページを移動する
When fetching multiple pages of API results, use the provided nextpageuri
parameter to retrieve the next page of results.
All of the Twilio Helper Libraries handle paging automatically. You do not need to explicitly request individual pages when using a Helper Library to fetch lists of 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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.