AlexaリマインダーAPIリファレンス
AlexaリマインダーAPIを使用して、スキルからリマインダーを作成および管理します。このリファレンスでは、AlexaリマインダーAPIで使用できるオペレーションについて説明します。
関連トピック: Alexaリマインダーの概要およびAlexaリマインダー--使用のガイドライン
- AlexaリマインダーAPIのエンドポイントと認可
- AlexaリマインダーAPIのセッション内およびセッション外の動作
- リマインダーの作成
- リマインダーの取得
- リマインダーの複数取得
- リマインダーの更新
- リマインダーの削除
- リマインダーオブジェクト
- トリガー時刻の計算
- エラーメッセージ
- リマインダーイベントのサブスクリプション
AlexaリマインダーAPIのエンドポイントと認可
APIのエンドポイントは、受信リクエストのcontext
オブジェクトのapiEndpoint
値から取得します。
-
北米:https://api.amazonalexa.com
-
ヨーロッパ:https://api.eu.amazonalexa.com
-
極東:https://api.fe.amazonalexa.com
すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。
一部のオペレーションで使用されるid
は、リマインダーのidを指します。これはリマインダーが作成されるときに自動的に生成されます。
AlexaリマインダーAPIのセッション内およびセッション外の動作
リマインダーはセッション内アクセストークンを使用してのみ作成できます。ただし、GET、UPDATE、およびDELETEオペレーションは、セッション内およびセッション外の両方のアクセストークンで動作します。関連トピック: セッション外の対話
リマインダーの作成
このAPIは、現在のスキルの新しいリマインダーを作成するために呼び出されます。
リクエスト
POST /v1/alerts/reminders
リクエストのヘッダー
Content-length: <<バイト長>>
Authorization: Bearer <<アクセストークン>>
Content-Type: application/json
リクエストの本文(SCHEDULED_ABSOLUTE)
{
"requestTime" : "2016-09-22T19:04:00.672",
"trigger": {
"type" : "SCHEDULED_ABSOLUTE",
"scheduledTime" : "2018-09-22T19:00:00.000",
"timeZoneId" : "America/Los_Angeles",
"recurrence" : {
"freq" : "WEEKLY",
"byDay": ["MO"]
}
},
"alertInfo": {
"spokenInfo": {
"content": [{
"locale": "en-US",
"text": "犬の散歩"
}]
}
},
"pushNotification" : {
"status" : "ENABLED"
}
}
リクエストの本文(SCHEDULED_RELATIVE)
{
"requestTime" : "2018-09-22T19:04:00.672",
"trigger": {
"type" : "SCHEDULED_RELATIVE",
"offsetInSeconds" : "7200"
},
"alertInfo": {
"spokenInfo": {
"content": [{
"locale": "en-US",
"text": "犬の散歩"
}]
}
},
"pushNotification" : {
"status" : "ENABLED"
}
}
フィールド | 説明 | パラメータータイプ |
---|---|---|
requestTime | 有効なISO 8601形式です。イベントが実際に発生した時刻を記述します。 | 文字列 |
trigger | リマインダーのトリガーに関する情報を含みます。 | オブジェクト |
trigger.type | トリガーのタイプを示します。SCHEDULED_ABSOLUTE またはSCHEDULED_RELATIVE です。 |
enum |
trigger.offsetInSeconds | trigger.type がSCHEDULED_RELATIVE に設定された場合は、このフィールドを使用して、リマインダーが鳴らされるまでの時間を指定します(秒)。 |
整数 |
trigger.timeZoneId | タイムゾーンのIDを含む文字列です。タイムゾーンの動作を参照してください。 | enum |
trigger.recurrence | トリガーの繰り返し情報に関する情報を含みます。 | オブジェクト |
trigger.recurrence.freq | 次のいずれかになります。 WEEKLY 、DAILY 。反復の頻度のタイプです。 |
enum |
trigger.recurrence.byDay | 曜日のリストを指定します。標準的な2文字の略語を使用します。たとえば、1週間全体は[ SU, MO, TU, WE, TH, FR, SA ]です。 | enum |
alertInfo | アラートに関する情報を含みます。 | オブジェクト |
alertInfo.spokenInfo | アラートに含まれる発話コンテンツに関する情報を含みます。 | オブジェクト |
alertInfo.spokenInfo.content | アラートのコンテンツを含みます。 | オブジェクト |
alertInfo.spokenInfo.content.locale | 値の指定に使用されるロケールです。 | enum |
alertInfo.spokenInfo.content.text | 表示および読み上げ用に使用されるテキストです。 | 文字列 |
pushNotification | プッシュ通知に関する情報を含みます。 | オブジェクト |
pushNotification.status | 次のいずれかになります。 ENABLED 、DISABLED |
enum |
応答
HTTP/1.1 200 OK
応答の本文
{
"alertToken": "string",
"createdTime": "2018-08-14T15:40:55.002Z",
"updatedTime": "2018-08-14T15:40:55.002Z",
"status": "ON",
"version": "string",
"href": "string"
}
フィールド | 説明 | パラメータータイプ |
---|---|---|
alertToken | このリマインダーアラートの一意のID | 文字列 |
createdTime | 有効なISO 8601形式 - このリマインダーアラートの作成時刻です | 文字列 |
updatedTime | 有効なISO 8601形式 - このリマインダーアラートの最終更新時刻です | 文字列 |
status | 「ON」または「COMPLETED」 | enum |
version | このリマインダーアラートのバージョン | 文字列 |
href | 作成されたアラートを取得するURIです | 文字列 |
リマインダーの取得
このAPIは、現在のスキルの特定のリマインダーを取得するために呼び出されます。
リクエスト
GET /v1/alerts/reminders/{id}
応答
HTTP/1.1 200 OK
{
"totalCount": "string",
"alerts": [
{
"alertToken": "string",
"createdTime": "2018-08-14T15:47:48.386Z",
"updatedTime": "2018-08-14T15:47:48.386Z",
"status": "ON",
"trigger": {
"type": "SCHEDULED_ABSOLUTE",
"scheduledTime": "2018-08-14T15:47:48.387Z",
"offsetInSeconds": 0,
"timeZoneId": "string",
"recurrence": {
"freq": "WEEKLY",
"byDay": [
"SU"
],
"interval": 0
}
},
"alertInfo": {
"spokenInfo": {
"content": [
{
"locale": "string",
"text": "string"
}
]
}
},
"pushNotification": {
"status": "ENABLED"
},
"version": "string"
}
],
"links": "string"
}
リマインダーの複数取得
このAPIはスキルによって呼び出され、スキルのすべてのリマインダーを取得します。ステータスが「OFF」の完了済みのリマインダーも含まれます。
リクエスト
GET /v1/alerts/reminders
応答
HTTP/1.1 200 OK
{
"totalCount": "string",
"alerts": [
{
"alertToken": "string",
"createdTime": "2018-08-14T16:03:38.811Z",
"updatedTime": "2018-08-14T16:03:38.811Z",
"status": "ON",
"trigger": {
"type": "SCHEDULED_ABSOLUTE",
"scheduledTime": "2018-08-14T16:03:38.811Z",
"offsetInSeconds": 0,
"timeZoneId": "string",
"recurrence": {
"freq": "WEEKLY",
"byDay": [
"SU"
],
"interval": 0
}
},
"alertInfo": {
"spokenInfo": {
"content": [
{
"locale": "string",
"text": "string"
}
]
}
},
"pushNotification": {
"status": "ENABLED"
},
"version": "string"
}
],
"links": "string"
}
リマインダーの更新
このAPIは、現在のスキルのリマインダーを更新するために呼び出されます。
リクエスト
PUT /v1/alerts/reminders/{id}
リクエストの本文
{
"createdTime": "2018-08-14T15:53:12.919Z",
"trigger": {
"type": "SCHEDULED_ABSOLUTE",
"scheduledTime": "2018-08-14T15:53:12.919Z",
"offsetInSeconds": 0,
"timeZoneId": "string",
"recurrence": {
"freq": "WEEKLY",
"byDay": [
"SU"
],
"interval": 0
}
},
"alertInfo": {
"spokenInfo": {
"content": [
{
"locale": "string",
"text": "string"
}
]
}
},
"pushNotification": {
"status": "ENABLED"
}
}
応答
HTTP/1.1 200 OK
応答の本文
{
"alertToken": "string",
"createdTime": "2018-08-14T15:40:55.002Z",
"updatedTime": "2018-08-14T15:40:55.002Z",
"status": "ON",
"version": "string",
"href": "string"
}
フィールド | 説明 | パラメータータイプ |
---|---|---|
alertToken | このリマインダーアラートの一意のID | 文字列 |
createdTime | 有効なISO 8601形式 - このリマインダーアラートの作成時刻です | 文字列 |
updatedTime | 有効なISO 8601形式 - このリマインダーアラートの最終更新時刻です | 文字列 |
status | 「ON」または「COMPLETED」 | enum |
version | このリマインダーアラートのバージョン | 文字列 |
href | 作成されたアラートを取得するURIです | 文字列 |
リマインダーの削除
このAPIは、現在のスキルの特定のリマインダーを削除するために呼び出されます。このオペレーションはアクティブなアラートのみを削除します。完了したものは削除しません。完了したリマインダーはAlexaアプリに3日間表示され、その後は自動的に削除されます。
リクエスト
DELETE /v1/alerts/reminders/{id}
応答
HTTP/1.1 200 OK
リマインダーオブジェクト
フィールド | 説明 | パラメータータイプ |
---|---|---|
requestTime | 有効なISO 8601形式で表されたこのリマインダーアラートの作成時刻です。 | 文字列 |
trigger | 必須です。リマインダーのトリガー情報です。 | オブジェクト |
trigger.type | 次のいずれかになります。 SCHEDULED_ABSOLUTE 、SCHEDULED_RELATIVE 。リマインダーは、特定の時刻、またはrequestTime を起点にoffsetInSeconds で計算された相対時刻に設定できます。 |
enum |
trigger.scheduledTime | 有効なISO 8601形式で表されたトリガー予定時刻です。trigger.type がSCHEDULED ABSOLUTE の場合に使用します。 |
文字列 |
trigger.offsetInSeconds | trigger.type がSCHEDULED_RELATIVE の場合に、このフィールドを使用して、リマインダーが鳴らされるまでの時間を指定します(秒) |
整数 |
trigger.timeZoneId | リマインダーの想定タイムゾーンです。こちらのタイムゾーンのリストを参照してください | 文字列 |
alertInfo | VUI/GUI体裁のリマインダーのアラート情報です。 | オブジェクト |
alertInfo.spokenInfo | 必須です。リマインダーのVUI体裁です。読み上げ情報と表示情報は同じです。 | オブジェクト |
alertInfo.spokenInfo.content | 読み上げ情報と表示情報の内容。1つ以上のロケールにalertInfo.spokenInfo.content.text が必要です。 |
文字列 |
alertInfo.spokenInfo.content.locale | 読み上げテキストが出力されるロケールです。 | Alexaでサポートされるロケールのいずれかです(例:en-US )。 |
alertInfo.spokenInfo.content.text | プレーンテキスト形式の読み上げテキストです。 | 文字列 |
pushNotification | Alexaモバイルアプリへのリマインダーのプッシュ通知を有効または無効にします。 | オブジェクト |
pushNotification.status | 次のいずれかになります。 ENABLED 、DISABLED 。デフォルトはENABLED です。 |
enum |
トリガー時刻の計算
スキルは絶対時刻または相対時刻のどちらかを使用してリマインダーを設定できます。SCHEDULED_ABSOLUTE
またはSCHEDULED_RELATIVE
のtrigger.type
を使用します。
絶対計算
例: スキルで、6月1日の午後7時に薬を飲むリマインダーを設定します。絶対時刻を使用するリマインダーの場合、scheduledTime
は必須フィールドです。
"type" : "SCHEDULED_ABSOLUTE"
"scheduledTime" : "2018-06-01T19:00:00"
相対計算
例: スキルで、1時間後に薬を飲むなど経過時間ベースのリマインダーを設定します。
"type" : "SCHEDULED_RELATIVE"
"offsetInSeconds" : 3600
このオフセットはリクエスト内のrequestedTime
からの相対です。
リマインダー時刻におけるタイムゾーンの動作
事例1: デバイスのタイムゾーンでのリマインダー
スキルがデバイスのタイムゾーンでリマインダーを設定します。この場合、timezoneId
は不要です。
"scheduledTime" : "2018-06-01T19:00:00"
このリクエストでは、リマインダーはデバイスのタイムゾーンの午後7時に設定されます。
事例2: アプリのタイムゾーンでのリマインダー
スキルは、リマインダーが設定されている日時とタイムゾーンを提供します。例: マイサロンで、ニューヨークの6月1日午後7時にお客様の予約のリマインダーを設定します。実際にリマインダーが通知される日時を考慮してtimezoneId
の値を設定したかどうか確認してください。
"scheduledTime" : "2018-06-01T19:00:00"
"timezoneId" : "America/New_York"
ユーザーのデバイスがアプリリクエストとは異なるタイムゾーンの場合、Alexaは読み上げおよび表示用に時刻をデバイスのタイムゾーンに変換します。そのため、ユーザーのデバイスが日本時間(JST、東京)の場合、読み上げおよび表示時刻はJST 6月2日午前8時になります。
エラーメッセージ
Httpステータスコード | 列挙 | メッセージ |
---|---|---|
400 | INVALID_REQUEST_TIME_FORMAT | リクエストの日時形式が正しくありません。 |
INVALID_TRIGGER | タイプとフィールドが一致しません。SCHEDULED_ABSOLUTEにoffsetInSecondsが設定されているか、SCHEDULED_RELATIVEにscheduledTimeが設定されています。 | |
TRIGGER_SCHEDULED_TIME_IN_PAST | 予定時刻が過去です。 | |
INVALID_TRIGGER_SCHEDULED_TIME_FORMAT | 日付形式がサポートされていません。 | |
INVALID_TRIGGER_TIME_ZONE | タイムゾーンが有効ではありません。 | |
INVALID_TRIGGER_RECURRENCE | 繰り返しパターンが無効です。 | |
UNSUPPORTED_TRIGGER_RECURRENCE | 繰り返しパターンが有効ですが現在はサポートされていません。 | |
INVALID_ALERT_INFO | アラート情報にロケールがないか、無効なロケール形式です。 テキスト文字列が長すぎます。 |
|
INVALID_TRIGGER_OFFSET | 無効な相対時刻のオフセットです。 | |
401 | UNAUTHORIZED | トークンは有効ですが適切な権限がありません。 |
MISSING_BEARER_TOKEN | アクセストークンがありません。 | |
INVALID_BEARER_TOKEN | 無効または誤ったアクセストークンです。 | |
EXPIRED_BEARER_TOKEN | アクセストークンが失効しています。 | |
403 | MAX_REMINDERS_EXCEEDED | デバイスのリマインダーの上限(500など)に達しました。 |
404 | ALERT_NOT_FOUND | アラートが存在しません。 |
429 | MAX_RATE_EXCEEDED | リクエストはスキルごとに速度25 TPSに調整されます。 |
500 | INTERNAL_SERVER_ERROR | |
503 | SERVICE_UNAVAILABLE | |
504 | DEVICE_NOT_REACHABLE | デバイスにアクセスできません。またはデバイスがオフラインです。 |
リマインダーイベントのサブスクリプション
関連トピック: Alexaスキルのスキルイベント
リマインダーイベントをサブスクリプションすると、AlexaリマインダーAPIを呼び出さずにスキルにこれらのイベントを通知できます。スキルでは、アカウントリンクを使用して外部アプリを組み込み、これらのイベントの通知を使用して、アプリ内のリマインダーの削除や変更など、アプリの変更を行うことができます。
イベントの通知は順不同で届くので、リマインダーイベントの結果としてスキルが実行するアクションでは、イベントのタイムスタンプに注意する必要があります。たとえば、リマインダーが2回更新され、先に更新されたイベントが次に更新されたイベントの後に届いた場合、先に更新されたものは破棄される必要があります。
Alexaは、スキルサービスが応答で確認を送信しなかった場合、イベントの再配信を試行します。スキルサービスは過去のイベントをAlexaから取得することはできず、配信されたイベントを利用する必要があります。
イベントで使用されるapiEndpoint値
エンドポイントは、https://api.amazonalexa.comです。
JSON形式のリマインダーイベント
スキルサービスでのイベントの使用に従ってリマインダーイベントをサブスクリプションするようにスキルを設定し、skill.jsonマニフェストファイルを設定できます。
利用可能なリマインダーイベントは次のとおりです。
- REMINDER_STARTED
- REMINDER_CREATED
- REMINDER_UPDATED
- REMINDER_STATUS_CHANGED
- REMINDER_DELETED
ReminderStarted
このイベントは、リマインダーが鳴り始めたときに生成されます。このイベントはspeechletのNotificationStartedイベントによって生成されます。これにより、スキル側でトリガー時刻にアクションを行うことができます
{
"version": "1.0", // バージョン、文字列
"context": {
"System": {
"application": {
"applicationId": "<skill_id>" // スキルid、文字列
},
"user": {
"userId": "amzn1.ask.account.VEBA...", // スキルのユーザーID、 文字列
"accessToken": "<access_token>", // 3Pでユーザーを識別するトークン
"permissions": {
"consentToken": "Atza|IgEB..." // リマインダーAPIを呼び出すトークン
}
},
"apiEndpoint": "https://api.amazonalexa.com" // リマインダーAPIを呼び出すエンドポイント
}
},
"request": {
"type": "Reminders.ReminderStarted",
"requestId": "913e4588-62f9-4d5b", // 文字列
"timestamp": "2017-09-15T01:46:14Z", // イベントのタイムスタンプ、YYYY-MM-DD'T'hh:mm:ss'Z'
"body": {
"alertToken": "<alert-token-value>", // 鳴らされたリマインダー
}
},
"session": {
"attributes": {}
}
}
ReminderCreated
このイベントは、Alexaシステムでリマインダーが作成されたときに生成されます。リマインダーが作成されたことをスキルに通知します。このイベントはリマインダーの作成者には送信されません。
{
"version": "1.0", // バージョン、文字列
"context": {
"System": {
"application": {
"applicationId": "<skill_id>" // スキルid、文字列
},
"user": {
"userId": "amzn1.ask.account.VEBA...", // スキルのユーザーID、 文字列
"accessToken": "<access_token>", // 3Pでユーザーを識別するトークン
"permissions": {
"consentToken": "Atza|IgEB..." // リマインダーAPIを呼び出すトークン
}
},
"apiEndpoint": "https://api.amazonalexa.com" // リマインダーAPIを呼び出すエンドポイント
}
},
"request": {
"type": "Reminders.ReminderCreated",
"requestId": "<requestId-value>", // 文字列
"timestamp": "2017-09-15T01:46:14Z", // イベントのタイムスタンプ、YYYY-MM-DD'T'hh:mm:ss'Z'
"body": {
"alertToken": "<alert-token-value>", // 作成されたリマインダートークン
}
},
"session": {
"attributes": {}
}
}
ReminderDeleted
このイベントは、リマインダーがユーザーによって削除されたときに生成されます。
{
"version": "1.0", // バージョン、文字列
"context": {
"System": {
"application": {
"applicationId": "<skill_id>" // スキルid、文字列
},
"user": {
"userId": "amzn1.ask.account.VEBA...", // スキルのユーザーID、 文字列
"accessToken": "<access_token>", // 3Pでユーザーを識別するトークン
"permissions": {
"consentToken": "Atza|IgEB..." // リマインダーAPIを呼び出すトークン
}
},
"apiEndpoint": "https://api.amazonalexa.com" // リマインダーAPIを呼び出すエンドポイント
}
},
"request": {
"type": "Reminders.ReminderDeleted",
"requestId": "<requestId-value", // 文字列
"timestamp": "2017-09-15T01:46:14Z", // イベントのタイムスタンプ、YYYY-MM-DD'T'hh:mm:ss'Z'
"body": {
"alertToken": "<alert-token-value>", // 削除されたalertToken
}
},
"session": {
"attributes": {}
}
}
ReminderUpdated
このイベントは、リマインダーが更新されたときに生成されます。リマインダーのキャンセル、延期、完了、一時停止、再開、スヌーズ、オン、トリガー時刻の更新、ラベルの更新などです。リマインダーの現在の状態以外の更新の詳細は提供されません。更新の詳細を取得するには、スキルでリマインダーの取得を使用して更新の詳細を取得する必要があります。
{
"version": "1.0", // バージョン、文字列
"context": {
"System": {
"application": {
"applicationId": "<skill_id>" // スキルid、文字列
},
"user": {
"userId": "amzn1.ask.account.VEBA...", // スキルのユーザーID、 文字列
"accessToken": "<access_token>", // 3Pでユーザーを識別するトークン
"permissions": {
"consentToken": "Atza|IgEB..." // APIを呼び出すトークン
}
},
"apiEndpoint": "https://api.amazonalexa.com" // APIを呼び出すエンドポイント
}
},
"request": {
"type": "Reminders.ReminderUpdated",
"requestId": "913e4588-62f9-4d5b", // 文字列
"timestamp": "2017-09-15T01:46:14Z", // イベントのタイムスタンプ、YYYY-MM-DD'T'hh:mm:ss'Z'
"body": {
"status": "DEFERRED" // リマインダーのステータスの説明
"alertToken": "09d9d7df-05be-438c-veba", // 更新されたalertToken
}
},
"session": {
"attributes": {}
}
}