政務數(shù)據(jù)平臺 第4部分：接口規(guī)范

ICS01.040.03

A12

DB52

貴州省地方標準

DB52/T1541.4—2021

政務數(shù)據(jù)平臺第4部分：接口規(guī)范

Governmentdataplatform——Part4：Interfacespecification

2021-05-17發(fā)布2021-09-01實施

貴州省市場監(jiān)督管理局發(fā)布

DB52/T1541.4—2021

政務數(shù)據(jù)平臺第4部分：接口規(guī)范

1范圍

本文件規(guī)定了政務數(shù)據(jù)平臺數(shù)據(jù)接口的術語和定義、縮略語、基本要求、接口組成、接口要求和接

口安全。

本文件適用于政務數(shù)據(jù)平臺接口的設計和應用。

2規(guī)范性引用文件

本文件沒有規(guī)范性引用文件。

3術語和定義

下列術語和定義適用于本文件。

3.1

接口interface

基于應用程序的服務能力封裝成接口，并通過API網關開放給客戶端調用。

3.2

數(shù)據(jù)data

對事實、概念或指令的一種形式化表示，適用于以人工或自動方式進行通信、解釋或處理。

[來源：DB52/T1239.1-2017，3.1]

3.3

政務數(shù)據(jù)資源目錄directoryofgovernmentdataresources

通過對政務數(shù)據(jù)資源依據(jù)規(guī)范的元數(shù)據(jù)描述，按照一定的分類方法進行排序和編碼的一組信息,用

以描述各個政務數(shù)據(jù)資源的特征，以便于對政務數(shù)據(jù)資源的檢索、定位與獲取。

3.4

政務數(shù)據(jù)提供方governmentdataprovider

基于統(tǒng)一數(shù)據(jù)共享交換平臺，利用各種技術向其他政務部門、事業(yè)單位、企業(yè)或公眾提供政務數(shù)據(jù)

的實體。

1

DB52/T1541.4—2021

3.5

訪問令牌accesstoken

訪問控制操作主體的系統(tǒng)對象。

4縮略語

下列縮略語適用于本文件。

API：應用程序編程接口（ApplicationProgrammingInterface）

HTTP：超文本傳輸協(xié)議（HyperTextTransferProtocol）

HTTPS：超文本傳輸安全協(xié)議（HyperTextTransferProtocoloverSecureSocketLayer）

JSON：輕量級的數(shù)據(jù)交換格式（JavascriptObjectNotation）

REST：一種網絡應用程序的設計風格和開發(fā)方式（RepersentationalStateTransfer）

5基本要求

5.1應采用HTTP/HTTPS作為傳輸協(xié)議。

5.2應采用JSON作為消息的封裝格式。

5.3應提供服務請求成功、失敗等各種情況的接口返回狀態(tài)碼。

5.4應支持跨語言、跨操作系統(tǒng)調用。

6接口組成

政務數(shù)據(jù)平臺接口主要包括：認證授權服務接口、組織接口、用戶接口、數(shù)據(jù)資源目錄接口。政務

數(shù)據(jù)平臺接口組成見圖1。

圖1政務數(shù)據(jù)平臺接口組成圖

2

DB52/T1541.4—2021

7接口要求

7.1認證授權服務接口

接口描述：政務數(shù)據(jù)提供方接入政務數(shù)據(jù)平臺應調用認證授權服務接口。通過平臺認證授權服務接

口進行身份驗證，驗證成功后接口返回的授權訪問令牌，政務數(shù)據(jù)提供方操作政務數(shù)據(jù)平臺接口應攜帶

訪問令牌，進行正常會話交互。

接口地址：/api/auth_service。

接口類型：post。

請求參數(shù)：認證授權服務接口請求參數(shù)見表1。

請求示例：見附錄A。

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表1認證授權服務接口請求參數(shù)表

參數(shù)名稱類型是否必填說明

access_keystring是政務數(shù)據(jù)平臺分配給政務數(shù)據(jù)提供方的唯一標識

access_secretstring是政務數(shù)據(jù)平臺分配給政務數(shù)據(jù)提供方的密鑰

usernamestring是政務數(shù)據(jù)平臺分配給政務數(shù)提供方的用戶賬戶名稱

passwordstring是政務數(shù)據(jù)平臺分配給政務數(shù)據(jù)提供方的用戶賬戶密碼

7.2組織接口

7.2.1組織新增接口

接口描述：政務數(shù)據(jù)提供方調用政務數(shù)據(jù)平臺組織新增接口，獲取政務數(shù)據(jù)平臺返回的組織ID，根

