获取用户信息协议
当技能为用户提供个性化服务时,需要使用用户的个人信息。例如技能向用户推荐附近的美食时需要知道用户的地址信息,向用户邮箱推送用户关注的资讯时需要用户的邮箱信息。技能只有经过用户的授权才能使用用户的信息。本文将详细地介绍技能如何获取用户授权,以及如何请求用户百度账号信息、请求用户地理位置信息及请求用户打印机服务。使用本文提供的API接口前,请先阅读如何申请及使用用户信息了解用户授权的整体流程。
目录
申请用户信息权限
技能使用用户信息时,需要通过用户的授权。技能可以通过向DuerOS发送Permission.AskForPermissionsConsent指令获取用户的权限。当收到用户响应时,DuerOS会向技能发送授权成功或授权失败事件。
Permission.AskForPermissionsConsent指令
技能向DuerOS发送该指令,请求获取用户信息的权限。
协议格式
{
"type": "Permission.AskForPermissionsConsent",
"permissions": [
{
"name": "{{ENUM}}"
},
...
],
"token": "{{STRING}}"
}
参数说明
- type
- 请求授权类型名称,这里去固定值Permission.AskForPermissionsConsent。
- permissions[].name
- 权限名称。支持以下权限。
- 'READ::USER:PROFILE':表示百度账号用户信息的权限,包括昵称、邮箱、电话、头像。
- 'READ::DEVICE:LOCATION':表示用户地理位置信息的权限。
- 'WRITE::SMARTHOME:PRINTER':调用智能家居打印机打印的权限。
- 权限名称。支持以下权限。
- token
- 权限token,指令的唯一标识。
用户授权响应事件
当用户响应技能发出的申请权限的消息时,例如用户同意技能的申请或用户不同意,DuerOS会把用户的确认情况上报给技能。包括授权成功和授权失败两种事件。
授权成功事件
当技能申请用户信息权限成功时,DuerOS会向技能上报授权成功事件。
消息格式
{
"type": "Permission.Granted",
"requestId": "{{STRING}}",
"timestamp": "{{STRING}}",
"token": "{{STRING}}",
"permissions": ["{{ENUM}}"...]
}
参数说明
- type
- 上报事件类型,这里取固定值Permission.Granted。
- requestId
- 标识本次事件请求的唯一ID。
- timestamp
- 请求时间戳,单位是秒。
- token
- 权限token,指令的唯一标识。
- permissions
- 用户同意授权的权限数组,枚举类型,支持以下权限。
- 'READ::USER:PROFILE':表示百度账号用户信息的权限,包括昵称、邮箱、电话、头像。
- 'READ::DEVICE:LOCATION':表示用户地理位置信息的权限。
- 'WRITE::SMARTHOME:PRINTER':调用用户智能打印机的权限。
- 用户同意授权的权限数组,枚举类型,支持以下权限。
授权失败事件
当技能申请用户权限失败时,DuerOS会向技能上报授权失败事件。
消息格式
{
"type": "{{STRING}}",
"requestId": "{{STRING}}",
"timestamp": "{{STRING}}",
"token": "{{STRING}}"
}
参数说明
- type
- 上报事件类型。有以下两种类型
- Permission.Rejected:表示用户拒绝授权。
- Permission.GrantFailed:表示用户同意授权,但是由于其他原因导致授权失败。
- 上报事件类型。有以下两种类型
- requestId
- 标识本次事件请求的唯一ID。
- timestamp
- 请求时间戳,单位是秒。
- token
- 权限token,指令的唯一标识。
获取用户百度账号信息
当技能需要使用用户百度账号信息才能为用户提供服务时,技能会请求获取用户的信息。技能在每次提供服务时,都会发起申请,获取用户最新的数据。
请求获取用户百度账号信息
技能在获得用户百度账号信息权限后可以通过调用该接口获取用户的基础信息(昵称、手机号、邮箱、头像)。
消息样式
method = GET
host = {{apiEndpoint}}
path = /saiya/v1/user/profile
Authorization: Bearer {{apiAccessToken}}
参数说明
- Authorization
- apiAccessToken:用于身份和权限校验的access token,在LaunchRequest请求中获取。
参考样例
curl -X GET \
'https://xiaodu.baidu.com/saiya/v1/user/profile' \
-H 'authorization: bearer uLr0rabWoR95WEpeAJrOrdjthrIx90oACd/...'
返回请求消息
当DuerOS收到技能发送的请求用户百度账号信息后,会将处理结果返回给技能。
消息样式
{
"status": {{INT}},
"message": "{{STRING}}",
"data": {
"nickname": "{{STRING}}",
"phone": "{{STRING}}",
"email": "{{STRING}}",
"portrait": "{{STRING}}"
}
}
参数说明
- status
- 消息状态,0表示信息获取成功。非0表示消息异常。
- message
- 消息提示信息。当状态码为0时,提示获取用户信息成功。当状态码为非0时,返回对应的错误消息。
- data
- 返回用户信息。
- data.nickname
- 用户昵称。
- data.phone
- 用户手机号。
- data.email
- 用户邮箱。
- data.portrait
- 用户头像。
状态码及对应的提示信息说明
status | message | 描述 |
---|---|---|
0 | ok | 成功获取用户信息。 |
1 | The method is not supported. | 消息请求方法不支持。 |
2 | The authorization token is invalid. | Authorization没有定义或者非法。 |
5 | The authorization token doesn’t have access to the resource. | 没有获取用户信息的权限。 |
获取用户地理位置信息
技能提供的一些服务需要用户提供地理位置信息,如为用户查询“附近的餐厅”,此时技能可以通过下面的接口获取用户的地理位置信息(即智能设备的地理位置信息)。
请求消息
技能可以通过向DuerOS发送该请求获取用户的地理位置信息。
method = GET
host = {{apiEndpoint}}
path = /saiya/v1/devices/location
Authorization: Bearer {{apiAccessToken}}
参数说明
- Authorization
- apiAccessToken:用于身份和权限校验的access token,在LaunchRequest请求中获取。
参考样例
curl -X GET \
'https://xiaodu.baidu.com/saiya/v1/devices/location'\
-H 'authorization: Bearer ETKRs98nQy1S5hRUz/X3BH+2/H5EUKRmopyUnuosG6d+vAOcir+sG...'
返回消息
DuerOS收到地理位置信息请求后,会向技能返回处理结果。
数据格式
{
"status": {{INT32}},
"msg":{{STRING}},
"data":{
"geo":{
"wgs84":{
"longitude":{{DOUBLE}},
"latitude":{{DOUBLE}}
},
"bd09ll":{
"longitude":{{DOUBLE}},
"latitude":{{DOUBLE}}
},
"bd09mc":{
"longitude":{{DOUBLE}},
"latitude":{{DOUBLE}}
}
},
"country":{{STRING}},
"province":{{STRING}},
"city":{{STRING}},
"district":{{STRING}},
"street":{{STRING}},
"address":{{STRING}},
"sematicDescription":{{STRING}}
},
"logId":{{STRING}}
}
参数说明
- status
- 消息响应状态,0表示获取地理位置信息成功。非0表示获取设备地理位置信息失败。
- message
- 消息提示信息。当状态码为0时,提示获取设备地理信息成功。当状态码为非0时,返回对应的错误消息。
- data
- 地理位置数据信息。
- data.geo.wgs84
- GPS定位经纬度,请阅读百度地图坐标了解该参数的具体含义。
- data.geo.bd09ll
- 百度经纬度坐标,请阅读百度地图坐标了解该参数的具体含义。
- data.geo.bd09mc
- 百度墨卡托米制坐标,请阅读百度地图坐标了解该参数的具体含义。
- data.country
- 地理位置信息中的国家信息。
- data.province
- 地理位置信息中的省份信息。
- data.city
- 地理位置信息中的城市信息。
- data.district
- 地理位置信息中的行政区信息。
- data.street
- 地理位置信息中的街道信息。
- data.address
- 地理位置信息中的详细地址信息。
- data.sematicDescription
- 地理位置信息的语义化描述。
- logId
- 标识本次请求的唯一ID。
状态码及对应的提示信息说明
status | message | 描述 |
---|---|---|
0 | ok | 成功获取设备地理位置信息。 |
1 | The method is not supported. | 消息请求方法不支持。 |
2 | The authorization token is invalid. | Authorization没有定义或者非法。 |
5 | The authorization token doesn’t have access to the resource. | 没有获取用户地理位置信息的权限。 |
11 | no data. | 没有返回用户地理位置信息。 |
说明:
- 如果用户通过小度在家设备发出与位置相关的请求时,技能获取的是小度在家设备的地理位置,定位方式采用百度地图WIFI定位模式,定位精度20m。
- 如果用户通过小度音箱设备发出与位置相关的请求时,技能获取的位置是通过手机APP定位的位置,该位置依赖于手机系统,不能保证精度。
获取打印机服务
技能在获取打印机权限后,可以通过调用以下接口请求打印服务。
请求打印机服务消息
技能向DuerOS发送该消息,请求打印机服务,消息中包含打印资源内容。
请求消息
method = POST
host = {{apiEndpoint}}
path = /saiya/v1/smarthome/printer
Authorization: Bearer {{apiAccessToken}}
参数说明
- Authorization
- apiAccessToken:用于身份和权限校验的access token,在LaunchRequest请求中获取。
请求参数
{
"fileSourceUrl": "{{STRING}}",
"fileName": "{{STRING}}",
"mediaSize": "{{ENUM}}",
"color": {{BOOLEAN}},
"copies": {{INT32}}
}
参数说明
- fileSourceUrl
- 打印资源的URL地址。支持".jpeg"、".jpg"、".png"、".gif"格。资源的URL地址示例"http://www.234.cn/uploadfile/image/20140410111022_9402.jpg"。
- fileName
- 打印资源的名称,可选,默认使用系统提供的名称。
- mediaSize
- 打印纸张的尺寸大小,可选,支持以下规格,默认值是IsoA4_210x297mm。
- IsoA3_420x297mm
- IsoA4_210x297mm
- IsoA5_148x210mm
- 打印纸张的尺寸大小,可选,支持以下规格,默认值是IsoA4_210x297mm。
- color
- 是否使用彩色打印,布尔类型,默认值是false。
- true:表示使用彩色打印。
- false:表示使用黑白打印。
- 是否使用彩色打印,布尔类型,默认值是false。
- copies
- 打印份数,默认值是1。
参考样例
curl -X POST \
'https://xiaodu.baidu.com/saiya/v1/smarthome/printer' \
-H 'authorization: Bearer ETKRs98nQy1S5hRUz/X3BH+2...' \
-H 'content-type: application/json' \
-d '{
"fileSourceUrl": "http://www.234.cn/uploadfile/image/20140410111022_9402.jpg",
"fileName": "XYZ",
"mediaSize": "IsoA4_210x297mm",
"color": false,
"copies": 1
}'
返回消息
当DuerOS收到请求打印机服务消息后,会根据打印机响应情况,将处理结果返回给技能。
消息样式
{
"status": {{INT32}},
"message": "{{STRING}}",
"data":{
"copies" : {{INT32}}
},
"logId":"{{STRING}}"
}
参数说明
- status
- 消息响应状态,0表示打印请求成功。非0表示打印请求失败。
- message
- 消息提示信息。当状态码为0时,提示打印请求成功。当状态码为非0时,返回对应的错误消息。
- data
- 返回打印数据。
- data.copies
- 成功打印的页数。
- logId
- 标识本次请求的唯一ID。
状态码及对应的提示信息说明
status | message | 描述 |
---|---|---|
0 | ok | 请求打印服务成功。 |
1 | The method is not supported. | 请求方法不支持。 |
2 | The authorization token is invalid. | Authorization没有定义或者非法。 |
3 | Param Error. | 消息请求参数错误。 |
5 | The authorization token doesn’t have access to the resource. | 不能访问打印资源。 |
11 | no data | 没有返回打印相关数据。 |