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

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

AlexaリマインダーREST APIを使用すると、施設内の管理対象デバイスでリマインダーの作成と管理を行うことができます。リマインダーにテキストを設定すると、Alexaはスケジュールされた指定時刻にデバイスからテキストを読み上げます。リマインダーを使用することで、毎日のタスク、イベント、スケジュールや、後で思い出す必要のある任意の項目をユーザーに通知する音声エクスペリエンスを構築できます。

特定のエンドポイントに1回限りのリマインダーをスケジュールできます。これには、午後3時のリマインダーのような絶対時刻リマインダーと、10分後のリマインダーのような相対時刻リマインダーがあります。また、定期的なリマインダーをスケジュールすることもできます。たとえば、毎週平日の午前7時にリマインダーを設定できます。

APIエンドポイント

組織が所在する国に応じて、リクエストヘッダーのHostパラメーターを、以下のいずれかのAPIエンドポイントに設定してください。

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

ドイツ、スペイン、フランス、イタリア、英国

https://api.eu.amazonalexa.com

日本

https://api.fe.amazonalexa.com

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。詳細については、APIアクセスを管理するを参照してください。

操作

リマインダーAPIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

リマインダーの作成

POST /v2/alerts/reminders

リマインダーの削除

DELETE /v2/alerts/reminders/{reminderId}

リマインダーの取得

GET /v2/alerts/reminders/{reminderId}

エンドポイントにあるリマインダーのリストの取得

GET /v2/alerts/reminders?recipient.type={recipientType}}&recipient.id={recipientId}&owner={owner}

リマインダーの更新

PUT /v2/alerts/reminders/{reminderId}

リマインダーの作成

指定したAlexa搭載エンドポイントに新しいリマインダーを作成します。エンドポイントごとに最大250件のリマインダーを作成できます。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

リマインダーを作成するには、/v2/alerts/remindersリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v2/alerts/reminders HTTP/1.1
Host: api.amazonalexa.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

次の例では、2024年6月21日の午後4時30分にトリガーされる1つのリマインダーを作成します。

次の例では、リクエスト時刻として2024-06-21T 22:30:00 UTCを指定し、その30分後にトリガーされるリマインダーを作成します。デバイスのタイムゾーンがAmerica/Los_Angelesの場合、このリマインダーは2024年6月21日午後4時にスケジュールされます。デバイスのタイムゾーンがAmerica/Denverの場合、このリマインダーは2024年6月21日午後5時にスケジュールされます。

次の例では、2024年6月から2024年9月まで、毎月5日の午後4時30分にトリガーされるリマインダーを作成します。

リクエスト本文のプロパティ

プロパティ 説明 型 必須

recipients

このリマインダーを適用する受信者のリスト。指定できる受信者は1つのみです。

オブジェクトの配列

◯

recipients[].type

受信者のタイプ。
有効な値は ENDPOINTです。

文字列

◯

recipients[].id

リマインダーを設定するエンドポイント。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

reminder

リマインダーを表します。

オブジェクト

◯

reminder.requestTime

相対時刻リマインダーをスケジュールするときに使用する日付と時刻を、協定世界時（UTC）で指定します。APIは、requestTimeにoffsetInSecondsを適用して相対時刻リマインダーのトリガー時刻を計算します。指定しない場合、デフォルトで現在の日付と時刻が使用されます。
ISO 8601形式（YYYY-MM-DDThh:mm:ssZ）で指定します。

requestTimeは、デバイスのローカルタイムゾーンではなく、UTC時間で指定します。APIは、リマインダーの時刻を計算するときにデバイスのタイムゾーンを使用します。たとえば、requestTimeが2024-06-21T22:30:00で、offsetInSecondsが1800（30分）であるとします。デバイスのタイムゾーンがAmerica/Los_Angelesの場合、このリマインダーは2024年6月21日午後4時にスケジュールされます。デバイスのタイムゾーンがAmerica/Denverの場合、このリマインダーは2024年6月21日午後5時にスケジュールされます。

文字列

×

reminder.trigger

リマインダーのトリガーに関する情報を含みます。

Triggerオブジェクト

◯

reminder.alertInfo

リマインダーで読み上げられるコンテンツを含みます。

AlertInfoオブジェクト

◯

応答

