最基本的數(shù)據(jù)查詢功能

??本篇文章我們將介紹如何使用ADI平臺定義一個基本的數(shù)據(jù)查詢接口。由于是介紹平臺具體功能的第一篇文章，里面會涉及比較多的概念介紹，了解了這些概念有助于您閱讀后續(xù)的文章。
ADI平臺的首頁面如下：

1

1.菜單介紹

1.1 OAuth客戶端

該API平臺是一個獨立的服務平臺，任何與該API對接的系統(tǒng)都是一個OAuth客戶端。

1.2 路由設置

一個路由就是一個接口，該接口是給各OAuth客戶端調用的，路由下面包括分享設置，所謂分享設置就是接口的執(zhí)行策略。一個路由可以包括多個分享設置（即多個執(zhí)行策略），能夠根據(jù)不同的條件執(zhí)行不同的分享設置（例如不同的入?yún)⒖梢詧?zhí)行不同的分享設置），在今后的文章中會詳細介紹。

1.3 標準字典類別

即定義接口報文中有哪些字段是需要使用字典值的，您需要在這里配置您的業(yè)務系統(tǒng)中的字典字段和字典值，例如房地產(chǎn)行業(yè)的業(yè)務系統(tǒng)中的業(yè)務類別、交易者類別、房屋狀態(tài)、建筑結構等。該功能用于自動完成兩個不同系統(tǒng)間的字典轉換（例如A系統(tǒng)的"男性"與B系統(tǒng)的"male"互相轉換），在今后的文章中會詳細介紹。

1.4 分享日志ES查詢

API平臺會將每次的上報記錄保存在ES中，您通過該模塊可以方便的對全量分享日志做可視化查詢（一個分享設置的執(zhí)行會產(chǎn)生一條對應的分享日志）。

1.5 分享日志管理

通過該模塊可以方便的對保存在關系數(shù)據(jù)庫中的全量分享日志做可視化查詢。

1.6 失敗請求管理

通過該模塊可以更加直觀的看到接口調用失敗的日志。

1.6 產(chǎn)品授權管理

在這里填寫產(chǎn)品授權碼，只有通過授權的API平臺才能正常使用。

2.測試數(shù)據(jù)準備

我準備了一個mysql的測試庫business_system來模擬某網(wǎng)簽備案業(yè)務系統(tǒng)的數(shù)據(jù)庫數(shù)據(jù)（什么是網(wǎng)簽備案系統(tǒng)？簡單來說就是住建局的房產(chǎn)交易平臺，供買賣雙方簽訂房屋買賣合同使用），其中包括三張表：

2.1 幢表（zhuang）

表結構如下:

2

幢表準備了兩條數(shù)據(jù)：

3

2.2 戶表（h）

戶表通過"幢序號zxh"外鍵字段與zhuang表關聯(lián)，表明這套房子屬于哪個樓幢，表結構如下：

4

戶表準備了兩條數(shù)據(jù)：

5

2.3 交易者表（jyz）

交易者表記錄了誰購買了哪一套房子（通過戶序號關聯(lián)戶表），以及買賣合同編號等信息，表結構如下：

6

交易者表中保存了兩個合同，其中的YS20231203000001合同有兩個賣方（張三、李四）、兩個買方（王五、趙六）；YS20231203000002合同有一個賣方（戚薇）和一個買方（周杰倫），數(shù)據(jù)如下：

7

請注意： 后續(xù)的文章將很大程度在這個測試庫上完成相關示例，請大家多多熟悉。

2.4 接口需求

通過買賣合同號使用GET請求查詢該合同對應的樓棟基本信息、戶基本信息、賣方基本信息、買方基本信息，該接口提供給住建局的預售資金監(jiān)管系統(tǒng)使用（什么是預售資金監(jiān)管系統(tǒng)？簡單來說就是住建局的資金監(jiān)管平臺，買方把購房資金交給資金監(jiān)管系統(tǒng)，等條件成熟后住建局再把資金給賣方，由此確保房產(chǎn)交易的安全性），要求接口響應如下json格式的報文：

