REST API: Commands
Commandsリソースを使用すると、SMS機能を持つ機器からマシンからマシンへ簡単なメッセージを交換することができます。 たとえば、コマンドを使用してデバイスに自身のAPNを変更するよう指示できます。
SMSは転送手段として使用されますが、コマンドを受け取るためにSIM側でのアドレス指定可能な電話番号は必要ありません。 これは、会話メッセージングに使用されるTwilioのMessagesリソースとの主な相違点です。
SIMから確定済み電話番号へ送信されたメッセージ（SIMからコマンドを受信するを参照してください）はコマンドとして解釈され、SIMのコマンドコールバックURLに送信が行われます。
コマンドは、SMSテキストモード、またはバイナリー（PDU）モードで送受信できます。 テキストモードコマンドの最大文字数は160文字（シングルバイト文字）／70文字（ダブルバイト文字）です。 バイナリーモードコマンド最大長は140バイトです。
デバイスに送信されたコマンドを受信、処理するには、おそらく「ATコマンド」を使用してモデムと直接やりとりする必要があります。 SMSメッセージの受信には、GSM/LTEモジュールの製造元のドキュメントを確認してください。
一般的なタスク
- 単一のヒストリックコマンドを取得する
- ヒストリックコマンドの一覧を取得する
- サーバーからSIMにコマンドを送信する
- SIMからサーバーにコマンドを送信する
- Delete a single historic Command
非同期のリソース
Commandリソースは非同期オペレーションを実行します。 Commandリソースの更新終了時に非同期の通知を受信するには、最初のHTTPリクエストにコールバックURLと、オプションでコールバックメソッドパラメーターを指定するすることが必要です。 下記に、これを行う例を示します。
HTTPリソースとメソッド
Commandインスタンスリソース
リソースURL
https://wireless.twilio.com/v1/Commands/{CommandSid}
リソースのプロパティ
Commandインスタンスリソースは以下のプロパティーによって構成されています。
| Names in py format | |
|---|---|
sid
|
このリソースを一意に識別する 34 文字の文字列です。 |
account_sid
|
このコマンドの属するアカウントの一意なIDです。 |
sim_sid
|
このコマンドが送信、または受信された |
command
|
メッセージがSIMに、またはSIMから送信されます。 テキストモードのメッセージでは、半角ASCII文字160字以内に収めることが必要です。 バイナリーモードのメッセージでは、base64を使用してエンコーディングされる、最大140バイトの一連のデータです。 |
command_mode
|
どのモードでSMSが送信または受信されたかを示す文字列です。 |
transport
|
|
delivery_receipt_requested
|
|
status
|
コマンドのステータスを示す文字列です。 |
direction
|
コマンドの方向です。 |
date_created
|
このリソースの作成された日時で、ISO 8601形式のGMTで取得可能です。 |
date_updated
|
このリソースが最後に更新された日時で、ISO 8601形式のGMTで取得可能です。 |
url
|
このリソースに対するURLです。 |
ステータス値
下表は、Commandインスタンスで利用可能なstatus値について説明しています。
| Status | 概要 |
|---|---|
| queued | コマンドはTwilioのネットワーク中でSIMへの送信の待機のため、待ち行列に入れられます。 |
| sent | コマンドがSIMに送信されました。 |
| delivered | コマンドがSIMに配信されました。 （to_simコマンド向け） |
| received | コマンドがSIMから受信されました。 （from_simコマンド向け） |
| failed | コマンドに失敗しました。 |
コマンドの一覧リソース
リソース URL
https://wireless.twilio.com/v1/Commands
HTTP GET
アカウント内のCommandsリソースを一覧します。 このリストにはページング情報が含まれます。
例 1
アカウントの全Commandを一覧します。
リストフィルター
下記のGETのクエリー文字列パラメーターを使用すると、返される一覧を制限することができます。 パラメーターは大文字と小文字を区別することに注意してください:
| Names in py format | |
|---|---|
sim
オプション
|
このSIMとの間で送受信されるコマンドのみを返します。 |
status
オプション
|
このステータス値を伴うコマンドのみを返します。 |
direction
オプション
|
この方向のコマンドのみを返します。 |
transport
オプション
|
Only return Commands with this transport value. |
| Names in py format | |
|---|---|
command
必須
|
（テキストモードにおける）コマンドのメッセージ本文、またはバイナリーモードにおけるbase64でエンコーディングされたバイト文字列です。 |
sim
オプション
|
コマンドを送信する先の、SIMのSidまたはUniqueName（一意な名前）です。 |
callback_method
オプション
|
コールバックURLへのリクエストの発行時にTwilioが使用するHTTPメソッド（有効な選択肢はGETまたはPOST）です。 既定値はPOSTです。 |
callback_url
オプション
|
Twilioは、コマンドの送信が終了（delivered、またはfailed）すると、このURLにリクエストを発行します。 |
command_mode
オプション
|
SMSメッセージの送信にどのモードを使用するかを表す文字列です。 |
include_sid
オプション
|
テキストモードでSIMにコマンドが送信されるとき、Twilioはメッセージ本文に、デバイスが同一のコマンドを複数回実行しないことを確実にするために使用されるコマンドのSidを自動的に含めます。 インクルージョンの選択肢は |
delivery_receipt_requested
オプション
|
A boolean representing whether to request delivery receipt from the recipient. For Commands that request delivery receipt, the Command state transitions to 'delivered' once the server has received a delivery receipt from the device. Defaults to true. |
コールバック値
送信におけるコマンド配信は非同期で行われるため、コマンド送信の試行が完了した時点で呼び出されるコールバックURLを渡すことが推奨されます。 コールバックには下記のパラメーターが含まれます。
| パラメーター | 概要 |
|---|---|
| CommandSid | このコールバックが参照しているコマンドです。 |
| CommandStatus | コマンドの現在のステータスです。 |
| SimSid | このコマンの送信先のSIMです。 |
| SimUniqueName | 存在する場合、受信側のSIMのUniqueName（一意な名前）です。 |
| ErrorCode | エラーの発生時、エラーコードが提供されます。 |
| ErrorMessage | エラーの発生時、エラーメッセージが提供されます。 |
| ApiVersion | 最初のリクエストが発行されたAPIのバージョンです。 |
| AccountSid | このコマンドの属するアカウントの一意なIDです。 |
| CommandMode | SMSの送信にどのモードが使用されたかを表す文字列です。 text あるいは binary のいずれかです。 |
コールバックメソッドがPOSTに設定されるか指定されなかった場合、コールバックパラメーターはHTMLフォームパラメーターとして渡されます。 コールバックメソッドがGETであった場合、コールバックパラメーターはクエリー文字列として渡されます。
例
SIMにコマンドを送信します。コマンドの配信の試行が完了した際に非同期で通知されるコールバックURLとコールバックメソッドを指定します。 この例では、受信側のSIMを識別するため、「AliceSmithSmartMeter」というSIMのUniqueName（一意な名前）を使用します。
Commands sent from SIMs in ready status
A Command can be sent from a SIM in the ready status. Following the fifth Command sent to_sim or from_sim the device will automatically transition to the active status. Visit the SIM Status Values to learn more.
HTTP PUT
サポートされていません。
HTTP DELETE
サポートされていません。
SIMからコマンドを受信する
SIMからコマンドを受信する（モバイルオリジネーション）には、CommandsCallbackUrlプロパティーと、オプションでCommandsCallbackMethodプロパティー（既定値はPOST）を使用して、既存のSIMインスタンスを更新することが必要です。
SIMがSMSメッセージを予約済み電話番号である「2936」に送信する際、Commandリソースが作成され、CommandsコールバックURLが呼び出されます。 コールバックリクエストには下記のパラメーターが含まれます。
| パラメーター | 概要 |
|---|---|
| CommandSid | このコマンドのSidです。 |
| SimSid | このコマンドの送信元のSIMです。 |
| SimUniqueName | 存在する場合、送信側のSIMのUniqueName（一意な名前）です。 |
| Command | コマンドメッセージの本文です。 textモードでは、この値は160文字以内（日本語を含む場合70文字以内）のテキストです。 binaryモードの場合、この値は最大サイズが140バイトの、Base64でエンコーディングされた文字列です。 |
| Status | 常に「received」という文字列です。 |
| ApiVersion | 最初のリクエストが発行されたAPIのバージョンです。 |
| AccountSid | このコマンドの属するアカウントの一意なIDです。 |
| CommandMode | どのモードでSMSが受信されたかを表す文字列です。 text あるいは binary のいずれかです。 |
ヘルプが必要ですか？
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.