Skip to content

Commit

Permalink
小微Skill 文档更新
Browse files Browse the repository at this point in the history
  • Loading branch information
@llyanlin
llyanlin committed Jun 20, 2018
1 parent eff28c7 commit 6652d16
Show file tree
Hide file tree
Showing 2 changed files with 227 additions and 48 deletions.
89 changes: 72 additions & 17 deletions product/大数据与AI/腾讯云小微/小微Skill/操作指南/创建自定义类接口参考.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
本节描述发送到您的服务的请求的格式。

### HTTP 头
```
```json
POST / HTTP/1.1
Content-Type : application/json;charset=UTF-8
Host : your.application.endpoint
Expand All @@ -17,8 +17,7 @@ Accept-Charset : utf-8
### 请求正文语法

发送到您的服务的请求正文是 JSON 格式。

```
```json
{
"version": "string",
"session": {
Expand All @@ -36,7 +35,8 @@ Accept-Charset : utf-8
"consentToken": "string"
},
"accessToken": "string"
}
},
"reqDeviceId" : "string"
},
"context": {
"System": {
Expand All @@ -55,7 +55,19 @@ Accept-Charset : utf-8
}
}
},
"request": {}
"request": {
"dialogState": "COMPLETED",
"intent": {
"confirmationStatus": "NONE",
"name": "QuerySomething",
"slots": null
},
"isUp": 0, //请求 PlayList 数据时才用到：1 请求之前的数据，0 请求后面的数据，默认为 0,当 lastPlayId 为空时没有意义，开发者自行决定是请求之前的数据还是后面的数据
"lastPlayId": "", //请求 PlayList 数据时才用到，表示最后一条播放资源的 ID，默认为空
"requestId": "q3dj417m-dny9-230c-8rc2-8r0nqm518642",
"timestamp": "2018-04-11T09:49:33+08:00",
"type": "IntentRequest"
}
}
```

Expand All @@ -66,19 +78,21 @@ Accept-Charset : utf-8
| --- | --- | --- |
| version | 请求的版本说明符，其值定义为：“1.0” | string |
| session | 会话对象提供与请求相关联的附加上下文。| object |
| context | 上下文对象在您的请求发送到您的服务时向您提供有关腾讯云小微服务和设备的当前状态的信息。这包括在所有请求中。对于在会话（LaunchRequest 和 IntentRequest）上下文中发送的请求，上下文对象复制会话中可用的用户和应用程序信息。对于上下文对象的定义，请参阅上下文对象。| object |
| context | 上下文对象在您的请求发送到您的服务时，向您提供有关腾讯云小微服务和设备的当前状态的信息。这包括在所有请求中。对于在会话（LaunchRequest 和 IntentRequest）上下文中发送的请求，上下文对象复制会话中可用的用户和应用程序信息。对于上下文对象的定义，请参阅上下文对象。| object |
| request | 提供用户请求详细信息的请求对象。有几种不同的请求类型可以使用，请参阅：标准请求(Standard Requests) 包括启动请求(LaunchRequest)、意图请求(IntentRequest)、会话结束请求(SessionEndedRequest)。| object |

#### 会话(*session*)对象
标准请求类型（LaunchRequest，IntentRequest和SessionEndedRequest）包括会话对象。context.System.user 和 context.System.application 对象在会话中提供与相同对象相同的用户和应用程序信息(请参阅上下文(*context*)对象)。

| 参数 | 描述 | 类型 |
| --- | --- | --- |
| new | 一个布尔值，指示这是否是一个新的会话。对于新会话返回 true，对于现有会话返回 false。| boolean |
| 参数 | 描述 | 类型 |
|---------|---------|---------|
| new | 一个布尔值，指示这是否是一个新的会话。 对于新会话返回 true，对于现有会话返回 false。| boolean |
| sessionId | 一个字符串，表示每个用户的活动会话的唯一标识符。| string |
| attributes | 键值对映射。对于新会话已启动的请求，属性映射为空，属性 new 设置为 true。键是一个表示属性名称的字符串， 类型：字符串。该值是表示属性值的对象，类型：对象。返回响应时，可以在会话中包含 sessionAttributes 属性中需要持久化的数据。然后，您提供的属性将在下一个请求中传回您的技能。| object |
| application | 包含应用程序 ID 的对象。这是用来验证请求是否适用于您的服务：applicationId：表示您的技能的应用程序 ID 的字符串。该信息也可以在 context.System.application 属性中使用。您的技能的应用程序 ID 显示在开发人员门户的“技能信息”页面上。| object |
| user | 描述发出请求的用户的对象。用户由以下组成：userId：表示发出请求的用户的唯一标识符的字符串。此标识符的长度可以有所不同，但不能超过 255 个字符。当用户启用腾讯云小微应用程序的技能时，userId 将自动生成。注意：禁用和重新启用技能将生成新的标识符。accessToken：标识另一个系统中的用户的令牌。仅当用户已成功关联其帐户时才提供此功能。该信息也可以在 context.System.application 属性中使用。| object |
| attributes | 键值对映射。对于新会话已启动的请求，属性映射为空，属性 new 设置为 true。键是一个表示属性名称的字符串，类型：字符串。该值是表示属性值的对象，类型：对象。返回响应时，可以在会话中包含 sessionAttributes 属性中需要持久化的数据。然后，您提供的属性将在下一个请求中传回您的技能。| object |
| application | 包含应用程序ID的对象。这是用来验证请求是否适用于您的服务：applicationId：表示您的技能的应用程序 ID 的字符串。该信息也可以在 context.System.application 属性中使用。您的技能的应用程序 ID 显示在开发人员门户的“技能信息”页面上。| object |
| user | 描述发出请求的用户的对象。 用户由以下组成：userId：表示发出请求的用户的唯一标识符的字符串。 此标识符的长度可以有所不同，但不能超过255个字符。 当用户启用腾讯云小微应用程序的技能时，userId 将自动生成。注意：禁用和重新启用技能将生成新的标识符。accessToken：标识另一个系统中的用户的令牌。 仅当用户已成功关联其帐户时才提供此功能。 该信息也可以在 context.System.application 属性中使用。| object |
| reqDeviceId | 一个字符串，表示发出请求设备的唯一标识符。| string |


#### 上下文(*context*)对象
标准请求类型（LaunchRequest，IntentRequest和SessionEndedRequest）包括会话对象。context.System.user 和 context.System.application 对象在会话中提供与相同对象相同的用户和应用程序信息。
Expand All @@ -98,7 +112,7 @@ Accept-Charset : utf-8
## 响应格式

本节描述您的服务返回的响应格式。腾讯云小微技能的服务必须以JSON格式发送其回复。请注意响应的以下大小限制：
*outputSpeech* 响应不能超过 8000 个字符。*card* 中包含的所有文字不能超过 8000 个字符。这包括*title*， *content*， *text*，和图片地址。图像URL（smallImageUrl 或 largeImageUrl）不能超过 2000 个字符。您的响应的总大小不能超过 24kb。如果您的响应超过这些限制，则腾讯云小微服务返回错误。
*outputSpeech* 响应不能超过 8000 个字符。*card* 中包含的所有文字不能超过 8000 个字符。这包括*title*， *content*， *text*，和图片地址。图像 URL（smallImageUrl 或 largeImageUrl）不能超过 2000 个字符。您的响应的总大小不能超过 24kb。如果您的响应超过这些限制，则腾讯云小微服务返回错误。

### HTTP头

Expand Down Expand Up @@ -167,9 +181,11 @@ Content-Length:

| 参数 | 描述 | 类型 | 必需 |
| --- | --- | --- | --- |
| type | 包含要呈现的输出语音类型的字符串。有效的类型有：“PlainText”：表示输出语音被定义为纯文本。“SSML”：表示输出语音是用SSML标记的文本。| string | 是 |
| text | 包含要呈现给用户的语音的字符串。当类型为“PlainText”时使用此选项 | string | 是（对于PlainText） |
| ssml | 包含标有 SSML 的文本的字符串，以呈现给用户。当类型为“SSML”时使用此选项 | string | 是（对于SSML） |
| type | 包含要呈现的输出语音类型的字符串。 有效的类型有：“PlainText”：表示输出语音被定义为纯文本。“SSML”：表示输出语音是用SSML标记的文本。“PlayList”：表示输出播放列表。| string | 是 |
| text | 包含要呈现给用户的语音的字符串。 当类型为“PlainText”返回纯文本文字。当类型为“PlayList”时返回播放列表的Json String | string | 是（对于PlainText和PlayList）|
| ssml | 包含标有SSML的文本的字符串，以呈现给用户。 当类型为“SSML”时使用此选项 | string | 是（对于SSML）|
| more | 当类型为“PlayList”时表示是否还有数据 | bool | 是（对于PlayList）|


#### 卡片(*Card*)对象
只有在发送对 LaunchRequest 或 IntentRequest 的响应时，才能包含此对象。
Expand All @@ -180,7 +196,7 @@ Content-Length:
| title | 包含卡片标题的字符串。（不适用于 LinkAccount 类型的卡）。| string | 否 |
| content | 包含 Simple 卡内容的字符串（不适用于 Standard 或 LinkAccount 类型的卡）。| string | 否 |
| text | 包含标准卡的文本内容的字符串（不适用于 Simple 或 LinkAccount 类型的卡） | string | 否 |
| image | 一个图像对象，指定要在标准卡上显示的图像的URL。仅适用于 Standard 类型的卡。您可以提供两个 URL，用于不同大小的屏幕。smallImageUrl largeImageUrl | object | 否 |
| image | 一个图像对象，指定要在标准卡上显示的图像的URL。仅适用于 Standard 类型的卡。您可以提供两个 URL，用于不同大小的屏幕。smallImageUrl、largeImageUrl | object | 否 |

#### *Reprompt*对象
只有在发送对 LaunchRequest 或 IntentRequest 的响应时，才能包含此对象。
Expand Down Expand Up @@ -229,3 +245,42 @@ Content-Length:
}
}
```
播放列表的返回数据示例