{ "ywbh": "業(yè)務編號", "htbh": "合同編號", "building": { "bdcdyh": "幢登記單元代碼/不動產(chǎn)單元號", "zl": "幢坐落" }, "houses": [{ "bdcdyh": "戶登記單元代碼/不動產(chǎn)單元號", "fwbm": "房屋編碼", "szqsc": "所在起始層", "szzzc": "所在終止層", "shbw": "室號部位", "fwzl": "房屋坐落", "jzjg": "建筑結構", "jzjgbm": "建筑結構編碼", "fwyt": "房屋用途", "fwytbm": "房屋用途編碼", "jzmj": "建筑面積" }], "sellers": [{ "jyzqc": "交易者全稱", "jyzzjmc": "交易者證件名稱", "jyzzjhm": "交易者證件號碼", "jyzxz": "交易者性質" }], "buyers": [{ "jyzqc": "交易者全稱", "jyzzjmc": "交易者證件名稱", "jyzzjhm": "交易者證件號碼", "jyzxz": "交易者性質" }]}

其中building用來裝載幢基本信息，houses用來裝載戶基本信息，sellers用來裝載賣方信息，buyers用來裝載買方信息。

3.開始定義接口

3.1 新增OAuth客戶端

點擊主界面的[OAuth客戶端]菜單->點擊[新增]，填寫如下字段：

8

核心字段說明：
系統(tǒng)名稱： 是指要與我們API平臺對接的第三方業(yè)務系統(tǒng)的名稱；這里我們命名為"預售資金監(jiān)管系統(tǒng)"。
單位名稱： 是指要與我們API平臺對接的第三方業(yè)務系統(tǒng)所屬的單位；這里我們命名為"住建/房管"。
client_id： 是指該系統(tǒng)在API平臺的唯一標識，今后我們做OAuth2.0客戶端認證時會用到。
token的有效時間(秒)： 是指該系統(tǒng)從API平臺獲取到的access_token的有效期（默認值是2592000，即30天），今后我們做OAuth2.0客戶端認證時會用到。
按同樣的方式我們再新增一個OAuth客戶端，命名為"網(wǎng)簽備案系統(tǒng)"。
當兩個客戶端新增完成后，我們可以看到OAuth客戶端列表：

9

其中的client_secret是自動生成的，今后我們做OAuth2.0客戶端認證時會用到。
注意：一個OAuth客戶端新增后可以重復使用，當遇到有新的系統(tǒng)要參與對接時，按同樣的方式新增即可。

3.2 新增一個路由(接口)

點擊主界面的[路由設置管理]->點擊[新增]，填寫以下字段：

10

核心字段說明：
路由編碼： 是指接口的英文名稱，會體現(xiàn)到動態(tài)生成的接口地址中；這里我們命名為"queryMmhtJbxx"。
路由名稱： 是指接口的中文名稱；這里我們命名為"查詢買賣合同基本信息"。
源系統(tǒng)： 是指該接口默認是給哪個OAuth客戶端調用的；這里我們選擇"預售資金監(jiān)管系統(tǒng)"（當然也可以被其它OAuth客戶端調用，這里只是賦一個默認值）。
調用方式： 是指該接口對應的http method；這里我們按上面的需求選擇get。
其它字段我們暫時用不上，后續(xù)文章介紹對應的功能時再講解，這里保持默認即可。保存后，您將看到以下界面：

11

3.3 新增一個分享

點擊路由的[分享設置]-[新增]，填寫以下字段：

12