正常に完了すると、HTTP 202 Acceptedと共に、新しいリマインダーのIDが返されます。エラーの場合は、適切なHTTPステータスコードが返され、エラーが発生したエンドポイント、エラーコード、人が読める形式のメッセージが応答の本文に追加されます。

応答本文の例

次の例は、指定したエンドポイントにリマインダーが正常に作成されたことを示しています。

次の例は、指定したエンドポイントへのリマインダーの作成に失敗したことを示しています。

応答本文のプロパティ

プロパティ 説明 型

type

応答のタイプ。
有効な値は、 ALL_SUCCESS、ALL_FAILEDです。

文字列

message

人が読める形式での結果の説明。このメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。メッセージの内容に依存するビジネスロジックは構築しないでください。

文字列

successResults[]

リマインダーが正常に作成されたエンドポイントのリスト

オブジェクトの配列

successResults[].id

（オプション）リマインダーのエンドポイント受信者のID。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

successResults[].reminderId

（オプション）新しいリマインダーのID

文字列

errors[]

リマインダーの作成に失敗したエンドポイントのリスト

オブジェクトの配列

errors[].id

（オプション）リマインダーのエンドポイント受信者のID。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

errors[].status

（オプション）失敗したリマインダーのエラーのステータスコード

文字列

errors[].errorCode

（オプション）短いエラーコード文字列

文字列

errors[].errorDescription

（オプション）エラーに関する詳細な説明

文字列

HTTPステータスコード

ステータス 説明

202 Accepted

リマインダーが正常に作成されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • CONCURRENT_MODIFICATION - 認証局に対する以前の更新がまだ進行中です。
  • INVALID_INPUT_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 - 繰り返しパターンは有効ですが、サポートされていません。
  • UNSUPPORTED_TRIGGER_RECURRENCE_INTERVAL - 繰り返しパターンは有効ですが、2つの時刻間の最小間隔がサポートされていません。
  • INVALID_ALERT_INFO - アラート情報にロケールがないか、ロケール形式が正しくありません。テキスト文字列が長すぎます。
  • INVALID_TRIGGER_OFFSET - 相対時刻のオフセットが無効です。
  • UNSUPPORTED_SCHEDULED_TIME_FORMAT - トリガー予定時刻の形式がサポートされていません。サポートされている形式は、YYYY-MM-DDTHH:mm:ss.SSSとYYYY-MM-DDTHH:mm:ss/YYYY-MM-DDTHH:mmです。
  • INVALID_INPUT - 入力が無効です。引数を確認し、もう一度試してください。
  • INVALID_RECIPIENT_ID - 受信者のIDが無効です。
  • INVALID_RECIPIENT_TYPE - 受信者のタイプがサポートされていません。
  • DEVICE_NOT_REACHABLE - デバイスが到達不可能またはオフラインです。
    リマインダーが7日以内にトリガーされるように設定されている場合は、リマインダーを作成するディレクティブが呼び出し時に送信されます。
  • DEVICE_NOT_SUPPORTED - このデバイスではリマインダーはサポートされていません。
  • TOO_MANY_RECIPIENTS - 受信者の数が、許容されるしきい値の1を超えています。リマインダーAPIは、現時点では一括リマインダーをサポートしていません。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • MAX_REMINDERS_EXCEEDED - このデバイスのリマインダーの最大数に達しました。

404 Not Found

リクエストされたリソースが見つかりません。

409 Conflict

リクエストが、ターゲットリソースの現在の状態と競合していることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • MISSING_TIME_ZONE - 指定されたエンドポイントにタイムゾーンが設定されていません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

リマインダーの削除

リマインダーIDで指定したリマインダーを削除します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

リマインダーを削除するには、/v2/alerts/remindersリソースに対してDELETEリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

DELETE /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

reminderId

パス

削除するリマインダーのID

文字列

◯

access_token

ヘッダー

LWAアクセストークン。詳細については、認証を参照してください。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

リマインダーが正常に削除されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_REMINDER_ID - 指定されたリマインダーIDが無効です。
  • DEVICE_NOT_REACHABLE - デバイスが到達不可能またはオフラインです。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

リマインダーの取得

リマインダーIDで指定したリマインダーを取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

リマインダーを取得するには、/v2/alerts/remindersリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

reminderId

パス

取得するリマインダーのID

文字列

◯

access_token

ヘッダー

