## 5.6 觸發器 >本節主要介紹如何利用開發者后臺調用第三方API接口，用戶可以在后臺自定義觸發器來調用接口數據，實現一些復雜的功能。 ### 5.6.1 什么是觸發器 ruyi.ai 的開發者后臺提供了經典的“用戶說”、“機器答”形式的問答對編輯，并提供了實時生效的自定義詞典實體編輯，以及可以通過暗號控制的多輪對話等。但是當客戶希望自定義實現一些復雜的功能時，那么就需要給意圖開發相應的觸發器。 觸發器是在實體解析、意圖識別之后，根據識別的意圖和解析的實體進行自定義邏輯處理的功能接口。它可以獲取解析到的實體作為參數，在此基礎上進行開發，并把結果加入 ruyi.ai 語義接口的返回結果中。如果第三方接口返回的數據不滿足需求，還可以對第三方數據進行進一步邏輯處理，觸發器上填入“包裝”后的接口url即可。 ### 5.6.2 如何使用自定義觸發器 ruyi.ai 支持Web API 形式的自定義觸發器，支持GET、POST方法，支持自定義header以及json形式的請求體。使用自定義觸發器分兩步： ①編輯自定義觸發器 ②在意圖中使用自定義觸發器 #### 第一步：編輯自定義觸發器 在機器人助理界面的機器人設置中有一個觸發器設置，在觸發器設置頁面中可以添加自定義觸發器。  在添加自定義觸發器時，需要填寫自定義觸發器的名字，API 的服務地址、請求方法以及需要的 header 信息。 以名人名言機器人為例。  - 觸發器名稱：自定義觸發器名稱，該名稱在該機器人下需要唯一。 - URL: Web API的請求地址，API可以使用開放的API網站或自己制作。 - Method：Web API 的請求方法，目前支持 GET、POST 兩種方法。 - header：請求所需的 header，可添加多個 header，沒有則不填。 - JSON body：當請求需要傳遞 JSON 格式的請求體時，在文本框中直接編輯JSON，若 JSON 中某個 field 或某處需要引用用戶說中實體的值，則以$符號加名稱引用，即"$名稱".**此處名稱與意圖界面中意圖處理的名稱一致。** 下圖使用了 JSON body，其中 city 和 name 的值來自于用戶說。  - 是否緩存：觸發器是否使用緩存，選擇"ON"的情況下，需要選擇緩存周期以及指定緩存的 key，選擇"OFF"的情況下，觸發器不使用緩存。一般情況下不建議使用` - 緩存周期：如果使用緩存，則需要選擇緩存周期，即一個結果會被緩存多長時間。以下拉框形式選擇，目前支持1小時，當天，24小時，一周，其中當天是指緩存到當天23:59:59。 - 緩存key：如果使用緩存，需要指定緩存的 key，對于 REST API 來說，請求的結果取決于該請求所傳遞的參數，而使用緩存的前提是當參數相同時，返回相同的結果，而參數不同時，返回不同的結果，所以緩存的key應該以 API 的參數來構建。` 設置自定義觸發器的人應當清楚哪些參數會影響 API 的結果，那么這些參數都應該作為 key 的一部分，這些參數的名稱應該都加入緩存 key 中。**此處名稱與意圖界面中意圖處理的名稱一致。** 以天氣為例，天氣 API 接受參數地點和日期，這兩個參數決定了 API 的結果，它們在意圖處理中的名稱分別是 location 和 date，那么緩存 key 就需要填入 location 和 date。  #### 第二步：在意圖中使用自定義觸發器 在意圖頁面的觸發器欄中選擇配置好的觸發器，如果觸發器需要參數，那么我們需要配置觸發器的參數。 **觸發器參數來源**：自定義觸發器的參數可以是用戶說的話中的實體，也可以通過默認值的方式傳遞自定義參數，另外ruyi平臺會向自定義觸發器傳遞一些默認參數，比如appId，userId等（見附錄1）。 **觸發器參數傳遞方式**：ruyi平臺默認參數會直接把參數放入觸發器請求的request中，其他自定義參數則通過意圖中的意圖處理來傳遞。意圖處理中的名稱對應 API 中的參數名。來自于用戶說的實體參數，開發者后臺會自動在意圖處理中進行配置，只需要修改**名稱**為 API 的參數名即可。自定義參數，比如 AppKey，名稱填入參數名，值填入“$"+參數名，類型用@sys.any，然后把參數值填入默認值即可。 以意圖名人名言為例。編寫好用戶說后，在意圖處理中進行參數配置。   意圖名人名言完成后，選擇保存，然后就可以在“試一試”中感受對話效果了。以下為試一試中返回成功的JSON。 ``` { "_text": "孔子講過什么名言", "msg_id": "75da006e-ed6b-4bbf-8519-2dd78364d9cc", "intents": [{ "parameters": { "key": "70617dd808f24244a91b3e2c1a25244f", "keyword": "孔子", "any": "", "名言": "名言" }, "action": "名人名言", "name": "名人名言", "result": { "code": 200, "response": { "total": 29, "result": [{ "famous_name": "孔子", "famous_saying": "君子謀道不謀食，憂道不憂貧。" }, { "famous_name": "孔子", "famous_saying": "鳥之將死，其鳴也哀；人之將死，其言也善。" }, { "famous_name": "孔子", "famous_saying": "自古皆有死，民無信不立。" }, { "famous_name": "孔子", "famous_saying": "君子之道四焉，強于行義，弱于受諫，怵于待祿，慎于治身。" }, { "famous_name": "孔子", "famous_saying": "禮之于人，猶酒之有襞也。" }, { "famous_name": "孔子家語", "famous_saying": "君子以行言，小人以舌言" }, { "famous_name": "孔子", "famous_saying": "其身正，不令而行；其身不正，雖令不行。" }, { "famous_name": "孔子", "famous_saying": "天下之至仁者，能合天之至親也。" }, { "famous_name": "孔子", "famous_saying": "吾十有五而志于學，三十而立，四十而不惑，五十而知天命，六十而耳順，七十而從心所欲，不逾矩。" }, { "famous_name": "孔子", "famous_saying": "夫子循循然善誘人，博我以文，約我以禮，欲罷不能。" }, { "famous_name": "孔子", "famous_saying": "民無信不立。" }, { "famous_name": "《孔子家語·三恕》", "famous_saying": "虛則欹，中則正，滿則震。" }, { "famous_name": "孔子", "famous_saying": "獨學而無友，則孤陋而寡聞。" }, { "famous_name": "蘇軾", "famous_saying": "孔子圣人，其學必始于觀書。" }, { "famous_name": "《孔子家語》", "famous_saying": "鞭撲之自子，不從父之教。" }, { "famous_name": "孔子", "famous_saying": "不患貧而患不均，不患寡而患不安。" }, { "famous_name": "《孔子家語》", "famous_saying": "良藥苦于口而利于病，忠言逆于耳而利于行。" }, { "famous_name": "《孔子家語·顏回·孔子語》", "famous_saying": "君子以行言，小人以舌言。" }, { "famous_name": "孔子", "famous_saying": "益者三友：友直、友諒、友多聞。" }, { "famous_name": "孔子家語", "famous_saying": "君者舟也，庶人者水也。水所以載舟，亦所以覆舟" }], "error_code": 0, "reason": "Succes" }, "text": "【孔子】講過【獨學而無友，則孤陋而寡聞。】", "type": "dialog" }, "outputs": [{ "type": "wechat.text", "property": { "text": "【孔子】講過【益者三友：友直、友諒、友多聞。】" } }], "score": "1.0", "scoreColor": "c4", "is_match": 1, "id": "3efeeae2-e32c-489b-8471-c11112df5311" }], "meta_process_milliseconds": 81 } ``` ### 附錄1 #### ruyi平臺觸發器默認參數 | 參數名 | 獲取方式 | 說明 | | --- | --- | --- | | appId | 直接從request中獲取 | Bot對應的appId | | userId | 直接從request中獲取 | 該次對話的用戶id | | skillAppId | 直接從request中獲取 | 觸發的技能Bot對應的appId | #### ruyi平臺默認暗號攜帶參數 | 參數名 | 獲取方式 | 說明 | | --- | --- | --- | | 自定義 | 通過意圖處理獲取，意圖處理”值“的一欄填入#ruyi_default_context.last_result.xxx，xxx對應上次觸發器結果中所需字段的路徑 | ruyi默認暗號攜帶的參數，可以從中獲取上次觸發器的結果 | | 自定義 | 通過意圖處理獲取，意圖處理”值“的一欄填入#ruyi_default_context.last_q | ruyi默認暗號攜帶的參數，對應上次對話中用戶說的話 | | 自定義 | 通過意圖處理獲取，意圖處理”值“的一欄填入#ruyi_default_context.curr_q | uyi默認暗號攜帶的參數，對應本次對話中用戶說的話 |