スキルメッセージREST APIリファレンス

スキルメッセージREST APIリファレンス

スキルメッセージREST APIを使えば、指定したユーザーへの非同期メッセージをアプリやサービスからAlexaスキルに送信できます。APIリクエストを受信したら、Alexaはメッセージを受け取ってアプリに応答します。その後、Alexaはメッセージを配信キューに入れ、スキルへのメッセージ配信を試行します。

Alexaがスキルに配信するメッセージの詳細については、スキルで受信したメッセージを処理するを参照してください。

APIエンドポイント

スキルのリージョンに基づいて、以下のエンドポイントのいずれかを使用します。

  • 北米：https://api.amazonalexa.com
  • ヨーロッパ：https://api.eu.amazonalexa.com
  • 極東：https://api.fe.amazon.com

認証

スキルメッセージAPIをサードパーティのアプリやサービスからセッション外に送信します。APIを呼び出す前に、スキルにアクセスするためのアクセストークンを取得する必要があります。詳細については、スキルにメッセージを送信するようアプリケーションやサービスを設定するを参照してください。

操作

スキルメッセージAPIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

スキルにメッセージを送信する

POST /v1/skillmessages/users/{userId}

スキルにメッセージを送信する

指定したユーザーへの非同期メッセージをAlexaスキルに送信します。APIリクエストを受信したら、Alexaはメッセージを受け取ってスキルへの配信を試行します。

リクエスト

スキルにメッセージを送信するには、skillmessages/usersリソースにPOSTリクエストを行います。

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

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

POST /v1/skillmessages/users/{userId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

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

パラメーター 位置 説明 型 必須

userId

パス

ユーザーを識別します。userIdは、access_tokenで識別されるスキルの有効なユーザーに対応している必要があります。
このIDの値は、Alexaからスキルに送信されるリクエストで指定されるcontext.System.user.userIdと同じです。

文字列

◯

access token

ヘッダー

スキルにアクセスするためのベアラートークンです。

文字列

◯

リクエスト本文の例

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

{
    "data": {
        "sometag": "何らかのメッセージ"
    },
    "expiresAfterSeconds":60
}

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

プロパティ 説明 型 必須

data

Alexaがスキルへのメッセージに含めるペイロードを定義します。ペイロードを含めない場合、空のオブジェクトを含めます。
有効な値： 文字列型のJSON形式のキー／値ペアです。
最大サイズ： 6KB（引用符、コンマ、括弧を含む）。

JSONオブジェクト

〇

expiresAfterSeconds

メッセージが正常に配信されなかった場合にメッセージを保持する秒数です。デフォルト値は3600秒（1時間）です。
有効な値： 1～86400秒。

Alexaは、指数バックオフを使用してメッセージ配信を再試行します。Alexaは、30秒後に再試行し、再試行するごとに間隔を2倍に延長します。メッセージ受信後の経過時間合計がexpiresAfterSecondsの値を超えたら、Alexaは再試行を停止し、メッセージの保持を解除します。スキルはすみやかに応答を送信する必要があります。

整数

✕

応答

成功時の応答はHTTP 202 Acceptedです。この応答は、Alexaがメッセージを受け取り、スキルへの配信キューに追加したことを示します。この応答はAlexaがメッセージを配信したことを意味するものではありません。また、配信に成功しても、Alexaはスキルに受信確認を送信しません。メッセージ配信の詳細については、スキルで受信したメッセージを処理するを参照してください。エラーの場合、応答は適切なHTTPステータスコードを返します。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

202 Accepted

メッセージが受け取られ、スキルへの配信キューに追加されました。メッセージを配信するには、スキルのエンドポイントを利用できる必要があります。エンドポイントを利用できない場合、AlexaはexpiresAfterSeconds秒の間、再試行します。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

指定されたuserIdが見つかりません。

429 Too Many Requests

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

500 Server Error

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

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

最終更新日: 2024 年 02 月 28 日

DevAssistant