據(jù)組織ID進行政務數(shù)據(jù)提供方系統(tǒng)和政務數(shù)據(jù)平臺交互。

接口地址：/api/add/organization。

接口類型：post。

請求參數(shù)：同步組織機構請求參數(shù)見表2。

請求示例：見附錄B。

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表2同步組織機構請求參數(shù)表

參數(shù)名稱類型是否必填說明

addTypeint是操作類型：1表示新增

trustNoint是統(tǒng)一社會信用代碼

groupShortNamestring是組織簡稱

groupNamestring是組織名稱

regionNamestring是組織所屬地區(qū)

orgPostNoint是組織區(qū)劃編號

group_levelint是級別：401省直，402市州

super_orgint是父級組織編號

3

DB52/T1541.4—2021

7.2.2組織編輯接口

接口描述：編輯組織機構信息。

接口地址：/api/add/organization。

接口類型：post。

請求參數(shù)：組織機構編輯請求參數(shù)見表3。

請求示例：見附錄B。

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表3組織機構編輯請求參數(shù)表

參數(shù)名稱類型是否必填說明

addTypeint是操作類型：2表示編輯

trustNoint是統(tǒng)一社會信用代碼

groupShortNamestring是組織簡稱

groupNamestring是組織名稱

regionNamestring是組織所屬地區(qū)

orgPostNoint是組織區(qū)劃編號

group_levelint是級別：401省直，402市州

super_orgint是父級組織編號

7.2.3組織查詢接口

接口描述：政務數(shù)據(jù)提供方查詢政務組織機構信息。

接口地址：/api/organization/query。

接口類型：get。

請求參數(shù)：組織機構查詢接口請求參數(shù)見表4。

請求示例：http://ip+port/api/organization/query?org_name=組織名稱

&org_id=z6lqTzG3PTPpQIE92Bs0pA3PSyVJmlWM。

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表4組織機構查詢接口請求參數(shù)表

參數(shù)名稱類型是否必填說明

org_idstring是組織id

org_namestring是組織名稱

7.3用戶接口

7.3.1用戶新增接口

接口描述：政務數(shù)據(jù)提供方調用用戶新增接口，同步組織機構用戶信息到政務數(shù)據(jù)平臺。

接口地址：/api/add/user。

接口類型：post。

請求參數(shù)：組織機構用戶新增請求參數(shù)見表5。

4

DB52/T1541.4—2021

請求示例：見附錄C。

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表5組織機構用戶新增請求參數(shù)表

參數(shù)名稱類型是否必填說明

org_idstring是組織id

addTypeint是操作類型：1表示新增

userNamestring是用戶名

trueNamestring是用戶真實姓名

roIdsstring否用戶角色

mobilestring是聯(lián)系電話

7.3.2用戶編輯接口

接口描述：政務數(shù)據(jù)提供方編輯政務組織機構用戶信息。

接口地址：/api/add/user。

接口類型：post。

請求參數(shù)：組織機構用戶編輯請求參數(shù)見表6。

請求示例：見附錄C。

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表6組織機構用戶編輯請求參數(shù)表

參數(shù)名稱類型是否必填說明

org_idstring是組織id

addTypeint是操作類型：1表示新增

userNamestring是用戶名

trueNamestring是用戶真實姓名

roIdsstring是用戶角色

7.3.3用戶查詢接口

接口描述：政務數(shù)據(jù)提供方查詢政務數(shù)據(jù)平臺組織機構用戶信息。

接口地址：/api/query/user。

接口類型：get。

請求參數(shù)：用戶查詢見請求參數(shù)表7。

請求示例：http://ip+port/api/user/query?userId=z6lqTzG3PTPpQIE92Bs0pA3PSyVJmlWM。

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表7用戶查詢請求參數(shù)表

參數(shù)名稱類型是否必填說明

userIdstring是用戶id

5

DB52/T1541.4—2021

7.4數(shù)據(jù)資源目錄接口

7.4.1數(shù)據(jù)資源目錄新增接口

接口描述：政務數(shù)據(jù)提供方同步政務組織機構的數(shù)據(jù)資源目錄信息到政務數(shù)據(jù)平臺。

接口地址：/api/add/resource。

接口類型：post

請求參數(shù)：數(shù)據(jù)資源目錄新增請求參數(shù)見表8。

請求示例：見附錄D。

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表8數(shù)據(jù)資源目錄新增請求參數(shù)表

