あなたのAlexaコンソール
?
サポート

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

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

スキルメッセージAPIは、スキルにメッセージリクエストを送信するために使用します。

関連トピック:AlexaスキルのスキルイベントAlexaスキルのリストイベントスキルにメッセージを送信するようアプリケーションやサービスを設定する

北米(NA)およびヨーロッパ(EU)のPOSTコマンド

apiEndpoint値から構築する最後のPOSTコマンドは、以下の形式で記述します。1つ目は米国のエンドポイント、2つ目はヨーロッパのエンドポイントです。

    POST api.amazonalexa.com/v1/skillmessages/users/{userId}

    POST api.eu.amazonalexa.com/v1/skillmessages/users/{userId}

スキルイベントを使用するスキルの場合、使用するエンドポイントは、このユーザーのイベントで送信されたapiEndpoint値に基づいています。

スキルメッセージAPIの使い方

指定されたユーザーのスキルにメッセージリクエストを送信するにはスキルメッセージAPIを使います。

スキルメッセージAPIは非同期です。正常な応答とは、メッセージが受け取られ、スキルに送信されるキューに入ることです。受け取ったメッセージをスキルに配信するためには、スキルのエンドポイントを使用する必要があります。スキルのエンドポイントが使用できない場合、メッセージはexpiresAfterSecondsフィールドに指定された期間、定期的に試行を繰り返します(指定されていない場合、デフォルトの有効期間が使われます)。正常な配信には、スキルがコンテキストを「継承」し、メッセージを確認しなければなりません。

スキルがオンラインの場合、メッセージは処理と同時に配信されます。メッセージ配信のタイミングや順序は保証されません。呼び出し元はメッセージを受信するスキルの所有者でもあるため、呼び出し元がスキルにメッセージが配信されたかどうかを判断します。配信メカニズムには受信確認機能はありません。呼び出し元は、複数のリクエストが送信された場合の重複メッセージの処理も行います。

スキルメッセージAPIのcURLメッセージリクエストのサンプル

ALEXA_USER_ID='ReplaceWithUserId'
SKILL_MESSAGING_TOKEN='ReplaceWithToken'
MESSAGE='{"data":{ "sampleMessage": "Sample Message"}, "expiresAfterSeconds": 60}'
API_URL=https://api.amazonalexa.com/v1/skillmessages/users/$ALEXA_USER_ID

 curl -v -s -k -X POST \
      -H "Authorization: Bearer $SKILL_MESSAGING_TOKEN" \
      -H "Content-Type: application/json" \
      -d "$MESSAGE" \
      $API_URL

 

スキルメッセージAPIのパラメーター

 
名前 位置 必須 説明
userId パス 文字列 スキルユーザーのIDです。このIDは、Alexaが送信するリクエストで提供されるuserIdと同じです。指定されたスキルの有効なユーザーでなければなりません。
skillMessagingToken ヘッダー 文字列 認可APIから提供されるトークンです。ベアラータイプのトークンです。例: Authorization: Bearer Atz|zzzzbbbccc
message 本文 オブジェクト

スキルに送信するメッセージで、以下のような形式になります。

{
    data:{ },
    expiresAfterSeconds: integer
}

Messageオブジェクト

パラメーター 説明
data JSON 必須です。メッセージと一緒に送信するペイロードデータです。データは、JSON形式のキーと値のペアで指定します。キーと値は文字列型にする必要があります。データ全体のサイズは6KB以下です。データサイズには、キーと値、それらを囲む引用符、キーと値を区切る「:」、ペア間を区切るカンマ、フィールドを囲む中括弧も含みます。ただし、キー/値ペア間のスペースはペイロードサイズには含まれません。同期メッセージなど、メッセージにペイロードデータがない場合、次のように空のオブジェクトとして渡すことができます。 "data":{}
expiresAfterSeconds 整数 任意です。メッセージの配信に失敗した場合に再試行のために、メッセージを保持する秒数です。60(1分)以上86400(1日)以下の値を指定できます。デフォルトは3600(1時間)です。この期間中、複数回再試行されます。
再試行のロジックは、等比級数的に増加します。最初の再試行が30秒後に行われ、再試行の回数ごとにその間隔が倍になっていきます。再試行はメッセージの最初の配信からの合計経過時間が、expiresAfterSecondsに指定された値を超えたときに終了します。
メッセージハンドラーが適切にセットアップされていれば、メッセージの有効期限切れが問題になることはまずありません。正しくセットアップが行われていれば、1回ですぐにメッセージを受信できます。この再試行メカニズムは、メッセージの配信中にスキルがダウンした場合のセーフガードとなります。