LWAアクセストークン。詳細については、認証を参照してください。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、指定したリマインダーの詳細が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

次の応答本文の例は、絶対時刻リマインダー、定期的なリマインダー、相対時刻リマインダーに対する出力を示しています。

応答本文のプロパティ

プロパティ 説明 型

recipient

このリマインダーの受信者

オブジェクト

recipient.type

受信者のタイプ。
有効な値は ENDPOINTです。

文字列

recipient.id

リマインダーを適用するエンドポイント。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

reminder

リマインダーの内容

オブジェクト

reminder.reminderId

このリマインダーの一意のID

文字列

reminder.createdTime

リマインダーの作成時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

reminder.updatedTime

リマインダーの最終更新時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

reminder.status

リマインダーのステータス。
有効な値は次のとおりです。

  • ON - このリマインダーはアクティブで、予定時刻に再生されます。
  • COMPLETED - このリマインダーはトリガー済みです。Alexaは、完了したリマインダーを3日後に削除します。

文字列

reminder.version

リマインダーのバージョン。
バージョン番号はリマインダーの更新操作によって増加します。

文字列

reminder.trigger

リマインダーのトリガーに関する情報を含みます。

Triggerオブジェクト

reminder.alertInfo

リマインダーで読み上げられるコンテンツを含みます。

AlertInfoオブジェクト

HTTPステータスコード

ステータス 説明

200 OK

指定されたエンドポイントのリマインダーのリストが応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_REMINDER_ID - 指定されたリマインダーIDが無効です。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

エンドポイントにあるリマインダーのリストの取得

指定したエンドポイントにスケジュールされているすべてのリマインダーのリストを取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

リマインダーのリストを取得するには、/v2/alerts/remindersリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

`GET /v2/alerts/reminders?recipient.type={recipientType}}&recipient.id={recipientId}&owner={owner}` HTTP/1.1
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

recipientType

クエリ

受信者のタイプ。
有効な値は ENDPOINTです。

文字列

◯

recipientId

クエリ

受信者の一意のエンドポイントID。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

owner

クエリ

エンドポイントをフィルタリングして、所有者に関連付けられているエンドポイントを取得します。~callerはアクセストークンで識別されるユーザーを表します。
有効な値は~callerです。

文字列

◯

access_token

ヘッダー

LWAアクセストークン。詳細については、認証を参照してください。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、指定したエンドポイントのリマインダーのリストが返されます。

応答本文の例

{
  "results": [
    {
      "recipient": {
        "id": "amzn1.alexa.endpoint.did.1234",
        "type": "Endpoint"
      },
      "reminder": {
        "reminderId": "reminder.Id.4",
        "createdTime": "2024-06-24T20:59:12.772Z",
        "updatedTime": "2024-06-24T20:59:12.929Z",
        "trigger": {
          "type": "SCHEDULED_ABSOLUTE",
          "scheduledTime": "2024-06-24T18:00:00.000",
          "timeZoneId": "America/Denver",
          "offsetInSeconds": 0
        },
        "status": "ON",
        "alertInfo": {
          "spokenInfo": {
            "content": [
              {
                "locale": "ja-JP",
                "text": "午後5時からビンゴが始まります",
                "ssml": "<speak>午後5時からビンゴが始まります</speak>"
              }
            ]
          }
        },
        "version": "2"
      }
    },
    {
      "recipient": {
        "id": "amzn1.alexa.endpoint.did.1234",
        "type": "Endpoint"
      },
      "reminder": {
        "reminderId": "reminder.Id.22",
        "createdTime": "2024-06-21T23:36:25.342Z",
        "updatedTime": "2024-06-24T03:29:53.945Z",
        "trigger": {
          "type": "SCHEDULED_ABSOLUTE",
          "scheduledTime": "2024-06-24T17:40:00.000",
          "timeZoneId": "America/Denver",
          "offsetInSeconds": 0,
          "recurrence": {
            "startDateTime": "2024-06-01T00:00:00.000-06:00",
            "endDateTime": "2024-09-30T00:00:00.000-06:00",
            "recurrenceRules": [
              "FREQ=DAILY;INTERVAL=1;BYHOUR=17;BYMINUTE=40"
            ]
          }
        },
        "status": "ON",
        "alertInfo": {
          "spokenInfo": {
            "content": [
              {
                "locale": "ja-JP",
                "text": "毎日夕食後に薬を服用してください",
                "ssml": "<speak>毎日夕食後に薬を服用してください</speak>"
              }
            ]
          }
        },
        "version": "3"
      }
    }
  ]
}

