Alexa.ChangeReportインターフェース3

Alexa.ChangeReportインターフェース3

プロパティの更新をAlexaにプロアクティブにレポートするには、スキルにAlexa.ChangeReportイベントを実装します。たとえば、ユーザーが手動で照明を点灯したとします。このとき、照明の状態がAlexaアプリに正しく反映されるように、変更レポートを送信します。

変更レポートの詳細については、状態および変更レポートについてを参照してください。

メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。

検出

検出中に、スキルでサポートしているインターフェースと、各インターフェースのレポート可能なプロパティを特定します。インターフェースにproactivelyReported = trueを設定すると、スキルはそのインターフェースのプロパティに何らかの変更があるたびにAlexa.ChangeReportイベントをAlexaに送信します。

検出応答の例

以下は、照明を制御するAlexaスキルのDiscover.Responseメッセージの例です。このスキルは、Alexa.PowerController、Alexa.BrightnessController、Alexa.EndpointHealthの各インターフェースをサポートしています。powerState、brightness、connectivityは出力可能なプロパティです。

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

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "一意の識別子、バージョン4 UUIDが望ましい"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "照明エンドポイントの一意ID",
                "manufacturerName": "エンドポイントのメーカー名",
                "description": "Alexaアプリに表示される説明",
                "friendlyName": "リビングの照明",
                "displayCategories": ["LIGHT"],
                "additionalAttributes": {
                    "manufacturer": "エンドポイントのメーカー名",
                    "model": "デバイスのモデル",
                    "serialNumber": "デバイスのシリアル番号",
                    "firmwareVersion": "デバイスのファームウェアバージョン",
                    "softwareVersion": "デバイスのソフトウェアバージョン",
                    "customIdentifier": "デバイスの任意のカスタム識別子"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.PowerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "powerState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.BrightnessController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "brightness"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

変更レポート

エンドポイントの状態の変化をプロアクティブに出力するには、Alexa.ChangeReportイベントを送信します。検出時にインターフェースのプロパティをproactivelyReportedとして指定した場合、そのプロパティ値が変更されたときはAlexaにAlexa.ChangeReportイベントを送信する必要があります。状態の変化がAlexaからのディレクティブによって発生した場合は、ディレクティブ応答と変更レポートイベントの両方を送信します。Alexa.ChangeReportイベントを、非同期的にAlexaイベントゲートウェイに送信します。

Alexaにデバイスの健全性を通知する場合、Alexa.EndpointHealthインターフェースを実装してください。

.

ChangeReportイベントの例

以下は、スキルからAlexaにプロアクティブに送信するAlexa.ChangeReportイベントの例です。endpointIdはデバイスを識別し、scopeはユーザーを識別します。この例では、スキルはデバイスの物理的な操作によってpowerStateプロパティがONに変わったことをレポートします。contextオブジェクトには、変更されていないプロパティの状態も含めます。

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

POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json
{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "照明エンドポイントID"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.PowerController",
                    "name": "powerState",
                    "value": "ON",
                    "timeOfSample": "2022-02-03T08:10:00.10Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2022-02-01T08:00:00.10Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2022-02-03T08:00:00.10Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

ChangeReportイベントのプロパティ

プロパティ 説明 型 必須

event

レポートのユーザーとエンドポイントを識別します。新しいプロパティ値と変更の理由をpayloadに格納します。payloadオブジェクトには、少なくとも1つのプロパティを含める必要があります。

Eventオブジェクト

◯

context

レポート可能なほかのすべてのプロパティの状態をレポートします。これらのプロパティとその値をproperties配列に列挙します。

Contextオブジェクト

◯

Payloadオブジェクト

Payloadオブジェクトには、スキルがレポートする変更の理由と変更されたプロパティ値のリストを含めます。プロパティを追加するには、検出応答でそのプロパティをproactivelyReported = trueとして定義する必要があります。Payloadオブジェクトには、変更されたプロパティ値のみを含めます。

プロパティ 説明 型 必須

change

変更の詳細を識別します。

オブジェクト

◯

change.cause

1つ以上のプロパティの変更の理由です。

Causeオブジェクト

◯

change.properties

変更されたプロパティのリストです。変更されたプロパティごとに1つのオブジェクトを含めます。

Propertyオブジェクトの配列

◯

Causeオブジェクト

以下の表は、Causeオブジェクトのプロパティを示しています。

プロパティ 説明 型 必須

type

変更の原因を識別します。

Type文字列

◯

Type値

プロパティの値が変更された理由を説明するには、次のいずれかのtype値を使用します。

CauseオブジェクトのType値 説明

APP_INTERACTION

ユーザーによるデバイスアプリの操作です。たとえば、デバイス製造元から提供されたアプリを使用して、ユーザーが照明を点灯したりドアをロックした場合です。

PERIODIC_POLL

エンドポイントの定期的なポーリングです。たとえば、温度センサーを1時間に1回ポーリングして、更新された温度をAlexaに送信できます。

PHYSICAL_INTERACTION

エンドポイントの物理的な操作です。たとえば、ユーザーが手動で照明を点灯したり、ドアをロックしたりします。

VOICE_INTERACTION

ユーザーとAlexaとの対話です。たとえば、ユーザーがEchoデバイスに話しかけて照明を点灯したり、Alexaアプリを使用して照明を消したりします。

ChangeReport応答

成功すると、Alexaは、イベントが受け入れられて詳しい論理検証と処理が行われることを示す202 Acceptedを送信します。イベントが受け付けられない場合、Alexaは適切なHTTPステータスコードを送信します。

応答本文のパラメーター

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

HTTPステータスコード

次の表は、スキルがAlexaイベントゲートウェイから受け取る可能性のあるHTTPステータスコードの一覧です。エラーを受け取った場合は、payloadオブジェクトにcodeフィールドとdescriptionフィールドが含まれます。これらのフィールドはログ記録の目的でのみ使用してください。

ステータス ペイロードのコード 説明

202 Accepted

—

リクエストは認可され、メッセージは構文的に有効なイベントでした。ゲートウェイはイベントを受け付け、論理的な検証と処理に進みます。

400 Bad Request

INVALID_REQUEST_EXCEPTION

メッセージが無効です。フィールドがない、値が正しくない、正しいJSON形式ではないことが原因です。ドキュメントと照合して、メッセージにすべての必須フィールドが含まれていることを確認します。

401 Unauthorized

INVALID_ACCESS_TOKEN_EXCEPTION

メッセージに認可トークンが含まれていないか、トークンが無効、有効期限切れ、形式が正しくないのいずれかです。トークンを更新して、リクエストを再試行してください。ユーザーがスキルを無効にすると、アクセストークンも無効になります。この場合は、ユーザーが認可を取り消したため、変更レポートの送信も停止できます。

403 Forbidden

SKILL_NEVER_ENABLED_EXCEPTION

イベントゲートウェイへのアクセスが許可されていません。イベントを正しいリージョンのエンドポイントに送信していることを確認してください。たとえば、北米のイベントは北米のエンドポイントに送信します。

403 Forbidden

INSUFFICIENT_PERMISSION_EXCEPTION

トークンに必要な権限がありません。スキルにAlexaイベントを送信する権限があることを確認してください。詳細については、Alexaイベントゲートウェイへのアクセス権限のリクエストを参照してください。

404 Not Found

ACCOUNT_NOT_FOUND_EXCEPTION

指定されたIDに関連付けられたアカウントレコードが存在しないか、期限が切れています。このエラーは、イベントの送信が遅すぎた場合や、無効なIDが指定された場合に発生する可能性があります。指定されたIDと認可コードが正しいことを確認してください。

404 Not Found

SKILL_NOT_FOUND_EXCEPTION

このトークンに関連付けられたスキルIDが見つかりませんでした。このエラーは、スキルが認定中などの異なるステージにある状況でユーザーのアクセストークンが生成された場合に発生します。このユーザーでスキルの無効化と有効化を行ってみてください。

413 Payload Too Large

REQUEST_ENTITY_TOO_LARGE_EXCEPTION

イベントペイロードのサイズが大きすぎます。1回のリクエストで許容されるエンドポイントの最大数は300です。より小さいペイロードでメッセージを送信してください。

429 Too Many Requests

THROTTLING_EXCEPTION

リクエスト数が多すぎます。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。

500 Internal Server Error

INTERNAL_SERVICE_EXCEPTION

Alexaでエラーが発生したため、メッセージは処理されませんでした。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。

503 Service Unavailable

SERVICE_UNAVAILABLE_EXCEPTION

Alexaがメッセージを受け取れませんでした。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。

応答本文401 Unauthorizedの例

以下は、エラー応答の例です。

HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
  },
  "payload": {
      "code": "INVALID_ACCESS_TOKEN_EXCEPTION",
      "description": "アクセストークンが無効、有効期限切れ、形式が正しくないのいずれかです。"
  }
}

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

最終更新日: 2024 年 11 月 08 日