```json
{
"response": {
"outputSpeech": {
"more": true,
"text": "[{"url":"http://isure.stream.qqmusic.qq.com/C2000032qfIn1Tzdbq.m4a?guid=2000001761&vkey=A99417E1ACF19E6CC24CB6637DD0124CF8073C8F667666798CD01A06076B71371045FC7E7598D4EF6AA1C70674293AE22501400A7D371719&uin=&fromtag=50","id":"unique_id=99388&p=0&uuid=774","name":"来生缘","author":"刘德华","album_name":"来生缘","album_pic_url":"http://y.gtimg.cn/music/photo_new/T002R500x500M000004A6KAD4ZoIub.jpg"},{"url":"http://isure.stream.qqmusic.qq.com/C200001QrG450Xz77g.m4a?guid=2000001761&vkey=C22A8D122CC31DC122AE6F1EA8818CF392B584F7144F14D87E5BEE4E2649BEF8393F713F8F9256679A3F4F69BB6DF29B281B887B770DD955&uin=&fromtag=50","id":"unique_id=99388&p=0&uuid=775","name":"吻别","author":"刘德华","album_name":"爱如此神奇","album_pic_url":"http://y.gtimg.cn/music/photo_new/T002R500x500M000002poFpm3AdEuF.jpg"}]",
"type": "PlayList"
},
"shouldEndSession": true
},
"version": "1.0"
}
```