核心字段說明：
分享類別： 是指該分享所屬的類別，盡量實事求是即可；因為是跟住建局對接，因此這里我們從下拉列表選擇"應用集成-001住建"。
分享編碼： 是指分享設置的英文名稱，默認和路由編碼一致，如果您的路由下有多個分享設置，請修改分享編碼，確保不會違反唯一性（后續(xù)文章會詳細介紹一個路由下新增多個分享設置的應用場景）。
分享名稱： 是指分享設置的中文名稱，默認和路由編碼一致，如果您的路由下有多個分享設置，根據(jù)分享設置的實際用途修改即可。
開發(fā)完成： 選擇“是”才會完全執(zhí)行該分享設置的邏輯；選擇“否”會直接響應測試數(shù)據(jù)，且需要您在這個界面維護“測試響應數(shù)據(jù)”字段（一般什么情況下會選擇"否"？當目標系統(tǒng)的接口還未開發(fā)完成時，為了不影響源系統(tǒng)的程序開發(fā)進度，這里就可以選擇"否"，并且按照約定的報文格式組織測試數(shù)據(jù)進行響應；后續(xù)文章會詳細介紹）。
目標系統(tǒng)名稱： 是指這個分享設置的響應方是誰，這里我們選擇"網(wǎng)簽備案系統(tǒng)"。
是否啟用： 選擇“是”，如果選擇“否”，將不會執(zhí)行該分享設置（當一個路由下有多個分享設置，并且不再需要某個分享設置時，可以設置成"否"）。
是否前置分享： 是指執(zhí)行該路由的其它分享設置之前，是否需要優(yōu)先執(zhí)行該分享設置，當且僅當前置分享設置執(zhí)行成功后才會執(zhí)行其他分享設置（后續(xù)文章會詳細介紹前置分享的應用場景）。
實時響應： 是指是否需要同步執(zhí)行該分享設置；選擇“否”將異步執(zhí)行，直接響應成功（后續(xù)文章會詳細介紹異步執(zhí)行的應用場景）。
數(shù)據(jù)庫類型： 是指該分享設置要直接操作的數(shù)據(jù)庫類型，支持Oracle、Mysql、SqlServer、PostgreSQL；這里我們選擇Mysql。
數(shù)據(jù)庫IP： 是指該分享設置要直接操作的數(shù)據(jù)庫IP地址；由于測試庫在本機，因此這里填寫"127.0.0.1"。
數(shù)據(jù)庫實例名： 是指該分享設置要直接操作的數(shù)據(jù)庫實例名；這里我們填寫"business_system?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC"。
數(shù)據(jù)庫端口： 是指該分享設置要直接操作的數(shù)據(jù)庫連接端口；這里我們填寫3306。
數(shù)據(jù)庫用戶名： 是指該分享設置要直接操作的數(shù)據(jù)庫用戶名。
數(shù)據(jù)庫密碼： 是指該分享設置要直接操作的數(shù)據(jù)庫密碼，保存后API平臺會進行加密存儲。
其它字段我們暫時用不上，后續(xù)文章介紹對應的功能時再講解，這里保持默認即可。保存后，您將看到以下界面：

13

可以點擊"數(shù)據(jù)庫連接測試"，看看我們填寫的數(shù)據(jù)庫信息是否正確，如圖：

14

3.4 編寫sql組裝業(yè)務數(shù)據(jù)

點擊分享設置的[數(shù)據(jù)定義]，如圖：

15

點擊數(shù)據(jù)定義頁面的[新增]，假設接口的入?yún)⑹莌tbh(合同編號)，那么我們要做的，就是根據(jù)入?yún)⒕帉?span id="lftbtjp5bp" class="candidate-entity-word" data-gid="4317979">sql語句，實現(xiàn)報文的組裝。
首先，我們把json報文的根節(jié)點字段查詢出來，sql如下：

select distinct ywbh,htbh from jyz j where j.HTBH = request~htbh~

提示： request~ ~ 是sql中獲取動態(tài)參數(shù)（從接口的請求報文中獲?。┑膶懛ǎ瑓?shù)名和入?yún)⒈３忠恢拢ù笮懖幻舾校?；API平臺生成在線接口文檔的時候，會自動解析request~~中的參數(shù)，以便您進行測試。
把sql填寫到表單中，如圖：

16

核心字段說明：
數(shù)據(jù)集： 是指您的sql語句。
數(shù)據(jù)類型： 是指該sql語句的執(zhí)行結果要組裝成什么json格式，支持jsonObject和jsonArray；根數(shù)據(jù)集只能使用jsonObject。
數(shù)據(jù)集名稱： 是指組裝成json的時候，該數(shù)據(jù)集對應的json字段名；默認root，表示根數(shù)據(jù)集，會將sql查出來的字段放到json對象的根節(jié)點。
數(shù)據(jù)集父類名稱： 是指該數(shù)據(jù)集的上層數(shù)據(jù)集名稱，用來實現(xiàn)json嵌套格式（當某條sql的執(zhí)行依賴于上級sql的執(zhí)行結果時，那么需要在這里指定上層數(shù)據(jù)集，并且通過 parent~ ~ 可以把上層sql的執(zhí)行結果作為本sql的查詢條件）。
是否大寫： 是指組裝json的時候，json字段是否需要大寫；根據(jù)最前面給的json實例，我們這里選擇"否"，即小寫。
執(zhí)行前置條件_JS： 是指滿足指定條件時才執(zhí)行該數(shù)據(jù)集（后續(xù)文章會詳細介紹使用場景）。

