Alexa.ProactiveNotificationSourceインターフェース



Alexa.ProactiveNotificationSourceインターフェース

確認が必要なデバイスがあることをユーザーに通知するには、AlexaスキルにAlexa.ProactiveNotificationSourceインターフェースを実装します。たとえば、洗濯機のサイクルが完了したときや、掃除機のダストケースがいっぱいになったときなどにユーザーに通知できます。

スキル内でデバイスのお知らせを有効にします。ただし、Alexaがユーザーに通知を送信する前に、ユーザーがAlexaアプリでデバイスのお知らせを有効にする必要があります。ユーザーは、すべてのEchoデバイス(Echo Dot、Echo Plus、Echo Show、Echo Spotなど)にAlexaが送信するお知らせを有効にできます。

ProactiveNotificationSourceインターフェースは、デバイスに機能を提供するほかのインターフェースと共に実装します。現時点では、ProactiveNotificationSourceは以下の汎用コントローラーインターフェースのいずれかと共に使用する必要があります。

ユーザーへの通知は、「<コントローラーインスタンスのフレンドリー名>が<状態>です」という形式になります。次に例を示します。

Alexa: ダストケースがいっぱいです。

ChangeReportsイベントを送信してお知らせをトリガーします。

セマンティクスを使用してお知らせを有効にする

セマンティクスを使用して、お知らせを有効にできます。セマンティクスを使用する場合、次のAlexa.States値のいずれかに、デバイスの状態を手動でマッピングします。

  • Alexa.States.Low
  • Alexa.States.Empty
  • Alexa.States.Full
  • Alexa.States.Done
  • Alexa.States.Stuck

ModeControllerの場合は、modeプロパティをいずれかの状態にマッピングします。RangeControllerの場合は、rangeValueプロパティをいずれかの状態にマッピングします。プロパティ値を状態にマッピングするには、次のセクションで説明するように、検出応答にsemanticsオブジェクトを含めます。

後で、ユーザーがデバイスを操作するときに、ChangeReportイベントをAlexaに送信します。AlexaにChangeReportイベントを送信するとき、Alexa.States値のいずれかにマッピングされたプロパティ値がこのイベントに含まれていると、Alexaはユーザーへの通知をトリガーします。ChangeReportの例については、変更レポートを参照してください。

検出

Alexa.ProactiveNotificationSourceインターフェースをサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。

ProactiveNotificationSourceの場合は、通常の検出応答フィールドのほかに、notificationConditionsという名前の配列を含むconfigurationオブジェクトを含めます。配列内の各オブジェクトに含まれるフィールドを以下の例に示します。

フィールド 説明 必須
conditionType 通知をトリガーする条件のタイプ。有効な値はPropertyValueChangeのみです。 文字列
property 通知をトリガーするプロパティ。 オブジェクト
valueChangeCondition 通知をトリガーする条件。条件は、comparatorフィールドとvalueフィールドを含むオブジェクトです。comparatorの有効な値はStateEqualsのみです。 オブジェクト

検出応答の例

