## 2.1 硬件接口調用 >本節著重介紹如何使用如意API調用硬件接口，其中包含服務地址、調用實例、主要參數以及相關字段說明。另外介紹了事件接口以及接口返回狀態說明。 ruyi-api 采用 restful-api 的方式為一切可接入網絡的軟硬件提供語義理解和解析服務，利用基于HTTP協議的API調用可以輕松傳遞自然語言原文，并實時獲取最新的語義解析結果。 **注：** 智能硬件客戶和微信公眾號客戶結果輸出對應不同的字段。 微信端結果對應 outputs[0].type == wechat.text(文本)/wechat.music（音頻）/wechat.news(圖文）等。 硬件端結果對應：outputs[1].type == dialog(文本)，區分不同類型（文本，音頻，圖文）根據type字段做解析，區分不同技能建議根據service字段做解析。  ### 2.1.1 API (v1.0.2) 服務的域名URL ``` http://api.ruyi.ai ``` ### 2.1.2 意圖識別接口 \(POST/message\) 該接口從中文自然語言文本提取實體和意圖為用戶提供服務。 **服務地址** ``` http://api.ruyi.ai/v1/message ``` **調用實例1** ``` curl 命令 > curl -H "Content-Type: application/json" -X POST --data @content.json http://api.ruyi.ai/v1/message content.json 內容 > cat content.json { "q": "你好", "app_key": "xxxx", "user_id": "xxxx", "reset_session": true, "context": { "location": { "latitude": "39.92", "longitude": "116.46" } } } ``` **調用實例2** POST方法用Json字符串不用URL Parameter  **參數說明** | Field | Type | Required | Description | | --- | --- | --- | --- | | q | String | Yes | 輸入中文自然語言文本，例如`"1-1等于幾"`。注意，所有字符串參數需要 URL-encoded. | | app\_key | String | Yes | 應用的開發者密鑰 | | user\_id | String | Yes | 用戶唯一標識，便于支持個性化語義解析。**建議開發者使用UUID字符，且不同用戶必須用不同的user\_id，防止意圖串。** | | reset\_session | Boolean | No | 如果為`true`，重置當前對話session，忘記短期對話記憶。 | | context | String | No | 用戶當前上下文信息。JSON字符串格式。 | **Context參數說明** | Field | Type | Required | Description | | --- | --- | --- | --- | | location | JSON Object | No | 用戶當前位置，`Location`實體的一個實例:`location:{"latitude": "31", "longitude": "121"}`,分別傳入經度和緯度數值。 | | reference\_time | Long | No | 用戶當前參照時間，unix時間毫秒 | | timezone | String | No | 用戶當前時區的標準ID字符串, 例如`"Asia/Shanghai"` | | ip | String | No | 用戶IP | **Context范例** ```json { "reference_time": 1447499684824, "timezone": "Asia/Shanghai", "location": { "latitude": "31.215", "longitude": "121.609" }, "ip": "0.0.0.0" } ``` ### 2.1.3 意圖識別結果及實例 (Intent) Intent 指一組對話，包含用戶說和機器人答。 **主要參數說明** Field | Type | Required | Description ------------ | ----------- | -------- | ------------------------ name | String | No | 意圖的名稱，自定義意圖的名稱可以在開發者后臺編輯 action | String | No | 觸發器的名稱，自定義觸發器的名稱可以在開發者后臺編輯 parameters | JSON Object | No | 意圖參數列表 result | JSON Object | No | 意圖執行結果 outputs | JSON Array | No | 微信端`type = wechat.text ` 輸出文本 `text = 早上好啊！`，硬件端` type=dialog `輸出文本`text = 早安，睡的好么`，同時，硬件端結果包含情感字段，"emotion"="positive"，代表機器人回答時的情感狀態。 emotion | string | No |機器人回答的情感字段 ***emotion字段說明*** emotion情緒狀態 | 場景 | text example-1 | text example-2 ------------ | ----------- | -------- | ---------------------------- calm</br>淡定 | 正常說話狀態（無情緒） | Q：你叫什么</br> A：我叫艾如意，想給我改名咩，對我說"以后我就叫你XXX"認領我吧~ | Q:李白 </br>A:李白（701－762）當然是大家公認的我國古代最偉大的天才詩人之一…… happy</br>喜悅|播放有趣的話；接收到一般性的贊賞語言 |Q:這件衣服漂亮嗎</br>A:你覺得漂亮就好，我支持你！ |Q:出門記得帶傘</br>A:好的呢！謝謝你！ excited</br>興高采烈|接收到特別的贊賞語言；智力問答收到正確回答 |Q:我們一起去打球吧？</br>A:好啊好啊！我要陪著你| Q:和我一起去學校好嗎</br>A:好呀好呀！一起去 despite</br>瞧不起|當機器人感到不滿需要反駁時 |我從未見過如此厚顏無恥之人！|有錢又怎么樣，我不需要錢，我需要電。 naughty</br>調皮|當接收到打趣，調侃的情緒時 |嘿嘿。你猜？|就不告訴你啦啦啦 worry</br>煩悶|當接收到消極情緒過多時|Q:你好蠢</br>A:對不起，我知道我還不夠聰明，但是我一直在努力學習，請你諒解。|你又罵我，寶寶好傷心。 sad</br>悲傷|當接收到在能力范圍之外的指令時|Q:你想認識我的小伙伴嗎</br>A:其實我認識的人不多|Q:你說什么呢？我沒有聽清楚</br>A:額，我也不記得了，下次記得仔細聽哦 like</br>喜愛|機器人反饋開心，喜歡等包含正面情緒時使用|Q:你今天開心嗎？</br>A:和你一起成長，每天都很開心|Q:你喜歡什么樣的女朋友</br>A:我喜歡的跟你一樣哦，很巧吧 angry</br>憤怒|接收到侮辱性語言|你怎么能隨便罵人呢！|這個問題你都問了八遍了，不理你了 surprise</br>驚奇|當接受到認知之外的信息時|Q:看見我媽媽了嗎？</br>A:怎么了呀，冷靜啊|不會吧，還有這樣的事？！ disappointed</br>失望|接受到出乎意料的負面情緒|沒想到你是這樣的人。|我講了那么多遍你還沒記住，你是不是根本不在乎我。 positive</br>確認|機器人反饋同意、好、OK、是、對等含確認意思時使用|Q:我去上學嘍</br>A:好的，回聊|Q:我可以問你一個問題嗎？</br>A:當然可以呀，你說吧 negative</br>否認|機器人反饋不同意、不好、No、不是、不對、錯誤、否等含否認意思時使用|Q:我去上學嘍</br>A:好的，回聊|Q:你的身高是多少？</br>A:不要這么在意外表嘛 confused</br>慌張|受到指責或者沒有答案的問題時使用|Q:你怎么什么都不會</br>A:沒有人生下來就會把，不會到會是個過程，我相信我可以|Q:你的家在哪里？</br>A:我也不太清楚我打哪兒來的 proud</br>驕傲|接收到夸獎和贊美的語言時|那可不是，寶寶可聰明著呢！|我聰明起來的時候無人能及。 suspect</br>疑問|返回有詢問含義的句子|Q:你知道這道題怎么算嗎</br>A:哪道題呀|Q:我錢包被偷了</br>A:好可憐，還好嗎？ #### 一個識別結果的實例 **訪問以下url** ``` http://api.ruyi.ai/v1/message?q=早安&app_key=APP_KEY&user_id=123456 ``` **返回結果** ```json { "code": 0, "msg": "ok", "result": { "_text": "早安", "msg_id": "5c439ac4-8efe-491c-b31a-fbd600811cfb", "intents": [{ "parameters": { "service": "chat_kids" }, "action": "早安", "name": "問候_早安", "result": { "text": "早上好，心情好嗎", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "早上好啊！" } }, { "type": "dialog", "property": { "text": "早安，睡的好么", "emotion": "calm" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "ecca5758-bbdf-4863-a5c1-d7089cc6f418" }], "meta_process_milliseconds": 65 } } ``` JSON 結果說明 Field | Explain ----------------------------- | ------------------------------------------------------------------------------------------- code | 請求成功返回`0`，其他結果參見錯誤碼說明 msg | 訪問成功則返回`"ok"`，其他結果參見返回狀態碼說明 result | 返回結果 result.msg_id | 為信息唯一識別碼 result._text | 原始輸入文本 result.intents | 包含意圖解析結果和返回結果 result.intents.0.parameters | 意圖識別結果, 其中`service`字段表示對應領域服務名稱 result.intents.0.outputs | 輸出結果，微信端結果對應"type"="wechat.text"下的“text”內容；硬件端結果對應 "type"="dialog"下的“text”內容，其中，硬件端結果包含情感字段，"emotion"="positive" 普通開發者解析其中的`"outputs"->"property"->"text"`字段即可得到機器人回答。 ### 2.1.4 事件接口 events 接口是用來向 ruyi.ai 反饋事件信息的接口，應用在諸如斷點播放、歌曲收藏等場景，通過該接口可以把事件信息傳遞給 ruyi.ai，然后 ruyi.ai 根據事件信息進行相應操作。 **接口地址** ``` http://api.ruyi.ai/ruyi-api/v1/events ``` **請求方法** `POST` **Header** | 名稱 | 值 | | :--- | :--- | | Content-Type | application/json | **請求參數** | 參數名 | 必選 | 類型 | 描述 | | --- | --- | --- | --- | | app\_key | 是 | String | 虛擬助理秘鑰,放入 query string 中 | | event | 是 | String | 事件類型，有聲斷點事件類型為“audio.xmly.break” | | entity\_type | 是 | String | 事件發生實體類型，有聲斷點事件為“user” | | entity\_id | 是 | String | 事件發生實體id，有聲斷點事件為用戶id | | target\_entity\_type | 是 | String | 事件目標實體類型，有聲斷點事件為"audio.xmly.track" | | target\_entity\_id | 是 | String | 事件目標實體id，有聲斷點事件為事件發生時播放資源的track\_id | | event\_time | 是 | String | 事件發生時的時間，為ISO 8601格式的字符串 | | detail | 是 | Object | 事件詳細信息，根據事件類型訂制 | **請求示例** `curl -XPOST http://api.ruyi.ai/ruyi-api/v1/events?app_key=xxx -H 'Content-Type:application/json' -d '` ``` { "event": "audio.xmly.break", "entity_type": "user", "entity_id": "u0", "target_entity_type": "audio.xmly.track", "target_entity_id": "3218935", "event_time": "2016-12-04T05:02:56.123+08:00", "detail": { "msg_id": "3d7e7533-94c3-4620-996e-c68541de853b", "album_id": "268522", "track_id": "3218935", "order_num": 0, "break_in_seconds": 145 } } ``` #### 有聲斷點事件請求參數 | 參數名 | 必選 | 類型 | 描述 | | --- | --- | --- | --- | | app\_key | 是 | String | 虛擬助理秘鑰,放入query string中 | | event | 是 | String | 事件類型，有聲斷點事件類型為“audio.xmly.break” | | entity\_type | 是 | String | 事件發生實體類型，有聲斷點事件為“user” | | entity\_id | 是 | String | 事件發生實體id，有聲斷點事件為用戶id | | target\_entity\_type | 是 | String | 事件目標實體類型，有聲斷點事件為"audio.xmly.track" | | target\_entity\_id | 是 | String | 事件目標實體id，有聲斷點事件為事件發生時播放資源的track\_id | | event\_time | 是 | String | 事件發生時的時間，為ISO 8601格式的字符串 | | detail | 是 | Object | 事件詳細信息，根據事件類型訂制 | **有聲斷點事件詳細信息** | 參數名 | 必選 | 類型 | 描述 | | -- | -- | -- | -- | | msg_id | 是 | String | message接口返回結果中的msg_id | | album_id | 是 | String | 斷點事件發生時播放資源的album_id | | track_id | 是 | String | 斷點事件發生時播放資源的track_id | | order_num | 是 | String | 斷點事件發生時播放資源的order_num | | break_in_second | 否 | String | 斷點事件發生時播放到了資源的多少秒，默認為"0" | **有聲斷點事件請求示例** `curl -XPOST http://api.ruyi.ai/ruyi-api/v1/events?app_key=xxx -H 'Content-Type:application/json' -d '` ```json { "event": "audio.xmly.break", "entity_type": "user", "entity_id": "u0", "target_entity_type": "audio.xmly.track", "target_entity_id": "3218935", "event_time": "2016-12-04T05:02:56.123+08:00", "detail": { "msg_id": "3d7e7533-94c3-4620-996e-c68541de853b", "album_id": "268522", "track_id": "3218935", "order_num": 0, "break_in_seconds": 145 } } ``` **有聲斷點events接口說明** 1. 音箱在播放一個有聲專輯時，在發送新的語義請求或者關機等需要記錄用戶當前播放斷點的情況下，調用`events`接口，傳入相應參數，`events`接口會保存斷點 2. ` events`接口會根據傳入的事件信息，把該用戶在該專輯播放的斷點記錄下來，在下次用戶請求播放該專輯時，我們根據專輯更新情況或者多輪的方式判斷該專輯是否需要斷點播放，如果需要，則返回該斷點的資源和之后一定數量資源的播放列表 3. `events`接口的參數目前均為必須參數，其中`app_key`放在`query string`中，其他參數放在請求體中，請求方法為`POST` 4. 有聲事件詳細信息所需要的`album_id`,`track_id`,`order_num`會在今天（12月2號）發版后加入有聲結果的`track_list`中，每個資源都會加上這三個字段。 5. `events`接口的所有參數的值都是`String`類型！ 6. 注意請求header的`Content-Type:application/json` ### 2.1.5 返回狀態及錯誤代碼 如意API返回 JSON 內各字段說明 Field | Type | Description ------------ | ----------- | ------------------------ code | Integer | 返回狀態碼 msg | String | 錯誤描述 result | JSON Object | 接口返回內容 常見錯誤代碼及其說明 Code | Error Type | Description ------------ | ----------- | ------------------------ 0／200 | 成功 | 請求成功 400 | 無效請求 | 某些必需參數缺失或參數值錯誤，詳見`msg`字段 401 | 未授權 | 授權失敗，`app_key`缺失或錯誤 403 | 請求被禁止 | 有效請求，但服務拒絕響應，請聯系[contact@ruyi.ai](contact@ruyi.ai) 408 | 請求超時 |請求響應超時，一般響應時間設置為2000ms以內 429 | 短時間內大量訪問 | 短時間內請求數過多 500 | 內部錯誤 | 服務處理異常 503 | 服務不可用 | 服務異常或正在維護