千里傳音播報服務與播報設備之間實現交互,完成智能語音播報,需要調用如下物模型服務。
服務列表
服務名稱 | 功能 | 是否必須 |
向設備推送更新語料的指令。 | 是 | |
向設備下發組合播報的語料組及語音播報順序的指令。 設備可無需返回應答,但參與吱音計劃的設備必須返回應答。 | 是 | |
向設備下發語音播報指令,并等待設備應答。 | 是 | |
使設備重播上一次組合播報內容。 | 否 | |
啟動設備進行指定語料組合的重復播報。 | 否 | |
停止設備進行固定語料組合的重復播報。 | 否 | |
按照語料標識,刪除設備內指定語料。 | 是 | |
將設備的本地語料中,來自千里傳音語音播報服務推送的語料全部刪除。 | 是 | |
拓展服務 | 方便千里傳音播報服務后續做功能拓展。 | 否 |
查看服務定義
登錄物聯網平臺控制臺。
在控制臺左上方,選擇物聯網平臺所在地域華東2(上海)。
在實例概覽頁簽的全部環境下,找到對應的實例,單擊實例卡片。
在左側導航欄,選擇 。
在產品列表中,單擊播報設備所屬產品對應操作列的查看。
在產品詳情頁面,單擊功能定義頁簽。
單擊服務類型對應功能名稱右側操作列的查看,可查看到對應功能定義的標識符、輸入參數、輸出參數等信息。
服務定義說明
語料內容下載地址:
物聯網平臺將待推送的語料地址記錄到一個JSON文件中,并將文件的URL推送至設備,設備解析文件后,根據不同語料的下載地址,完成下載后,將語料存放至本地,以便后續實現組合播報。
說明為了實現千里傳音服務的正確調用,下載的語料存放至本地的文件應使用語料標識進行命名,或者在播報設備中已實現語料標識與本地文件名的映射關系。
任務標識:
用于標識本次語料推送任務的ID號。在任務完成或發生錯誤時,需要通過該ID號向物聯網平臺云端反饋語料推送結果。
設備收到的數據示例
{ "method":"thing.service.SpeechPost", "id":"6835*", "params":{ "jobcode":"LJSdmPCIcG9js83R3IHc3GD6cbN*_16086091*", //任務標識 "url":"http://speech-solution.oss-cn-shanghai.aliyuncs.com/speech_post_content/hL7****gu7Auup1TQUMy4gEcFyQ/LJSdmPCIcG9js8****Hc3GD6cbN.json?Expires=16086&OSSAccessKeyId=LTAIN******&Signature=ivvUslTdFHqeUCsa0yBv%2FD****" //語料內容下載地址 }, "version":"1.0.0" }
URL下載文件內容示例
{ "audios":[ { "format":"wav", //本條語料的音頻格式 "id":"100wan", //本條語料標識 "size":69960, //本條語料的大小(字節數) "type":"custom", "url":"http://speech-solution.oss-cn-shanghai.aliyuncs.com/speech_model_audio/A96R0NcWiYoAXPSAuyfoLTG12nn*****/100wan.wav?Expires=1628949824&OSSAccessKeyId=LTAIN******S6P47&Signature=%2Bqk2bs********SfyoXU1Ugjxeg%3D" //語料下載地址 } ], "format":"wav", "size":69960 //本次推送的所有語料的總大小(字節數) }
標識符:SpeechBroadcast。
調用方式:異步。物聯網平臺執行調用后直接返回結果,不會等待設備的回復消息。
如果使用概述,請參考SDK中《data_model_basic_demo.c》文件中的異步調用回調函數實現異步調用。具體操作,請參見步驟四:設置屬性。
static void demo_dm_recv_async_service_invoke(void *dm_handle, const aiot_dm_recv_t *recv, void *userdata) { printf("demo_dm_recv_async_service_invoke msg_id = %ld, service_id = %s, params = %.*s\r\n", (unsigned long)recv->data.async_service_invoke.msg_id, recv->data.async_service_invoke.service_id, recv->data.async_service_invoke.params_len, recv->data.async_service_invoke.params); /* TODO: 以下代碼演示如何對來自云平臺的異步服務調用進行應答,用戶可取消注釋查看演示效果 * * 注意:如果用戶在回調函數外進行應答,需要自行保存msg_id,因為回調函數入參在退出回調函數后將被SDK銷毀,不可以再訪問到 */ /* { aiot_dm_msg_t msg; memset(&msg, 0, sizeof(aiot_dm_msg_t)); msg.type = AIOT_DMMSG_ASYNC_SERVICE_REPLY; msg.data.async_service_reply.msg_id = recv->data.async_service_invoke.msg_id; msg.data.async_service_reply.code = 200; msg.data.async_service_reply.service_id = "ToggleLightSwitch"; msg.data.async_service_reply.data = "{\"dataA\": 20}"; int32_t res = aiot_dm_send(dm_handle, &msg); if (res < 0) { printf("aiot_dm_send failed\r\n"); } } */ }
輸入參數:
參數名稱
說明
組合播報參數
內容播報:用JSON數組傳遞待播報語料的標識,將標識分別對應存儲在本地的語料段落。根據語料標識所屬數組下標順序,依次播報存儲在設備端的語料內容。
數字播報:與內容播報不同,數字播報不會逐個下發數字標識,而是下發特殊標識符
{}
來通知設備端進行數字播報。播報金額:格式為
{$***}
,例如{$123.4}
,則播放一百二十三點四元。播報數字:格式為
{N***}
,例如{N123.4}
,則播報一二三點四。
播報指令下發時間戳
播報指令下發時,物聯網平臺側的時間戳,為UTC時間戳格式。
播報標識
當前播報指令的消息ID,用于區分不同的播報指令,相同指令設備側只播報一次。
音頻格式
需要播報的語料的音頻格式,用于播報標識相同、格式不同的語料,支持:wav,mp3,amr。
返回參數:
參數名稱
說明
播報結果
設備端的實際播報結果。返回值如下:
0:語料播報成功。
1:語料已播報,重復播報。
2:語料不存在。
錯誤信息
用于向調用者返回具體的錯誤原因,您可按照實際情況自定義。
播報標識
需與輸入參數中的播報標識保持一致,用于返回本次播報調用相匹配的應答消息。
開始處理時間戳
設備開始處理播報請求的UTC時間戳,用于云端統計播報的指標。
處理完成時間戳
設備完成處理播報請求的UTC時間戳,用于云端統計播報的指標。
Topic:
/sys/${productKey}/${deviceName}/thing/service/SpeechBroadcast
。payload:
{ "method":"thing.service.SpeechBroadcast", "id":"4532*", "params":{ "format":"wav", //音頻格式 "speechs":[ "ZFBDZ", //組合播報參數,內容播報 "{$123}" //組合播報參數,播報金額 ], "id":"zGlLLH9GMhrWTwYWXppcvvM3****", //播報標識 "timestamp":"1608523503634" //播報指令下發時間戳 }, "version":"1.0.0" }
Topic:
/sys/${productKey}/${deviceName}/thing/service/SpeechBroadcast_reply
。payload:
{ "code":200, "data":{ "result":2, "error_message":"speech model not found", "task_id":"LH9GMhrWTwYWXppcvvM3****", "start_time":"1638179978545", "end_time":"1638179978545" }, "id":"4532*" }
返回參數:
參數
說明
code
固定值200,表示播報請求已處理。
id
消息ID,與設備收到的播報請求payload.id保持一致。
data
返回結果。詳細說明,請參見定義中的返回參數。
標識符:SyncSpeechBroadcast。
調用方式:同步。物聯網平臺會等待設備回復;若設備沒有回復,則調用超時。
對于同步服務,您需要通過RRPC方式進行回復。如果使用概述,請參考SDK中《data_model_basic_demo.c》文件中的同步調用回調函數實現。具體操作,請參見步驟四:設置屬性。
static void demo_dm_recv_sync_service_invoke(void *dm_handle, const aiot_dm_recv_t *recv, void *userdata) { printf("demo_dm_recv_sync_service_invoke msg_id = %ld, rrpc_id = %s, service_id = %s, params = %.*s\r\n", (unsigned long)recv->data.sync_service_invoke.msg_id, recv->data.sync_service_invoke.rrpc_id, recv->data.sync_service_invoke.service_id, recv->data.sync_service_invoke.params_len, recv->data.sync_service_invoke.params); /* TODO:以下代碼演示如何對來自云平臺的同步服務調用進行應答,用戶可取消注釋查看演示效果 * * 注意:如果用戶在回調函數外進行應答,需要自行保存msg_id和rrpc_id字符串,因為回調函數入參在退出回調函數后將被SDK銷毀,不可以再訪問到 */ /* { aiot_dm_msg_t msg; memset(&msg, 0, sizeof(aiot_dm_msg_t)); msg.type = AIOT_DMMSG_SYNC_SERVICE_REPLY; msg.data.sync_service_reply.rrpc_id = recv->data.sync_service_invoke.rrpc_id; msg.data.sync_service_reply.msg_id = recv->data.sync_service_invoke.msg_id; msg.data.sync_service_reply.code = 200; msg.data.sync_service_reply.service_id = "SetLightSwitchTimer"; msg.data.sync_service_reply.data = "{}"; int32_t res = aiot_dm_send(dm_handle, &msg); if (res < 0) { printf("aiot_dm_send failed\r\n"); } } */ }
輸入參數:
與組合播報中輸入參數相同,具體說明,請參見本文組合播報服務定義中的輸入參數。
輸出參數:
參數名稱
說明
播報結果
設備端的實際播報結果。返回值如下:
0:語料播報成功。
1:語料已播報,重復播報。
2:語料不存在。
錯誤信息
用于向調用者返回具體的錯誤原因,您可按照實際情況自定義。
播報標識
需與輸入參數中的播報標識保持一致,用于返回本次播報調用相匹配的應答消息。
播報結果詳情
返回播報時設備的信號強度,電池電量等信息,您可按照實際情況自定義。
開始處理時間戳
設備開始處理播報請求的UTC時間戳,用于云端統計播報的指標。
處理完成時間戳
設備完成處理播報請求的UTC時間戳,用于云端統計播報的指標。
Topic:
/ext/rrpc/${rrpcId}/sys/${productKey}/${deviceName}/thing/service/SyncSpeechBroadcast
。payload:
{ "method":"thing.service.SyncSpeechBroadcast", "id":"4532*", "params":{ "format":"wav", //音頻格式 "speechs":[ "ZFBDZ", //組合播報參數,內容播報 "{$123}" //組合播報參數,播報金額 ], "id":"zGlLLH9GMhrWTwYWXppcvvM3****", //播報標識 "timestamp":"1608523503634" //播報指令下發時間戳 }, "version":"1.0.0" }
Topic:
/ext/rrpc/${rrpcId}/sys/${productKey}/${deviceName}/thing/service/SyncSpeechBroadcast
。payload:
{ "code":200, "data":{ "result":2, "error_message":"speech model not found", "task_id":"LH9GMhrWTwYWXppcvvM3****", "start_time":"1638179978545", "end_time":"1638179978545" }, "id":"4532*" }
返回參數:
參數
說明
code
固定值200,表示播報請求已處理。
id
消息ID,與設備收到的播報請求payload.id保持一致。
data
返回結果。詳細說明,請參見定義中的返回參數。
播報語料標識列表:
用JSON數組傳遞需要重復播報語料的標識列表。
音頻格式:
需要重復播報語料的音頻格式,支持:wav,mp3,amr。
播報語料標識列表:
用JSON數組傳遞需要停止重復播報語料的標識列表。
音頻格式:
需要停止重復播報的語料的格式,支持:wav,mp3,amr。
語料標識:
需要刪除的語料的標識。
音頻格式:
需要刪除語料的音頻格式,支持:wav,mp3,amr。
語料推送
當您通過千里傳音播報服務向設備推送語料時,設備會收到來自物聯網平臺語料推送服務的調用。該服務需與事件上報配合使用,將語料推送結果通過事件上報的方式反饋給物聯網平臺。
定義
功能項 | 說明 |
標識符 | SpeechPost。 |
調用方式 | 異步。物聯網平臺執行調用后直接返回結果,不會等待設備的回復消息。 |
輸入參數 |
語料推送結果
語料推送結果需通過事件上報的方式反饋給物聯網平臺。具體請參見事件上報。
當設備上報執行結果后,千里傳音播報服務控制臺語料推送任務看板的狀態才會更新,否則即使語料推送成功,任務看板的狀態依然會顯示超時。
示例
組合播報
當用戶播報應用通過千里傳音播報服務向設備下達播報指令時,設備端會收到物聯網平臺組合播報服務的調用。無論調用組合播報API,還是共享組合播報API,設備都將收到組合播報服務的調用,無需分別對接。
定義
示例
設備收到數據示例
設備返回的數據示例
同步組合播報
相對于組合播報服務,同步組合播報服務要求設備端必須返回執行結果,如果物聯網平臺沒有收到返回結果,則會進行播報命令重試。
定義
示例
設備收到的數據示例
設備返回的數據示例
重播上一條
當您通過千里傳音播報服務向設備下達重播上一次組合播報內容的指令時,設備會收到物聯網平臺重播上一條服務的調用。
功能項 | 說明 |
標識符 | ReSpeechBroadcastLastOne。 |
調用方式 | 異步。物聯網平臺執行調用后直接返回結果,不會等待設備的回復消息。 |
輸入參數 | 無。 |
啟動重復播報
當您通過千里傳音播報服務啟動設備進行固定語料組合的重復播報動作時,設備會收到物聯網平臺啟動重復播報服務的調用。
功能項 | 說明 |
標識符 | StartSpeechBroadcastLoop。 |
調用方式 | 異步。物聯網平臺執行調用后直接返回結果,不會等待設備的回復消息。 |
輸入參數 |
停止重復播報
當您通過千里傳音播報服務停止設備進行固定語料組合的重復播報動作時,設備會收到物聯網平臺停止重復播報服務的調用。
功能項 | 說明 |
標識符 | StopSpeechBroadcastLoop。 |
調用方式 | 異步。物聯網平臺執行調用后直接返回結果,不會等待設備的回復消息。 |
輸入參數 |
批量刪除語料
當您通過千里傳音播報服務刪除設備內指定語料時,設備會收到物聯網平臺批量刪除語料服務的調用。調用成功后,您可以在千里傳音控制臺對設備中的語料進行管理。
定義
功能項 | 說明 |
標識符 | DeleteSpeech。 |
調用方式 | 異步。物聯網平臺執行調用后直接返回結果,不會等待設備的回復消息。 |
輸入參數 | 語料列表:需要刪除的語料標識列表,用JSON數組傳遞。 |
示例
設備收到的數據示例:
{
"method":"thing.service.DeleteSpeech",
"id":"189604****",
"params":{
"speechs":[
{
"format":"wav", //音頻格式
"id":"SYS_T**E_0" //語料標識
},
{
"format":"wav",
"id":"SYS_T**E_TIME_ri"
}
]
},
"version":"1.0.0"
}
刪除所有推送語料
刪除所有由物聯網平臺云端推送的語料,以釋放本地存儲資源。該服務對接后,可以在千里傳音控制臺實現對設備存儲的管理。
當您需要刪除千里傳音播報服務推送至設備中的所有語料時,設備會收到物聯網平臺刪除所有推送語料服務的調用。
功能項 | 說明 |
標識符 | ClearAllSpeechModelByPost。 |
調用方式 | 異步。物聯網平臺執行調用后直接返回結果,不會等待設備的回復消息。 |
輸入參數 | 音頻格式:需要刪除的語料音頻格式。 支持:wav,mp3,amr。 示例:如果傳入mp3,則刪除設備內所有mp3格式的語料。 |
Topic說明
服務下行調用:
/sys/${productkey}/${deviceName}/thing/service/${tsl.service.identifier}
。服務返回應答:
為了更好地了解服務調用的設備端執行情況,對應異步服務需要通過Topic返回應答。
/sys/${productkey}/${deviceName}/thing/service/${tsl.service.identifier}_reply
。
其中:
${productkey}
、${deviceName}
:替換為具體設備的證書信息。${tsl.service.identifier}
:服務標識符。例如:組合播報為SpeechBroadcast。
使用說明
阿里云OpenAPI開發者門戶提供API在線調試工具。您可以模擬云端對設備進行服務調用,驗證對物聯網平臺云端服務調用的響應是否正確。
物聯網平臺OpenAPI使用說明和使用方法,請參見使用OpenAPI和使用OpenAPI示例。