(スキルメッセージAPIへのリクエストに対する)応答

 
コード 説明 ヘッダー
202メッセージは正常に受け取られ、スキルに送信されます。X-Amzn-RequestID

X-Amzn-RequestIDオブジェクト

名前 説明
X-Amzn-RequestID文字列リクエストを一意に識別する作成値です。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

 

エラーコード

コード エラー 説明
400 不正なリクエスト データが存在しないか、有効ではありません。
403許可されないリクエストskillmessagingTokenが期限切れか、有効ではありません。
404見つかりませんuserIdが存在しません。
429メッセージレートが超過しています。リクエストが、メッセージのレートの最大値を超過しました。
500内部サービス例外

スキルでメッセージを受信する

権限を付与するためにスキルを有効にして、スキルに対応するアプリケーションを設定した後は、スキルのサービス(AWS Lambdaまたはウェブサービス)が、受信したサービスの処理方法を認識していることを確認してください。 Messaging.MessageReceived は、スキルが受信する他のリクエストと同様のリクエストタイプです。標準のリクエスト形式の詳細については、カスタムスキルのJSONインターフェースリファレンスを参照してください。

スキルサービスはスキルメッセージAPIに確認応答を送信する必要があります

セッション外のメッセージの場合、スキルのサービス(AWS Lambdaまたはウェブサービス)はメッセージを受信したという確認応答をスキルメッセージAPIに送信する必要があります。確認応答が返されない場合、APIは有効期間が切れるまでメッセージを送信し続けます。

Node.jsを使用している場合、メッセージを処理した後にcontext.succeed();を呼び出して確認応答を送信します。別の言語の場合、確認応答として空の成功メッセージを送信します。

メッセージの受信後に他のAPI呼び出しを行う際に、これらのAPIリクエストが同期的に戻された後もコンテキストを継承することが重要です。詳細については、AWS Lambdaのドキュメントに記載されたNode.js ランタイム v0.10.42 のコンテキストメソッドを参照してください。

Messaging.MessageReceivedリクエストタイプ

Messaging.MessageReceivedリクエストタイプはスキルエンドポイントによって処理される必要があります(AWS Lambdaかウェブサービスいずれの場合にも適用)。リクエストはインテントの一種です。このため、このリクエストタイプでは、スキルにハンドリングメソッドを追加する必要があります。詳細については、カスタムスキルのJSONインターフェースのリファレンスの「リクエストのフォーマット」を参照してください。

リクエストMessageRequest
インターフェースメッセージ
定義
"request": {
    "type": "Messaging.MessageReceived",
    "requestId":"string",
    "timestamp":"string",
    "message": <object>
	}
アトリビュートメッセージ:バックエンドのサードパーティアプリケーションによって提供されるメッセージのブロブです。システムでのメッセージブロブのサイズは最大6KBです。

以下の例にあるMessaging.MessageReceivedリクエストサンプルでは、permissionsオブジェクトのconsentTokenを使用しています。セッション外のメッセージリクエストでは、ユーザーが同意した場合、ユーザーの同意を含むconsentTokenがスキルに提供されます。詳細については、カスタムスキルのJSONインターフェースのリファレンスの「Contextオブジェクト」を参照してください。

同意トークンの有効期間は60分です。永続性を持たせるべきではありません。同意トークンは、スキルメッセージAPIが新しいセッション内リクエストまたはセッション外リクエストを受信するたびに、自動的に更新されます。

userIdは、スキルユーザーのスキル有効化の期限が切れるまで有効です。ユーザーがスキルを無効にして再度有効にした場合、userIdは変更されます。そのため、ユーザーが次にスキルを使用するとき、そのユーザーは新しいユーザーとして認識されます。新しいユーザーの場合と同様、セッション外でのメッセージの送信に使用できるよう、userIdをセッションで記録しておく必要があります。スキルメッセージのエンドポイント(/skillmessages/users/{userId})を呼び出すのにスキルメッセージAPIが使用された場合、404エラー(userIdが見つかりません)が発生し、そのuserIdはシステムで有効ではなくなります。

