AliGenie.Discovery 接口描述了用以识别与用户帐户关连设备的信息。设备技能必须要能够处理并且正确的回复discovery指令好让用户或精灵服务端能够取得欲控制的设备信息，技能服务端也应该再某些时候主动上报关于用户帐户下关于增加、更新与删除设备的事件。
当技能收到此指令时，技能需要对用户帐户进行设备发现，并将帐户下的设备回报给精灵服务。如果找不到任何设备、用户的access token过期、或有任何与用户帐户相关的错误发生的话，技能应该要在 Discover.Response 中回复一个空的设备数组，而非错误信息。
Discover 指令{
"directive": {
"header": {
"namespace": "AliGenie.Discovery",
"name": "Discover",
"payloadVersion": "1",
"messageId": "abc-123-def-456"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
}
}
}
}
Discovery请求的payload中只会包含一个 scope 对象。Scope提供了要求厂商进行设备操作的用户授权信息。
BearerToken - 提供了用以访问已绑定的厂商帐户的OAuth bearer token。关于如何响应此接口，技能服务端可以：
Discover 指令同步的回复Discovery.Response事件。AddOrUpdateReport 与 DeleteReport 事件给精灵服务的TOP接口。无
在此回复中需包含与该用户帐户所关连的所有设备信息，例如像是每个设备的：
如果该帐户下没有发现到任何设备，或是你的服务发生了错误，则应该回传一个空的 endpoints 数组。
Discover.Response{
"event": {
"header": {
"namespace": "AliGenie.Discovery",
"name": "Discover.Response",
"payloadVersion": "1",
"messageId": "abc-1234-xyz-7890"
},
"payload": {
"endpoints": [
{
"endpointId": "car-001",
"friendlyName": "My Car",
"description": "My Car by The Car Manufacturer",
"manufacturerName": "The Car Manufacturer",
"displayCategories": [
"CONNECTED_CAR"
],
"cookie": {},
"capabilities": [
{
"type": "AliGenieInterface",
"interface": "AliGenie.ConnectedCar",
"version": "1",
"properties": {
"supported": [
{
"name": "fuelLevel"
},
{
"name": "batteryLevel"
},
{
"name": "remainingRange"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AliGenieInterface",
"interface": "AliGenie.ConnectedCar.LockController",
"version": "1",
"properties": {
"supported": [
{
"name": "lockState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AliGenieInterface",
"interface": "AliGenie",
"version": "1"
}
]
}
]
}
}
}
当用户增加了一台新设备到他们的帐户下，或对已存在的设备进行修改时 (例如更名)，需要技能服务主动像精灵服务上报此事件。此事件中需要包含的信息与 Discover.Response 非常类似，同样需要有唯一ID、用户友善的名称、设备支持的能力与能够被取得的属性等。
此事件为TOP接口调用 alibaba.ailabs.aligenie.discovery.addorupdatereport
| 栏位 | 描述 | 类型 | 必须 |
|---|---|---|---|
endpoints |
endpoint对象的数组。每个endpoint代表一个设备。 | 对象数组 | 是 |
| 栏位 | 描述 | 类型 | 必须 |
|---|---|---|---|
endpoint.endpointId |
设备ID。此ID必须对此技能全局唯一。 | 字串 | 是 |
endpoint.manufacturereName |
设备厂商名。此值不能超过128字符。 | 字串 | 是 |
endpoint.friendlyName |
顾客用来识别设备的名称。此值不能超过128字符，并且不能包含特殊符号。 | 字串 | 是 |
endpoint.description |
对此设备的描述。此值不能超过128字符。此描述应该包含厂商名称或此设备是如何连接的。 | 字串 | 是 |
endpoint.displayCategory |
表示此设备在精灵app上该如何显示。所指名的category会决定图标与在app中展示的设备细节。 | 字串数组 | 否 |
endpoint.cookie |
存放设备额外信息的map，API不会使用或解析其内容。 | 字串/值对映射 | 是 |
endpoint.capabilities |
表示特定设备所能支持与回应的操作的capability对象数组。每个capability对象可以依据类型以包含不同的栏位。 | 对象数组 | 是 |
| 值 | 描述 | 备注 |
|---|---|---|
| CONNECTED_CAR | 具有由云端被控能力的车 |
capability 对象| 栏位 | 描述 | 类型 | 必须 |
|---|---|---|---|
type |
表示能力的类型，其决定了该能力能有什么栏位。 | 字串“AliGenieInterface” | 是 |
interface |
接口的表示名称，描述对此设备的操作。 | 字串 | 是 |
version |
表示此endpoint所支持的接口版本。 | 字串 | 是 |
properties.supported |
表示此endpoint所能支持的接口的属性，以此格式显示: "name":"<propertyName>" |
字串 | 是 |
proactivelyReported |
表示此endpoint所列出的属性是否会产生 ChangeReport 事件。如果技能没有在此数组指明会上报事件的属性的话，则该属性的 proactivelyReported 与 retrievable 会被设为预设值false。 |
布尔值 | 否 |
retrievable |
表示此endpoint所列出的属性是否响应 StateReport 事件。如果技能没有在此数组指明会上报事件的属性的话，则该属性的 proactivelyReported 与 retrievable 会被设为预设值false。 |
布尔值 | 否 |
当用户从帐户中移除了一或多台设备时，技能服务需要主动向精灵服务上报此事件。
此事件为TOP接口调用 alibaba.ailabs.aligenie.discovery.deletereport