以下は、ProactiveNotificationSourceインターフェースを使用する衣類乾燥機のDiscover.Responseメッセージの例です。この例では、ModeControllerインターフェースの3つのインスタンス(乾燥温度、乾燥サイクル、糸くずフィルター)を使用します。ここでは、ProactiveNotificationSourceインターフェースを使用して、2つのコントローラーに対して有効になっているお知らせの例を示します(乾燥サイクルの終了をユーザーに通知、糸くずフィルターがいっぱいになったことをユーザーに通知)。

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

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "<メッセージID>"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "<エンドポイントの一意のID>",
                "manufacturerName": "<衣類乾燥機のメーカー>",
                "description": "<乾燥機メーカー>のスマート衣類乾燥機",
                "friendlyName": "乾燥機",
                "displayCategories": [
                    "DRYER"
                ],
                "additionalAttributes": {
                    "manufacturer" : "<衣類乾燥機のメーカー>",
                    "model" : "サンプルモデル",
                    "customIdentifier": "<デバイスのカスタム識別子>"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "instance": "Dryer.Temperature",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "retrievable": true,
                            "proactivelyReported": true,
                            "nonControllable": false
                        },
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "text",
                                "value": {
                                    "text": "温度",
                                    "locale": "ja-JP"
                                }
                            }]
                        },
                        "configuration": {
                            "ordered": true,
                            "supportedModes": [{
                                    "value": "Dryer.Temperature.Cool",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "低温",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "Dryer.Temperature.Warm",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "中温",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "Dryer.Temperature.Hot",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "高温",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "instance": "Dryer.CurrentDryerCycle",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "retrievable": true,
                            "proactivelyReported": true,
                            "nonControllable": true
                        },
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "text",
                                "value": {
                                    "text": "現在の乾燥サイクル",
                                    "locale": "ja-JP"
                                }
                            }]
                        },
                        "configuration": {
                            "ordered": true,
                            "supportedModes": [{
                                    "value": "CurrentDryerCycle.NotStarted",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "開始前",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "CurrentDryerCycle.Drying",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "乾燥中",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "CurrentDryerCycle.CoolDown",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "クールダウン",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "CurrentDryerCycle.Completed",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "完了",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                }
                            ]
                        },
                        "semantics": {
                            "stateMappings": [{
                                "@type": "StatesToValue",
                                "states": [
                                    "Alexa.States.Done"
                                ],
                                "value": "CurrentDryerCycle.Completed"
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "instance": "Dryer.LintTrap",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "retrievable": true,
                            "proactivelyReported": true,
                            "nonControllable": true
                        },
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "text",
                                "value": {
                                    "text": "糸くずフィルター",
                                    "locale": "ja-JP"
                                }
                            }]
                        },
                        "configuration": {
                            "ordered": false,
                            "supportedModes": [{
                                    "value": "Dryer.LintTrap.Clean",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "クリーン",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "Dryer.LintTrap.Medium",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "ミディアム",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "Dryer.LintTrap.Full",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "フル",
                                                "locale": "ja-JP"
                                            }
                                        }]
                                    }
                                }
                            ]
                        },
                        "semantics": {
                            "stateMappings": [{
                                "@type": "StatesToValue",
                                "states": [
                                    "Alexa.States.Full"
                                ],
                                "value": "Dryer.LintTrap.Full"
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ProactiveNotificationSource",
                        "version": "3.0",
                        "proactivelyReported": true,
                        "configuration": {
                            "notificationConditions": [{
                                    "conditionType": "PropertyValueChange",
                                    "property": {
                                        "type": "AlexaInterface",
                                        "interface": "Alexa.ModeController",
                                        "instance": "Dryer.CurrentDryerCycle",
                                        "name": "mode"
                                    },
                                    "valueChangeCondition": {
                                        "comparator": "StateEquals",
                                        "value": "Alexa.States.Done"
                                    }
                                },
                                {
                                    "conditionType": "PropertyValueChange",
                                    "property": {
                                        "type": "AlexaInterface",
                                        "interface": "Alexa.ModeController",
                                        "instance": "Dryer.LintTrap",
                                        "name": "mode"
                                    },
                                    "valueChangeCondition": {
                                        "comparator": "StateEquals",
                                        "value": "Alexa.States.Full"
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、状態および変更レポートについてを参照してください。

乾燥サイクル完了のChangeReportイベントの例

このChangeReportにより、次の通知が生成されます。 Alexa: 現在の乾燥サイクルが完了しました。

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

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.ModeController",
            "instance": "Dryer.CurrentDryerCycle",
            "name": "mode",
            "value": "CurrentDryerCycle.Completed",
            "timeOfSample": "2017-02-03T16:20:50Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
  }
}

ダストケースがいっぱいの場合のChangeReportイベントの例

このChangeReportにより、次の通知が生成されます。 Alexa: ダストケースがいっぱいです。

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.RangeController",
            "instance": "Vacuum.Bin",
            "name": "rangeValue",
            "value": "95",
            "timeOfSample": "2017-02-03T16:20:50Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {}
}