応答本文のプロパティ

プロパティ 説明 型

results

指定されたエンドポイントに関連付けられているリマインダーのリスト

オブジェクトの配列

results[].recipients

このリマインダーの受信者のリスト

オブジェクトの配列

results[].recipients[].type

受信者のタイプ。
有効な値は ENDPOINTです。

文字列

results[].recipients[].id

リマインダーを適用するエンドポイント。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].reminder

リマインダーの内容

オブジェクト

results[].reminderId

リマインダーの一意のID

オブジェクト

results[].reminder.createdTime

リマインダーの作成時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

results[].reminder.updatedTime

リマインダーの最終更新時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

results[].reminder.status

リマインダーのステータス。
有効な値は次のとおりです。

  • ON - このリマインダーはアクティブで、予定時刻に再生されます。
  • COMPLETED - このリマインダーはトリガー済みです。Alexaは、完了したリマインダーを3日後に削除します。

文字列

results[].reminder.version

リマインダーのバージョン。
バージョン番号はリマインダーの更新操作によって増加します。

文字列

results[].reminder.trigger

リマインダーのトリガーに関する情報を含みます。

Triggerオブジェクト

results[].reminder.alertInfo

リマインダーで読み上げられるコンテンツを含みます。

AlertInfoオブジェクト

HTTPステータスコード

ステータス 説明

200 OK

指定されたエンドポイントのリマインダーのリストが応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_RECIPIENT_TYPE - 指定されたリマインダータイプが無効です。
  • INVALID_REMINDER_ID - 指定されたリマインダーIDが無効です。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

リマインダーの更新

指定したリマインダーを更新します。リマインダーを更新するには、リマインダーのプロパティをすべて指定する必要があります。リマインダーの取得操作を使用してリマインダーオブジェクトを取得し、変更するプロパティを更新します。たとえば、元の予定時刻を維持したままリマインダーのテキストを変更するには、textプロパティとssmlプロパティに新しいテキストを設定し、triggerオブジェクトにはリマインダーの作成時に使用したものと同じ値を設定します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

リマインダーを更新するには、/v2/alerts/remindersリソースに対してPUTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

PUT /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

reminderId

パス

更新するリマインダーのID

文字列

◯

access_token

ヘッダー

LWAアクセストークン。詳細については、認証を参照してください。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
  "recipient": {
    "type": "Endpoint",
    "id": "amzn1.alexa.endpoint.did.1234"
  },
  "reminder": {
    "trigger": {
      "type": "SCHEDULED_ABSOLUTE",
      "timeZoneId": "America/Los_Angeles",
      "recurrence": {
        "startDateTime": "2019-05-10T6:00:00.000",
        "endDateTime": "2019-08-10T10:00:00.000",
        "recurrenceRules": [
          "FREQ=MONTHLY;BYMONTHDAY=5;BYHOUR=10;INTERVAL=1;"
        ]
      }
    },
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "ja-JP",
            "text": "午後5時からビンゴが始まります",
            "ssml": "<speak>午後5時からビンゴが始まります</speak>"
          }
        ]
      }
    }
  }
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

recipient

リマインダーの受信者

オブジェクト

◯

recipient.type

受信者のタイプ。
有効な値は ENDPOINTです。

文字列

◯

recipient.id

リマインダーを設定するエンドポイント。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

reminder

リマインダーを表します。

オブジェクト

◯

reminder.requestTime

相対時刻リマインダーをスケジュールするときに使用する日付と時刻を、協定世界時（UTC）で指定します。APIは、requestTimeにoffsetInSecondsを適用して相対時刻リマインダーのトリガー時刻を計算します。指定しない場合、デフォルトで現在の日付と時刻が使用されます。
ISO 8601形式（YYYY-MM-DDThh:mm:ssZ）で指定します。

requestTimeは、デバイスのローカルタイムゾーンではなく、UTC時間で指定します。APIは、リマインダーの時刻を計算するときにデバイスのタイムゾーンを使用します。たとえば、requestTimeが2024-06-21T22:30:00で、offsetInSecondsが1800（30分）であるとします。デバイスのタイムゾーンがAmerica/Los_Angelesの場合、このリマインダーは2024年6月21日午後4時にスケジュールされます。デバイスのタイムゾーンがAmerica/Denverの場合、このリマインダーは2024年6月21日午後5時にスケジュールされます。