參數(shù)名稱類型是否必填說明

idstring是數(shù)據(jù)資源目錄id

industryIdstring是行業(yè)id

orgIdstring是組織id

topicIdstring是主題id

userIdstring是用戶id

addTypeint是操作類型：1表示新增

接口信息描述見圖2，

apiDatajsonObject是

數(shù)據(jù)結構見附錄D、附錄E

目錄信息描述見圖3

directoryjsonObject是

數(shù)據(jù)結構見附錄F、附錄G

industrystring是行業(yè)

openAttributeint是開放屬性：1有條件開放；2無條件開放；3不予開放

serviceNamestring是服務名稱

shareAttributeint是共享屬性：1有條件共享；2無條件共享；3不予共享

topicstring是主題

uniscidstring是統(tǒng)一社會信用代碼

6

DB52/T1541.4—2021

圖2接口信息描述組成結構圖

7

DB52/T1541.4—2021

圖3目錄信息描述組成結構圖

7.4.2數(shù)據(jù)資源目錄編輯接口

接口描述：政務數(shù)據(jù)提供方編輯數(shù)據(jù)資源目錄信息。

接口地址：/api/add/resource。

接口類型：post。

請求參數(shù)：數(shù)據(jù)資源目錄編輯請求參數(shù)見表9。

請求示例：見附錄D。

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表9數(shù)據(jù)資源目錄編輯請求參數(shù)表

參數(shù)名稱類型是否必填說明

idstring是數(shù)據(jù)資源目錄id

userIdstring是用戶id

addTypeint是操作類型：2表示編輯

openAttributeint是開放屬性：1有條件開放；2無條件開放；3不予開放

shareAttributeint是共享屬性：1有條件共享；2無條件共享；3不予共享

7.4.3數(shù)據(jù)資源目錄查詢接口

接口描述：政務數(shù)據(jù)提供方查詢數(shù)據(jù)資源目錄信息。

接口地址：/api/resource/query。

接口類型：post。

請求參數(shù)：數(shù)據(jù)資源目錄查詢請求參數(shù)見表10。

請求示例：http://ip+port/api/resource/query?userId=z6lqTzG3PTPpQIE92Bs0pA3PSyVJmlWM。

8

DB52/T1541.4—2021

返回參數(shù)：見附錄I表I.1。

返回示例：見附錄H。

表10數(shù)據(jù)資源目錄查詢請求參數(shù)表

參數(shù)名稱類型是否必填說明

idstring是數(shù)據(jù)資源目錄id

userIdstring是用戶id

8接口安全

8.1對請求的合法性進行校驗。

8.2對請求的數(shù)據(jù)進行校驗。

8.3對請求實現(xiàn)黑明單與白名單攔截。

8.4對請求實現(xiàn)用戶使用接口的流量限制。

9

DB52/T1541.4—2021

AA

附錄A

（資料性）

認證授權服務接口JSONSchema示例

下面給出認證授權服務接口JSONSchema示例。

示例：

{

"$schema":"/draft-07/schema",

"$id":"/example.json",

"type":"object",

"title":"Therootschema",

"examples":[

{

"app_key":"C3kFcJP5Pw5w13nBX2GCh03zSrn8p7BA",

"app_secret":"rmnnkSkWfx0A7w6n13bKrwPGaM0dEQr6",

"username":"test",

"password":"8vJDXhG2waQ5rAxG"

}

],

"required":[

"app_key",

"app_secret",

"username",

"password"

]

}

10

DB52/T1541.4—2021

BB

附錄B

（資料性）

組織新增接口JSONSchema示例

下面給出組織新增接口JSONSchema示例。

示例：

{

"$schema":"/draft-07/schema",

"$id":"/example.json",

"type":"object",

"title":"Therootschema",

"description":"TherootschemacomprisestheentireJSONdocument.",

"default":{},

"examples":[

{

"addType":"1",

"trustNo":"91370200163562681G",

"groupShortName":"測試",

"groupName":"組織新增測試",

"regionName":"test",

"orgPostNo":"KXRay9teJN0V93kvgk",

"group_level":401,

"super_org":100

}

],

"required":[

"addType",

"trustNo",

"groupShortName",

"groupName",

"regionName",

"orgPostNo",

"group_level",

"super_org"

]

}

11

DB52/T1541.4—2021

CC

附錄C

（資料性）

用戶新增接口JSONSchema示例

下面給出用戶新增接口JSONSchema示例。

示例：

