Alexa.ChangeReportインターフェース

Alexa.ChangeReportインターフェース

プロパティの更新をAlexaにプロアクティブにレポートするには、スキルにAlexa.ChangeReportイベントを実装します。たとえば、ユーザーが手動で照明を点灯したとします。このとき、照明の状態が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"
                    }
                ]
            }]
        }
    }
}

ChangeReportイベント

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

.

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-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2022-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2022-02-03T16:20:50.52Z",
                "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開発者向け問い合わせ窓口にお問い合わせください。

エラー応答の例

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

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": "The access token is invalid, expired, or malformed."
  }
}

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

最終更新日: 2022 年 05 月 25 日