文字列

×

reminder.trigger

リマインダーのトリガーに関する情報を含みます。

Triggerオブジェクト

◯

reminder.alertInfo

リマインダーで読み上げられるコンテンツを含みます。

AlertInfoオブジェクト

◯

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

リマインダーが正常に更新されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • CONCURRENT_MODIFICATION - 認証局に対する以前の更新がまだ進行中です。
  • INVALID_INPUT_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 - 繰り返しパターンは有効ですが、サポートされていません。
  • UNSUPPORTED_TRIGGER_RECURRENCE_INTERVAL - 繰り返しパターンは有効ですが、2つの時刻間の最小間隔がサポートされていません。
  • INVALID_ALERT_INFO - アラート情報にロケールがないか、ロケール形式が正しくありません。テキスト文字列が長すぎます。
  • INVALID_TRIGGER_OFFSET - 相対時刻のオフセットが無効です。
  • UNSUPPORTED_SCHEDULED_TIME_FORMAT - トリガー予定時刻の形式がサポートされていません。サポートされている形式は、YYYY-MM-DDTHH:mm:ss.SSSとYYYY-MM-DDTHH:mm:ss/YYYY-MM-DDTHH:mmです。
  • INVALID_INPUT - 入力が無効です。引数を確認し、もう一度試してください。
  • INVALID_RECIPIENT_ID - 受信者のIDが無効です。
  • INVALID_RECIPIENT_TYPE - 受信者のタイプがサポートされていません。
  • DEVICE_NOT_REACHABLE - デバイスが到達不可能またはオフラインです。
    リマインダーが7日以内にトリガーされるように設定されている場合は、リマインダーを作成するディレクティブが呼び出し時に送信されます。
  • DEVICE_NOT_SUPPORTED - このデバイスではリマインダーはサポートされていません。
  • TOO_MANY_RECIPIENTS - 受信者の数が、許容されるしきい値の1を超えています。リマインダーAPIは、現時点では一括リマインダーをサポートしていません。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • MAX_REMINDERS_EXCEEDED - このデバイスのリマインダーの最大数に達しました。

404 Not Found

リクエストされたリソースが見つかりません。

409 Conflict

リクエストが、ターゲットリソースの現在の状態と競合していることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • MISSING_TIME_ZONE - 指定されたエンドポイントにタイムゾーンが設定されていません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

絶対時刻のタイムゾーン

scheduledTimeプロパティを使用してリマインダーのトリガーを絶対時刻に設定すると、リマインダーは次のように、デバイスのタイムゾーンか、リクエストで定義した特定のタイムゾーンのどちらかで再生されます。

  • デバイスと同じタイムゾーンでリマインダーを設定するには、scheduledTimeプロパティを設定し、timeZoneIdフィールドは未設定のままにします。
  • 特定のタイムゾーンでリマインダーを設定するには、scheduledTimeプロパティとtimeZoneIdプロパティの両方を設定します。

オブジェクトの定義

リマインダーAPIでは、以下のオブジェクトが定義されています。

AlertInfoオブジェクト

AlertInfoオブジェクトは、リマインダーの読み上げと表示に使用されるアラート情報を定義します。

プロパティ 説明 型

spokenInfo

リマインダーで読み上げられるコンテンツに関する情報を含みます。

オブジェクト

spokenInfo.content

アラートで読み上げられるコンテンツ。
配列には1つ以上の項目を含める必要があります。

オブジェクトの配列

spokenInfo.content[].locale

リマインダーテキストのロケールと言語を定義します。

文字列

spokenInfo.content[].text

表示および読み上げのコンテンツとして使用されるデフォルトのテキスト。
このフィールドには音声合成マークアップ言語（SSML）タグを含めないでください。

文字列

spokenInfo.content[].ssml

（オプション）読み上げのコンテンツとして使用されるテキスト。SSMLで記述します。
このフィールドに値を指定しない場合は、spokenInfo.content.textによってテキストと読み上げの両方のコンテンツが処理されます。
有効なSSMLタグはspeakです。

文字列

Errorオブジェクト