リクエスト内のContextオブジェクトのapiEndpoint値

以下の例にあるIntentRequestサンプルでは、SystemオブジェクトのapiEndpoint値を使用しています。値は、ユーザーの場所によって変わります。詳細については、カスタムスキルのJSONインターフェースのリファレンスの「Contextオブジェクト」を参照してください。

北米(NA)のユーザーヨーロッパ(EU)のユーザー
https://api.amazonalexa.comhttps://api.eu.amazonalexa.com

Messaging.MessageReceivedリクエストにPermissionsフィールドを含める

Amazon開発者ポータルで権限を有効にしている場合、Messaging.MessageReceivedリクエストごとにpermissionsフィールドが含まれます。ユーザーが権限に同意していない場合、このフィールドには入れ子になっているconsentTokenフィールドは含まれません。ただし、スキルに同意トークンが必要な場合、スキルは権限カードをスローして、ユーザーに権限の承認を求めるプロンプトを表示しなければなりません。詳細については、ユーザー同意をリクエストする新しい権限カードを参照してください。

permissionsフィールドについては、以下のMessaging.MessageReceivedリクエストサンプルを参照してください。

Messaging.MessageReceivedリクエストのサンプル

この例では、IDは変更され、切り捨てられています。

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.b4277435"
      },
      "user": {
        "userId": "amzn1.ask.account.AGQ3PQ",
        "permissions": {
         "consentToken": "ZZZZZZZ..."
        }
      },
      "apiAccessToken": "AxThk...",
      "request": {
        "type": "Messaging.MessageReceived",
        "requestId": "amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
        "timestamp": "2015-05-13T12:34:56Z",
        "message": {
          "notice": "<< text of message >>"
        }
      }
    }
  }
}

権限サポートありのIntentRequestのサンプル

{
  "version": "1.0",
  "session": {
    "new": false,
    "sessionId": "amzn1.echo-api.session.0000000-0000-0000-0000-00000000000",
    "application": {
      "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
    },
    "attributes": {
      "supportedHoroscopePeriods": {
        "daily": true,
        "weekly": false,
        "monthly": false
      }
    },
    "user": {
      "userId": "amzn1.account.AM3B00000000000000000000000"
    }
  },
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
      },
      "user": {
        "userId": "amzn1.account.AM3B00000000000000000000000"
      },
	  "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "IntentRequest",
    "requestId": " amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
    "timestamp": "2015-05-13T12:34:56Z",
    "intent": {
      "name": "GetZodiacHoroscopeIntent",
      "slots": {
        "ZodiacSign": {
          "name": "ZodiacSign",
          "value": "virgo"
        }
      }
    }
  }
}

 

ユーザー同意をリクエストする新しい権限カード

apiAccessTokenはスキルに対するすべてのリクエストに含まれます。これは、ユーザーがリクエストを完了するのに必要な権限をスキルに付与したかどうかは関係ありません。そのため、スキルがリクエストを完了するのに必要な正しい権限セットが、トークンに含まれていない可能性があります。スキルは特別な権限カードを表示して、ユーザーに動的に同意を求めることができます。

新しいカードAskForPermissionsConsentCard
インターフェースCardRenderer
定義
{
    "type": "AskForPermissionsConsent",
    "permissions": << list of scope strings >>
}
アトリビュートpermissions:Alexaの権限にマッピングされるスコープ文字列のリストを含みます。スキルに必要で、かつAmazon開発者ポータルのスキルメタデータで宣言されたAlexa権限のみが含まれます。

apiAccessTokenはすべてのスキルリクエストに含まれるため、apiAccessTokenが存在するかどうかで必要な権限があるかどうかを判断することはできません。代わりにAPIを呼び出して、レスポンスコードを確認します。スキルに権限がない場合は403 Forbiddenの応答が返されるため、その時点でAlexaへの応答にAskForPermissionsConsentカードを含めることができます。

権限カードありの応答のサンプル

セッション内の対話で、新しいAskForPermissionsConsentカードを含む応答を返すことができます。以下は、書き込み権限をリクエストするカードに対する一般的な応答です。

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
           "write::alexa:household:list"
      ]
    }
  }
}

permissionsの値は、Amazon開発者ポータルのエンドポイントページでスキルに対して宣言したスコープと同じです。