PlayList播放示例详解

```json
[
{
"url": "http://isure.stream.qqmusic.qq.com/C2000032qfIn1Tzdbq.m4a?guid=2000001761&vkey=A99417E1ACF19E6CC24CB6637DD0124CF8073C8F667666798CD01A06076B71371045FC7E7598D4EF6AA1C70674293AE22501400A7D371719&uin=&fromtag=50", //播放地址
"id": "unique_id=99388&p=0&uuid=774", //资源ID
"name": "来生缘", //资源名称
"author": "刘德华", //演奏者
"album_name": "来生缘", //专辑名称
"album_pic_url": "http://y.gtimg.cn/music/photo_new/T002R500x500M000004A6KAD4ZoIub.jpg"//专辑封面
},
{
"url": "http://isure.stream.qqmusic.qq.com/C200001QrG450Xz77g.m4a?guid=2000001761&vkey=C22A8D122CC31DC122AE6F1EA8818CF392B584F7144F14D87E5BEE4E2649BEF8393F713F8F9256679A3F4F69BB6DF29B281B887B770DD955&uin=&fromtag=50",
"id": "unique_id=99388&p=0&uuid=775",
"name": "吻别",
"author": "刘德华",
"album_name": "爱如此神奇",
"album_pic_url": "http://y.gtimg.cn/music/photo_new/T002R500x500M000002poFpm3AdEuF.jpg"
}
]

```
Loading

0 comments on commit 6652d16

Please sign in to comment.