Errorオブジェクトは、エラーが発生したときに応答に含まれるエラーのタイプとメッセージを定義します。

以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "REMINDER_NOT_FOUND",
    "message": "Reminder does not exist."
}
プロパティ 説明 型

type

発生したエラーのタイプ。
具体的なエラータイプについては、各操作のHTTPステータスコードの表を参照してください。

文字列

message

読み取り可能なエラーメッセージ。エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。

文字列

Recurrenceオブジェクト

Recurrenceオブジェクトは、定期的なリマインダーのルールを定義します。定期的なリマインダーは、トリガータイプがSCHEDULED_ABSOLUTEの場合に定義できます。

以下の表は、オブジェクトのプロパティの定義です。

プロパティ 説明 型

startDateTime

（オプション）繰り返しパターンの開始時刻。デフォルトは現在の時刻です。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

endDateTime

（オプション）繰り返しパターンの終了時刻。デフォルトでは終了時刻は設定されません。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

recurrenceRules

（オプション）リマインダーを繰り返すための繰り返しパターン。

有効な値は、 FREQ、BYMONTHDAY、BYDAY、BYHOUR、BYMINUTE、BYSECOND、INTERVALです。

有効なFREQルールパターンは、 FREQ=DAILY、FREQ=WEEKLY、FREQ=MONTHLY、FREQ=YEARLYです。

有効なINTERVALの値は次のとおりです。

  • 2つのrecurrence値の最小間隔は、en-USロケールでは1時間、その他すべてのサポートされるロケールでは4時間です。たとえば、 RRULE:FREQ=DAILY;INTERVAL=4のように指定できます。
  • DAILY、WEEKLY、MONTHLYパターンの最大間隔は31日です。たとえば、 RRULE:FREQ=MONTHLY;INTERVAL=6のように指定できます。
  • YEARLYパターンの最大間隔は1年です。

RRULEの配列

Triggerオブジェクト

Triggerオブジェクトは、スケジュール時刻のタイプ（絶対時刻または相対時刻）と、1回限りまたは定期的なリマインダーのルールを定義します。

以下の表は、オブジェクトのプロパティの定義です。

プロパティ 説明 型

type

トリガーのタイプを示します。
有効な値は、 SCHEDULED_ABSOLUTE、SCHEDULED_RELATIVEです。

文字列

offsetInSeconds

（オプション）リマインダーが再生されるまでの秒数を指定します。
trigger.typeがSCHEDULED_RELATIVEの場合に適用されます。

整数

scheduledTime

（オプション）このリマインダーがトリガーされる予定の日時。絶対時刻でスケジュールされます。ISO 8601形式（YYYY-MM-DDThh:mm:ssZ）で指定します。

  • 絶対時刻リマインダーの場合、このフィールドにはスケジュールされた絶対時刻が含まれます。
  • 相対時刻リマインダーの場合、このフィールドには計算されたトリガー時刻が含まれます。これは、リマインダーの作成時に設定されたrequestTimeとoffsetInSecondsに基づいて計算されます。
  • 定期的なリマインダーの場合、このフィールドには、繰り返しルールに基づいて、次回のトリガー日時か直近のトリガー日時のどちらかが含まれます。
    定期的なリマインダーの再生後、トリガーされた時刻からデバイスで次回のインスタンスがスケジュールされるまでの間には、遅延が生じることが想定されています。この遅延時間中、scheduledTimeは次回の繰り返しの時刻ではなく、直近のトリガー日時を返します。繰り返し間隔が長い場合、デバイスは次回のインスタンスを3～4時間後にスケジュールします。間隔が短い場合、スケジュールは通常1時間以内に設定されます。

文字列

timeZoneId

（オプション）タイムゾーンを指定します。America/New_Yorkなどを指定できます。
trigger.typeがSCHEDULED_RELATIVEの場合は適用されません。
設定されていない場合、Alexaはエンドポイント受信者のタイムゾーンを使用します。
タイムゾーンの詳細については、絶対時刻のタイムゾーンを参照してください。
有効な値については、List of tz database time zonesを参照してください。

文字列

recurrence

（オプション）定期的に繰り返されるリマインダーの繰り返し情報を指定します。
trigger.typeがSCHEDULED_ABSOLUTEの場合に適用されます。

Recurrenceオブジェクト

このページは役に立ちましたか？

最終更新日: 2025 年 08 月 14 日