タイマーREST APIリファレンス
タイマーREST APIを使用して、スキルでタイマーを作成、一時停止、再開、キャンセルできます。タイマーの設定時間が経過すると、Alexaはチャイム音を鳴らしたり、アナウンスを提供したり、タスクを起動したりできます。
タイマーの詳細については、Alexaタイマーの概要を参照してください。
APIエンドポイント
Alexaからのリクエストのcontext.System.apiEndpoint
値に基づいて、次のいずれかのエンドポイントを使用します。
- 北米:
https://api.amazonalexa.com
- ヨーロッパ:
https://api.eu.amazonalexa.com
- 極東:
https://api.fe.amazon.com
認証
スキルセッションからのAPIリクエストの場合は、Alexaからのリクエスト(LaunchRequest
、IntentRequest
など)によって取得したcontext.System.apiAccessToken
を値に設定した認可ヘッダーを含めます。タイマーは、スキルセッションからのみ作成、一時停止、再開できます。
ウェブサイトまたはアプリからのセッション外のAPIリクエストの場合は、認可ヘッダーにLogin with Amazon(LWA)のアクセストークンを含めます。アクセストークンを取得する方法の詳細については、スキルにメッセージを送信するためのアクセス権限をリクエストするを参照してください。
オペレーション
タイマーAPIには、以下のオペレーションが含まれています。
オペレーション | HTTPメソッドとURI |
---|---|
| |
| |
| |
| |
| |
| |
|
タイマーを作成する
新しいタイマーを作成して設定します。タイマーの設定時間と、設定時間が経過したときの動作を指定します。タイマーの設定時間が経過した場合、Alexaはチャイム音を鳴らしたり、アナウンスを提供したり、タスクを起動したりできます。
リクエスト
タイマーを作成するには、timers
リソースに対してPOST
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
POST /v1/alerts/timers
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
ヘッダー |
ユーザーのアクセストークンです。 |
文字列 |
◯ |
リクエスト本文の通知の例
リクエスト本文のアナウンスの例
リクエスト本文のタスク起動の例
リクエスト本文のプロパティ
プロパティ | 説明 | 型 | 必須 |
---|---|---|---|
|
タイマーを実行する時間です。 |
文字列 |
◯ |
|
タイマーの名前です。ユーザーはこの名前でタイマーを参照できます。 |
文字列 |
✕ |
|
タイマー作成時の動作を定義します。 |
オブジェクト |
◯ |
|
画面付きAlexa搭載デバイスでのタイマーの動作を指定します。 |
オブジェクト |
◯ |
|
画面付きAlexa搭載デバイスでのタイマーの表示/非表示を指定します。 |
文字列 |
◯ |
|
タイマーの設定時間が経過したときのAlexaの動作を定義します。 |
オブジェクト |
◯ |
|
タイマーの設定時間が経過したときに実行するオペレーションを定義します。 |
Operationオブジェクト |
◯ |
|
タイマーの設定時間が経過したときに通知を再生するかどうかを定義します。 |
オブジェクト |
◯ |
|
タイマーの設定時間経過が可聴であるかどうかを示します。 |
ブール値 |
◯ |
応答
正常に完了すると、HTTP 200 OK
と共に、タイマーの詳細が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。許可されている最大件数を超えてタイマーを作成しようとすると、Alexaはcode
= MAX_TIMERS_EXCEEDED
のHTTP 403 Forbidden
を返します。
応答本文の例
以下は、応答の例です。
{
"id": "timer.id",
"status": "PAUSED",
"duration": "PT10M",
"timerLabel": "エクササイズ",
"triggerTime": "2019-09-12T19:10:00.083Z",
"createdTime": "2019-09-12T19:00:00.083Z",
"updatedTime": "2019-09-12T19:04:35.083Z",
"remainingTimeWhenPaused": "PT5M25S"
}
応答本文のプロパティ
プロパティ | 説明 | 型 |
---|---|---|
|
タイマーを一意に識別します。 |
文字列 |
|
タイマーの状態です。
|
文字列 |
|
タイマーの継続時間です。 |
文字列 |
|
(任意)タイマーの名前です。ユーザーはこの名前でタイマーを参照できます。 |
文字列 |
|
タイマーの設定時間が経過し、ユーザーに通知する時間です。 注: Alexaは、タイマーの設定時間とユーザーのタイムゾーンでの作成時刻に基づいてトリガー時刻を計算します。
|
文字列 |
|
タイマーが作成された時刻です。 |
文字列 |
|
タイマーが最後に一時停止、再開、停止された時刻です。存在しない場合は、 |
文字列 |
|
(任意)タイマーが一時停止された場合の残り時間を指定します。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
応答本文にタイマーの情報が含まれています。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、トークンが無効または有効期限切れです。または、リソースに対するアクセス権限がクライアントにありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。たとえば、作成されたタイマーが最大件数(25件)に達している場合などです。 |
|
リクエストされたリソースが見つからないか、タイマーが存在しません。 |
|
スキルが許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
すべてのタイマーをキャンセルする
任意のAlexa搭載デバイスを使用してこのスキルでユーザー用に作成されたすべてのタイマーをキャンセル・削除します。
リクエスト
タイマーをキャンセルするには、timers
リソースに対してDELETE
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
DELETE /v1/alerts/timers
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
ヘッダー |
ユーザーのアクセストークンです。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
応答の本文はありません。
応答本文のプロパティ
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
このスキルでユーザー用に作成されたすべてのタイマーが正常にキャンセルされました。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、トークンが無効または有効期限切れです。または、リソースに対するアクセス権限がクライアントにありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。たとえば、作成されたタイマーが最大件数(25件)に達している場合などです。 |
|
リクエストされたリソースが見つからないか、タイマーが存在しません。 |
|
スキルが許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
タイマーをキャンセルする
指定のタイマーをキャンセル・削除します。
リクエスト
タイマーをキャンセルするには、timers
リソースに対してDELETE
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
DELETE /v1/alerts/timers/{id}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
タイマーIDです。 |
文字列 |
◯ |
|
ヘッダー |
ユーザーのアクセストークンです。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
応答の本文はありません。
応答本文のプロパティ
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
指定されたタイマーが正常にキャンセルされました。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、トークンが無効または有効期限切れです。または、リソースに対するアクセス権限がクライアントにありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。たとえば、作成されたタイマーが最大件数(25件)に達している場合などです。 |
|
リクエストされたリソースが見つからないか、タイマーが存在しません。 |
|
スキルが許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
タイマーを取得する
このスキルで作成された指定のタイマーを取得します。
リクエスト
タイマーを取得するには、timers
リソースに対してGET
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
GET /v1/alerts/timers/{id}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
タイマーIDです。 |
文字列 |
◯ |
|
ヘッダー |
ユーザーのアクセストークンです。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
と共に、タイマーの詳細が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
応答の本文はありません。
応答本文のプロパティ
プロパティ | 説明 | 型 |
---|---|---|
|
タイマーを一意に識別します。 |
文字列 |
|
タイマーの状態です。
|
文字列 |
|
タイマーの継続時間です。 |
文字列 |
|
(任意)タイマーの名前です。ユーザーはこの名前でタイマーを参照できます。 |
文字列 |
|
タイマーの設定時間が経過し、ユーザーに通知する時間です。 注: Alexaは、タイマーの設定時間とユーザーのタイムゾーンでの作成時刻に基づいてトリガー時刻を計算します。
|
文字列 |
|
タイマーが作成された時刻です。 |
文字列 |
|
タイマーが最後に一時停止、再開、停止された時刻です。存在しない場合は、 |
文字列 |
|
(任意)タイマーが一時停止された場合の残り時間を指定します。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
応答本文にタイマーの情報が含まれています。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、トークンが無効または有効期限切れです。または、リソースに対するアクセス権限がクライアントにありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。たとえば、作成されたタイマーが最大件数(25件)に達している場合などです。 |
|
リクエストされたリソースが見つからないか、タイマーが存在しません。 |
|
スキルが許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
タイマーの一覧を取得する
任意のAlexa搭載デバイスを使用してこのスキルでユーザー用に作成されたすべてのタイマーを取得します。
リクエスト
タイマーを取得するには、timers
リソースに対してGET
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
GET /v1/alerts/timers
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
ヘッダー |
ユーザーのアクセストークンです。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
と共に、設定時間が最短のものから最長のものの順に並べられたタイマーのリストが返されます。タイマーがない場合、AlexaはtotalCount
が0に設定された空のリストを返します。
エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。
応答本文の例
{
"timers": [{
"id": "timer.id.1",
"status": "ON",
"duration": "PT10M",
"triggerTime": "2019-12-03T10:25:30Z",
"createdTime": "2019-12-03T10:15:30Z",
"updatedTime": "2019-12-03T10:15:30Z"
},
{
"id": "timer.id.2",
"status": "PAUSED",
"duration": "PT15M",
"timerLabel": "ピザ",
"createdTime": "2019-12-03T10:15:30Z",
"updatedTime": "2019-12-03T10:12:03Z",
"remainingTimeWhenPaused": "PT3M3S"
}
],
"totalCount": 2,
"nextToken": null
}
応答本文のプロパティ
プロパティ | 説明 | 型 |
---|---|---|
|
タイマーのリストです。 |
オブジェクトの配列 |
|
タイマーを一意に識別します。 |
文字列 |
|
タイマーの状態です。
|
文字列 |
|
タイマーの継続時間です。 |
文字列 |
|
(任意)タイマーの名前です。ユーザーはこの名前でタイマーを参照できます。 |
文字列 |
|
タイマーの設定時間が経過し、ユーザーに通知する時間です。 注: Alexaは、タイマーの設定時間とユーザーのタイムゾーンでの作成時刻に基づいてトリガー時刻を計算します。
|
文字列 |
|
タイマーが作成された時刻です。 |
文字列 |
|
タイマーが最後に一時停止、再開、停止された時刻です。存在しない場合は、 |
文字列 |
|
(任意)タイマーが一時停止された場合の残り時間を指定します。 |
文字列 |
|
タイマーの合計数です。 |
整数 |
|
返すタイマーがほかにもあるかどうかを示します。現時点では、ページ分割はサポートされていません。常に |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
応答本文にタイマーのリストが含まれています。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、トークンが無効または有効期限切れです。または、リソースに対するアクセス権限がクライアントにありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。たとえば、作成されたタイマーが最大件数(25件)に達している場合などです。 |
|
リクエストされたリソースが見つからないか、タイマーが存在しません。 |
|
スキルが許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
タイマーを一時停止する
現在のAlexa搭載デバイスで指定のタイマーを一時停止し、残り時間を保存します。ユーザーがタイマーを再開すると、タイマーは続行されます。
リクエスト
タイマーを一時停止するには、timers
リソースに対してPOST
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
POST /v1/alerts/timers/{id}/pause
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
タイマーIDです。 |
文字列 |
◯ |
|
ヘッダー |
ユーザーのアクセストークンです。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。status
= PAUSED
のタイマーを一時停止しようとすると、Alexaはcode
= TIMER_ALREADY_PAUSED
のHTTP 400 Bad Request
を返します。
応答本文の例
応答の本文はありません。
応答本文のプロパティ
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
指定されたタイマーが正常に一時停止されました。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、トークンが無効または有効期限切れです。または、リソースに対するアクセス権限がクライアントにありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。たとえば、作成されたタイマーが最大件数(25件)に達している場合などです。 |
|
リクエストされたリソースが見つからないか、タイマーが存在しません。 |
|
スキルが許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
タイマーを再開する
一時停止したタイマーを再開します。ユーザーがタイマーをキャンセルまたは再度一時停止しない限り、タイマーは残り時間の経過後に作動します。
リクエスト
タイマーを再開するには、timers
リソースに対してPOST
リクエストを実行します。
リクエストパスとリクエストヘッダーの例
POST /v1/alerts/timers/{id}/resume
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
リクエストパスとリクエストヘッダーのパラメーター
パラメーター | 位置 | 説明 | 型 | 必須 |
---|---|---|---|---|
|
パス |
タイマーIDです。 |
文字列 |
◯ |
|
ヘッダー |
ユーザーのアクセストークンです。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のプロパティ
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200 OK
が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。status
がPAUSED
に設定されていないタイマーを再開しようとすると、Alexaはcode
= TIMER_IS_NOT_PAUSED
のHTTP 400 Bad Request
を返します。
応答本文の例
応答の本文はありません。
応答本文のプロパティ
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
指定されたタイマーが正常に再開されました。 |
|
リクエスト本文の1つ以上のプロパティが無効であることを示します。
|
|
リクエストに認可トークンが含まれていないか、トークンが無効または有効期限切れです。または、リソースに対するアクセス権限がクライアントにありません。 |
|
認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。たとえば、作成されたタイマーが最大件数(25件)に達している場合などです。 |
|
リクエストされたリソースが見つからないか、タイマーが存在しません。 |
|
スキルが許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。 |
|
サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。 |
オブジェクトの定義
オペレーション
Operation
オブジェクトは、タイマーの設定時間が経過したときのAlexaの動作を定義します。
プロパティ | 説明 | 型 | 必須 |
---|---|---|---|
|
タイマーの設定時間が経過したら、Alexaはこのタイプ値に基づいて、チャイム音を鳴らしたり、アナウンスのテキストを読み上げたり、Skill Connectionsのタスクを起動したりします。 |
文字列 |
◯ |
|
アナウンスのテキストとロケール情報です。 注: SSMLはサポートされていません。
|
オブジェクトの配列 |
✕ |
|
タイマーの設定時間が経過したときにAlexaが読み上げるテキストです。 注: Alexaは、アナウンスの先頭に「<スキル名>から」のテキストを追加します。
|
文字列 |
◯ |
|
アナウンスで適用されるロケールです。 |
文字列 |
◯ |
|
カスタムタスクに関する情報です。 |
オブジェクト |
✕ |
|
カスタムタスクの名前です。 |
文字列 |
◯ |
|
タスクのバージョンです。 |
文字列 |
◯ |
|
Alexaがタスクを起動するときに含めるカスタムタスクの情報です。 |
オブジェクト |
✕ |
|
確認アナウンスのテキストとロケール情報です。ユーザーはタスクを承認または拒否する必要があります。 注: SSMLはサポートされていません。
|
オブジェクトの配列 |
✕ |
|
別のスキルに接続してタスクを完了させるかどうかのプロンプトをユーザーに出す目的でAlexaが読み上げるテキストです。 注: Alexaは、
continueWithSkillName を「<スキル名>で続行」に置き換えます。 |
文字列 |
◯ |
|
アナウンスで適用されるロケールです。 |
文字列 |
◯ |
関連トピック
最終更新日: 2022 年 11 月 24 日