AlexaリマインダーAPIリファレンス

AlexaリマインダーAPIリファレンス

AlexaリマインダーAPIを使用して、スキルからリマインダーを作成および管理します。このリファレンスでは、AlexaリマインダーAPIで使用できるオペレーションについて説明します。

関連トピック： Alexaリマインダーの概要およびAlexaリマインダー--使用のガイドライン

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": {}
  }
}