{

"$schema":"/draft-07/schema",

"$id":"/example.json",

"type":"object",

"title":"Therootschema",

"description":"TherootschemacomprisestheentireJSONdocument.",

"examples":[

{

"addType":"1",

"userName":"example",

"trueName":"示例",

"roIds":"sdfsdf",

"org_id":"ssKXRauteJN0V93krd",

"mobile":"KXRay9teJN0V93kvgk"

}

],

"required":[

"addType",

"userName",

"trueName",

"roIds",

"org_id",

"mobile"

]

}

12

DB52/T1541.4—2021

DD

附錄D

（資料性）

數(shù)據(jù)資源目錄接口的接口信息JSONSchema示例

數(shù)據(jù)資源目錄接口的接口信息JSONSchema示例。

示例：

{

"$schema":"/draft-07/schema",

"$id":"/example.json",

"type":"object",

"title":"Therootschema",

"description":"TherootschemacomprisestheentireJSONdocument.",

"required":[

"apiData"

],

"properties":{

"apiData":{

"$id":"#/properties/apiData",

"type":"object",

"title":"TheapiDataschema",

"description":"Anexplanationaboutthepurposeofthisinstance.",

"default":{},

"examples":[

{

"bodyType":0,

"createTime":1590647639923,

"description":"描述",

"requestDemo":"?pageIndex=1&pageSize=50",

"requestMode":1,

"requestParam":[

{

"description":"分頁，當前頁",

"must":0,

"name":"pageIndex",

"type":1

}

],

"responseDemo":"",

"responseParam":[

{

"description":"號碼",

13

DB52/T1541.4—2021

"name":"id",

"type":2

}

],

"responseType":1,

"resultCode":[

{

"description":"成功",

"name":"200"

}

],

"updateTime":1590647639923,

"url":"http://ip+port/"

}

],

"required":[

"bodyType",

"createTime",

"description",

"requestDemo",

"requestMode",

"requestParam",

"responseDemo",

"responseParam",

"responseType",

"resultCode",

"updateTime",

"url"

]

}

}

}

14

DB52/T1541.4—2021

EE

附錄E

（資料性）

數(shù)據(jù)資源目錄接口信息描述對象參數(shù)表

數(shù)據(jù)資源目錄接口信息描述對象參數(shù)表見表E.1。

表E.1數(shù)據(jù)資源目錄接口信息描述對象參數(shù)表

參數(shù)名稱類型是否必填說明

bodyTypeinteger是接口類型

createTimeinteger是創(chuàng)建時間

descriptionstring是用途描述

requestDemostring是服務調用示例

requestModeinteger是請求方法

requestParamarray是請求參數(shù)

responseDemostring是響應示例

responseParamarray是響應參數(shù)

responseTypeinteger是響應類型

resultCodearray是狀態(tài)碼說明

updateTimeinteger是更新時間

urlstring是接口服務地址

15

DB52/T1541.4—2021

FF

附錄F

（資料性）

數(shù)據(jù)資源目錄接口的目錄信息JSONSchema描述示例

下面給出數(shù)據(jù)資源目錄接口的目錄信息JSONSchema描述示例。

示例：

{

"$schema":"/draft-07/schema",

"$id":"/example.json",

"type":"object",

"title":"Therootschema",

"description":"TherootschemacomprisestheentireJSONdocument.",

"required":[

"directory"

],

"properties":{

"directory":{

"$id":"#/properties/directory",

"type":"object",

"title":"Thedirectoryschema",

"description":"Anexplanationaboutthepurposeofthisinstance.",

"default":{

},

"examples":[

{

"infoItems":[

{

"description":"身份證號碼",

"length":100,

"name":"id",

"type":"varchar"

}

],

"serviceName":"飲水安全",

"system":{

"system":"回歸測試",

"systemId":"710b8d8c-e868-4b55-9e4d-d2b50ad78521"

}

}

],

16

DB52/T1541.4—2021

"required":[

"infoItems",

"serviceName",

"system"

]

}

}

}

17

DB52/T1541.4—2021

GG

附錄G

（資料性）

數(shù)據(jù)資源目錄描述對象參數(shù)表

數(shù)據(jù)資源接口描述對象參數(shù)表見表G.1。

表G.1數(shù)據(jù)資源目錄描述對象參數(shù)表

參數(shù)名稱類型是否必填說明

infoItemsarray是信息項

serviceNamestring是服務名稱

systemobject是系統(tǒng)名稱

18

DB52/T1541.4—2021

HH

附錄H

（資料性）