填寫完成后點擊保存即可，如果保存成功，代表您的sql語法無誤，API平臺會自動解析該sql返回的字段，保存到”數(shù)據(jù)詳情”中。
提示：只有第一次保存sql才會自動解析字段，如果您后續(xù)修改sql增加或減少了字段，那么”數(shù)據(jù)詳情”中是不會自動增加或減少字段的，需要您手工在”數(shù)據(jù)詳情”中對字段進行增刪改。

17

點擊[數(shù)據(jù)詳情]可以看到自動生成的字段信息，如圖：

18

接下來我們組裝json中building(幢)節(jié)點的數(shù)據(jù)。點擊點擊分享設置的[數(shù)據(jù)定義]->[新增]
填寫如下sql語句：

SELECT DISTINCT z.ZHDJDYDM AS bdcdyh, z.zl FROM zhuang z JOIN h ON h.ZXH = z.ZXH JOIN jyz ON h.HXH = jyz.HXH AND jyz.ywbh = parent~ywbh~

提示： parent~~是sql中獲取動態(tài)參數(shù)（從父級數(shù)據(jù)集的查詢結果中獲取）的寫法，參數(shù)名和父級數(shù)據(jù)集返回的字段名保持一致（大小寫不敏感）。

19

根據(jù)報文結構，這個數(shù)據(jù)集對應的數(shù)據(jù)類型是jsonObject，數(shù)據(jù)集名稱是building，父級數(shù)據(jù)集選擇root，json字段小寫，填寫后點擊保存即可。

接下來我們組裝json中houses(戶)節(jié)點的數(shù)據(jù)。點擊點擊分享設置的[數(shù)據(jù)定義]->[新增]
填寫如下sql語句：

SELECT DISTINCT h.HDJDYDM AS bdcdyh, h.FBM AS fwbm, h.QSC AS szqsc, h.ZHZHC AS szzzc, h.FH AS shbw, h.ZL AS fwzl, h.JZJG AS jzjg, h.GHYT AS fwyt, h.JZMJ FROM h JOIN jyz ON h.HXH = jyz.HXH AND jyz.ywbh = parent~ywbh~

如圖：

20

根據(jù)報文結構，這個數(shù)據(jù)集對應的數(shù)據(jù)類型是jsonArray，數(shù)據(jù)集名稱是houses，父級數(shù)據(jù)集選擇root，json字段小寫，填寫后點擊保存即可。

接下來我們組裝json中sellers(賣方)節(jié)點的數(shù)據(jù)。點擊點擊分享設置的[數(shù)據(jù)定義]->[新增]
填寫如下sql語句：

SELECT j.QC AS jyzqc, j.ZJMC AS jyzzjmc, j.ZJHM AS jyzzjhm, j.JYZXZ FROM jyz j WHERE j.ywbh = parent~ywbh~ AND j.JYZLB = '賣方'

如圖：

21

根據(jù)報文結構，這個數(shù)據(jù)集對應的數(shù)據(jù)類型是jsonArray，數(shù)據(jù)集名稱是sellers，父級數(shù)據(jù)集選擇root，json字段小寫，填寫后點擊保存即可。

接下來我們組裝json中buyers(買方)節(jié)點的數(shù)據(jù)。點擊點擊分享設置的[數(shù)據(jù)定義]->[新增]
填寫如下sql語句：

SELECT j.QC AS jyzqc, j.ZJMC AS jyzzjmc, j.ZJHM AS jyzzjhm, j.JYZXZ FROM jyz j WHERE j.ywbh = parent~ywbh~ AND j.JYZLB = '買方'

如圖：

22

根據(jù)報文結構，這個數(shù)據(jù)集對應的數(shù)據(jù)類型是jsonArray，數(shù)據(jù)集名稱是buyers，父級數(shù)據(jù)集選擇root，json字段小寫，填寫后點擊保存即可。

到此為止，我們所有的sql都添加好了，數(shù)據(jù)定義列表截圖如下：

23

4.在線測試接口

回到路由設置的列表頁，找到我們剛才新增的路由，點擊[打開文檔]，如圖所示：

24

點擊后可以看到API平臺為我們自動生成的在線文檔，如圖：

25

我們填寫入?yún)⒅担篩S20231203000001，點擊[試一下]，接口調用該接口，如圖：

26

可以看到API平臺為這個接口自動生成的接口地址是"http://127.0.0.1:8080/adi/bitapi/queryMmhtJbxx"，其中的adi和bitapi是固定路徑，queryMmhtJbxx則是我們自定義的路由編碼；響應報文如下：

{ "type": "success", "data": { "ywbh": "20231203000001", "htbh": "YS20231203000001", "building": { "bdcdyh": "110108001001GB00001F0001", "zl": "北京市海淀區(qū)曙光中路曙光花園智業(yè)園1幢" }, "houses": [ { "bdcdyh": "110108001001GB00001F00010003", "fwbm": "fbm0003", "szqsc": 1, "szzzc": 1, "shbw": "103", "fwzl": "北京市海淀區(qū)曙光中路曙光花園智業(yè)園1幢B座1-103", "jzjg": "鋼結構", "fwyt": "住宅", "jzmj": 183 } ], "sellers": [ { "jyzqc": "張三", "jyzzjmc": "居民身份證", "jyzzjhm": "510121100909137101", "jyzxz": "外省市個人" }, { "jyzqc": "李四", "jyzzjmc": "軍官證", "jyzzjhm": "wj0001", "jyzxz": "軍人" } ], "buyers": [ { "jyzqc": "王五", "jyzzjmc": "戶口簿", "jyzzjhm": "522121100909137102", "jyzxz": "本市城鎮(zhèn)居民" }, { "jyzqc": "趙六", "jyzzjmc": "港澳臺身份證", "jyzzjhm": "gat0001", "jyzxz": "臺灣同胞" } ] }, "uuid": "ece8cac65dc744b993ac86dadaeae6af"}

其中的type、data、uuid是API平臺響應的固定參數(shù)，解釋如下：
type：表示本次接口調用是否成功，其中type=success表示請求處理成功，否則(type=fail)表示處理失敗，當處理成功時，data一般是裝載業(yè)務數(shù)據(jù)的json對象或者是字符串類型的提示信息，當處理失敗時，data則是字符串類型的失敗原因。
data：業(yè)務數(shù)據(jù)或提示信息。
uuid：本次請求的唯一標識，通過uuid值可以在API平臺中迅速定位日志詳情。

注意： API平臺要求請求報文必須是utf-8編碼的；API平臺的響應報文也是utf-8編碼的。

有了在線接口文檔，我們就不需要安裝類似postman這種軟件了，當時，如果你確實想在postman中調用也是可以的，在瀏覽器地址欄調用get請求也是可以的，如圖所示：

27

4.查詢接口調用日志

點擊主界面的[分享日子和ES查詢]或[分享日志管理]，如圖所示：

28

每個分享設置在執(zhí)行時都會生成一條分享日志。從"說明"列我們可以看到最開始那條日志對應的調用耗時最長，是因為數(shù)據(jù)源第一次被使用時API平臺會創(chuàng)建數(shù)據(jù)庫連接池。最常用的兩列：
日志編碼： 每次調用時的唯一編碼，可以從API平臺的響應報文中中獲??；
日志跟蹤： 從接口入?yún)⒅蝎@取，一般是業(yè)務系統(tǒng)的某個字段，例如業(yè)務編號或買賣合同號等，可以自定義使用哪個入?yún)⒆鳛槿罩靖欀怠?br />如果使用ES查詢，那么我們可以在第一個查詢條件輸入框中輸入某個關鍵字，即可查詢到相關的日志，例如我們輸入"周杰倫"進行查詢，效果如下：

29

ES查詢提高了我們查詢?nèi)罩镜撵`活程度。
點擊[詳情]，可以看到該條分享日志更加詳細的信息，例如請求報文、請求時間、響應報文、響應時間等，如圖所示：

30

31

里面有些字段值是空的，這是因為我們本次定義的接口沒有涉及到請求轉發(fā)、沒有涉及到加解密。

到這里，相信大家已經(jīng)對ADI平臺有了一個初步的認識，后續(xù)我將繼續(xù)介紹ADI平臺其它的重要功能，謝謝您的閱讀！