操作数据

Owned by Aileen (Unlicensed)
Last updated: 2019-05-07 by tuhao
15 min read

一. 操作简介

使用Postman可以查询系统前台与服务器的交互记录，例如列出当前账户下的所有用户（点击设置→用户)：

系统中所有的交互均可按照RESTFUL的GET/POST/PUT/DELETE操作进行。 第三方系统在开发时只要模拟JavaScript与后台交互的过程即可。
需要注意的是我们对POST和PUT做相同处理，只要在请求中包含了id字段的就认为是一个更新的动作，如果没有id动作就是添加处理。

Postman下载地址：https://www.getpostman.com/downloads/

Postman使用文档：https://learning.getpostman.com/docs/postman/launching_postman/sending_the_first_request/

中文使用帮助：https://blog.csdn.net/fxbin123/article/details/80428216


二. 示例

以consignment举例

添加

URIhttp://test.birdsystem.com/client/consignment
MethodPOST
Content-Typeapplication/json
URL Param-
Body Param
        {
            "delivery_service_id":1471,
            "contact":"Eddie dawson",
            "address_line1":"37 LYNAS gardens",
            "address_line2":"Grassendale",
            "city":"liverpool",
            "county":"Merseyside",
            "post_code":"l199bl",
            "country_iso":"GB",
            "telephone":"Tel:01519033363",
            "email":null,
            "sales_reference":"3", 
    		"type":"LOCAL"
        }
Response
{
    "data":[
        {
            "commodity_code":null,
            "total_price_customs_export":null,
            "name_customs":null,
            "total_quantity":null,
            "weight":null,
            "price":null,
            "price_customs_export":null,
            "period":null,
            "type":"LOCAL",
            "total":null,
            "external_code":null,
            "external_code1":null,
            "external_code2":null,
            "max_length":null,
            "max_width":null,
            "max_depth":null,
            "handling_fee_first_item":null,
            "handling_fee_other_item":null,
            "handling_fee_first_product":null,
            "handling_fee_other_product":null,
            "handling_fee":null,
            "handling_fee_urgent_consignment":null,
            "handling_fee_limit":null,
            "delivery_fee":null,
            "delivery_fee_type":null,
            "return_consignment_id":null,
            "return_consignment_action_type":null,
            "return_consignment_action_name":null,
            "quantity":null,
            "battery_type_name_list":null,
            "delivery_service_name":"飞鸟小包",
            "sku_count":null,
            "product_company_ref":null,
            "id":1707170020000004,
            "company_id":2,
            "client_id":1,
            "warehouse_id":null,
            "consignment_product_quantity":1,
            "consignment_product_reference":"1",
            "delivery_service_id":1471,
            "delivery_service_id_internal":1471,
            "delivery_package_size_id":432,
            "total_price":"0.00",
            "total_delivery_fee":"999.00",
            "total_handling_fee":"0.00",
            "total_weight":"30.00",
            "total_volume":"504000.00",
            "total_volume_weight":"504000.0000",
            "guarantee_percentage":"0.00",
            "contact":"Eddie dawson",
            "business_name":null,
            "address_line1":"37 LYNAS gardens",
            "address_line2":"Grassendale",
            "address_line3":null,
            "city":"liverpool",
            "county":"Merseyside",
            "post_code":"l199bl",
            "country_iso":"GB",
            "telephone":"Tel:01519033363",
            "email":null,
            "sender_contact":null,
            "sender_business_name":null,
            "sender_address_line1":null,
            "sender_address_line2":null,
            "sender_address_line3":null,
            "sender_city":null,
            "sender_county":null,
            "sender_post_code":null,
            "sender_country_iso":null,
            "sender_email":null,
            "sender_telephone":null,
            "sales_reference":"3",
            "payment_reference":null,
            "delivery_reference":null,
            "tracking_reference":null,
            "special_instruction":null,
            "neighbour_instruction":null,
            "temp_consignment_info_id":3,
            "is_urgent":0,
            "is_forced_delivery_service":0,
            "create_time":"2017-07-18 01:04:34",
            "finish_time":"2017-06-21 08:00:00",
            "arrive_time":null,
            "update_time":"2017-06-30 08:00:00",
            "status":"FINISHED",
            "primary_keys":[
                "id"
            ],
            "delivery_service_special_type":"HKSP",
            "delivery_service_is_use_delivery_agent_account_address":1,
            "consignment_delivery_agent-net17track_code":"ZZ",
            "country_name":"UNITED KINGDOM"
        }
    ],
    "success":true,
    "moduleName":"client"
}


查询某条记录

URIhttp://test.birdsystem.com/client/consignment
MethodGET
Content-Typeapplication/json
URL Paramid=1707170020000004
Body Param-
Response
{
    "total":1,
    "data":[
        {
            "commodity_code":null,
            "total_price_customs_export":null,
            "name_customs":null,
            "total_quantity":null,
            "weight":null,
            "price":null,
            "price_customs_export":null,
            "period":null,
            "type":"LOCAL",
            "total":null,
            "external_code":null,
            "external_code1":null,
            "external_code2":null,
            "max_length":null,
            "max_width":null,
            "max_depth":null,
            "handling_fee_first_item":null,
            "handling_fee_other_item":null,
            "handling_fee_first_product":null,
            "handling_fee_other_product":null,
            "handling_fee":null,
            "handling_fee_urgent_consignment":null,
            "handling_fee_limit":null,
            "delivery_fee":null,
            "delivery_fee_type":null,
            "return_consignment_id":null,
            "return_consignment_action_type":null,
            "return_consignment_action_name":null,
            "quantity":null,
            "battery_type_name_list":null,
            "delivery_service_name":"飞鸟小包",
            "sku_count":null,
            "product_company_ref":null,
            "id":1707170020000004,
            "company_id":2,
            "client_id":1,
            "warehouse_id":null,
            "consignment_product_quantity":1,
            "consignment_product_reference":"1",
            "delivery_service_id":1471,
            "delivery_service_id_internal":1471,
            "delivery_package_size_id":432,
            "total_price":"0.00",
            "total_delivery_fee":"999.00",
            "total_handling_fee":"0.00",
            "total_weight":"30.00",
            "total_volume":"504000.00",
            "total_volume_weight":"504000.0000",
            "guarantee_percentage":"0.00",
            "contact":"Eddie dawson",
            "business_name":null,
            "address_line1":"37 LYNAS gardens",
            "address_line2":"Grassendale",
            "address_line3":null,
            "city":"liverpool",
            "county":"Merseyside",
            "post_code":"l199bl",
            "country_iso":"GB",
            "telephone":"Tel:01519033363",
            "email":null,
            "sender_contact":null,
            "sender_business_name":null,
            "sender_address_line1":null,
            "sender_address_line2":null,
            "sender_address_line3":null,
            "sender_city":null,
            "sender_county":null,
            "sender_post_code":null,
            "sender_country_iso":null,
            "sender_email":null,
            "sender_telephone":null,
            "sales_reference":"3",
            "payment_reference":null,
            "delivery_reference":null,
            "tracking_reference":null,
            "special_instruction":null,
            "neighbour_instruction":null,
            "temp_consignment_info_id":3,
            "is_urgent":0,
            "is_forced_delivery_service":0,
            "create_time":"2017-07-18 01:04:34",
            "finish_time":"2017-06-21 08:00:00",
            "arrive_time":null,
            "update_time":"2017-06-30 08:00:00",
            "status":"FINISHED",
            "primary_keys":[
                "id"
            ],
            "delivery_service_special_type":"HKSP",
            "delivery_service_is_use_delivery_agent_account_address":1,
            "consignment_delivery_agent-net17track_code":"ZZ",
            "country_name":"UNITED KINGDOM"
        }
    ],
    "success":true,
    "moduleName":"client"
}

查询所有记录

URIhttp://test.birdsystem.com/client/consignment
MethodGET
Content-Typeapplication/json
URL Paramstart=0&limit=50&sort=[{"property":"update_time","direction":"DESC"}]

start: 从第几条记录开始查询, 选填, 默认0
limit: 查询多少条记录,  选填, 默认50
sort: 排序 property是列名, direction是方向, 例子中是根据id倒序查询

Body Param-
Response
{
    "total":914567,
    "data":Array[50],
    "success":true,
    "currency":"CNY",
    "moduleName":"admin"
}

查询所有记录时常用的参数

查询所有记录时，除了基本的start,limit,sort参数之外，还有一些其他常用参数，见下表　(以下参数都是以GET方式提交)

参数名类型说明示例
selectFields字符串查询返回的列表中需包含的字段 (需要进行URL encode)

例如 需要返回status,is_urgent,total_weight,total_volume_weight,type,update_time,create_time.

需要先将要返回的字段用逗号分隔,再进行URL编码

最终的URL参数为:

selectFields=status%2Cis_urgent%2Ctotal_weight%2Ctotal_volume_weight%2Ctype%2Cupdate_time%2Ccreate_time



filter字符串查询列表需要使用的过滤条件(需要进行URL encode)

例如 需要查询状态为FINISHED且更新时间大于2017-09-10的订单，条件是:

[
  {"type":"date","comparison":"gt","value":"2017-09-10","field":"update_time"},
  {"type":"list","value":["FINISHED"],"field":"status"}
].
经过URL编码后，最终的URL参数为:
filter=5B%7B%22type%22%3A%22date%22%2C%22comparison%22%3A%22gt%22%2C%22value%22%3A%222017-09-10%22%2C%22field%22%3A%22update_time%22%7D%2C%7B%22type%22%3A%22list%22%2C%22value%22%3A
%5B%22FINISHED%22%5D%2C%22field%22%3A%22status%22%7D%5D
条件有多种使用类型, 具体描述如下: 
string类型:   
         {"type":"string","value":"test","field":"sales_reference"}, 对应后台的  sales_reference like '%xxxxx%'
list类型:   
         {"type":"list","value":["FINISHED","PENDING'],"field":"status"}, 对应后台的  status in ('xxx','xxxx)
boolean类型: 
         {"type":"boolean", "value":'1', 'field': 'is_urgent'} , value为1或者0, 对应后台的   is_urgent = 1
numeric类型:
         {"type":"numeric","comparison":"ne","value":"1","field":"id"}, 对应后台的 id <> 1
         {"type":"numeric","comparison":"eq","value":"1","field":"id"},  : 对应后台的 id =1, 如果 value 是逗号分隔，相当于in 的效果. 例如value为1,2, 相当于 id in(1,2)
         {"type":"numeric","comparison":"gt","value":"1","field":"id"},   对应后台的 id >= 1
         {"type":"numeric","comparison":"lt","value":"1","field":"id"} ,  对应后台的  id <=1
         四个可以同时使用，也可以单独使用。是AND关系.
date类型:
        {"type":"date","comparison":"ne","value":"2018-11-21","field":"update_time"},  : 对应后台的 update_time <> '2018-11-21 00:00:00',
        {"type":"date","comparison":"eq","value":"2018-11-21","field":"update_time"},  : 对应后台的 update_time ='2018-11-21 00:00:00',
        {"type":"date","comparison":"gt","value":"2018-11-21 12:00:00","field":"update_time"},   对应后台的 update_time >= '2018-11-21 12:00:00'
        {"type":"date","comparison":"lt","value":"2018-11-21 12:00:00","field":"update_time"} ,  对应后台的  update_time <= '2018-11-21 12:00:00'
        四个可以同时使用，也可以单独使用。是AND关系.
各个API自定义的过滤参数字符串

不同的API为了方便查询数据，将一些常用字段配置成了过滤参数，直接传字段名及条件值即可生效.


各个API可用的条件，请见相关API说明文档

例如: Product产品列表，经常按client_ref或者status字段条件来筛选，而我们后台将这两个字段配置成了常用过滤条件。

那么可以在URL中传如下参数:

client_ref=IPxxx 或者 status=PENDING (可以多个条件同时使用)

修改

URIhttp://test.birdsystem.com/client/consignment
MethodPOST
Content-Typeapplication/json
URL Paramid=1707170020000004
Body Param
        {
            "delivery_service_id":1471,
            "contact":"Eddie dawson",
            "address_line1":"37 LYNAS gardens",
            "address_line2":"Grassendale",
            "city":"liverpool",
            "county":"Merseyside",
            "post_code":"l199bl",
            "country_iso":"GB",
            "telephone":"Tel:01519033363",
            "email":null,
            "sales_reference":"3", 
    		"type":"LOCAL"
        }
Response
{
    "data":[
        {
            "commodity_code":null,
            "total_price_customs_export":null,
            "name_customs":null,
            "total_quantity":null,
            "weight":null,
            "price":null,
            "price_customs_export":null,
            "period":null,
            "type":"LOCAL",
            "total":null,
            "external_code":null,
            "external_code1":null,
            "external_code2":null,
            "max_length":null,
            "max_width":null,
            "max_depth":null,
            "handling_fee_first_item":null,
            "handling_fee_other_item":null,
            "handling_fee_first_product":null,
            "handling_fee_other_product":null,
            "handling_fee":null,
            "handling_fee_urgent_consignment":null,
            "handling_fee_limit":null,
            "delivery_fee":null,
            "delivery_fee_type":null,
            "return_consignment_id":null,
            "return_consignment_action_type":null,
            "return_consignment_action_name":null,
            "quantity":null,
            "battery_type_name_list":null,
            "delivery_service_name":"飞鸟小包",
            "sku_count":null,
            "product_company_ref":null,
            "id":1707170020000004,
            "company_id":2,
            "client_id":1,
            "warehouse_id":null,
            "consignment_product_quantity":1,
            "consignment_product_reference":"1",
            "delivery_service_id":1471,
            "delivery_service_id_internal":1471,
            "delivery_package_size_id":432,
            "total_price":"0.00",
            "total_delivery_fee":"999.00",
            "total_handling_fee":"0.00",
            "total_weight":"30.00",
            "total_volume":"504000.00",
            "total_volume_weight":"504000.0000",
            "guarantee_percentage":"0.00",
            "contact":"Eddie dawson",
            "business_name":null,
            "address_line1":"37 LYNAS gardens",
            "address_line2":"Grassendale",
            "address_line3":null,
            "city":"liverpool",
            "county":"Merseyside",
            "post_code":"l199bl",
            "country_iso":"GB",
            "telephone":"Tel:01519033363",
            "email":null,
            "sender_contact":null,
            "sender_business_name":null,
            "sender_address_line1":null,
            "sender_address_line2":null,
            "sender_address_line3":null,
            "sender_city":null,
            "sender_county":null,
            "sender_post_code":null,
            "sender_country_iso":null,
            "sender_email":null,
            "sender_telephone":null,
            "sales_reference":"3",
            "payment_reference":null,
            "delivery_reference":null,
            "tracking_reference":null,
            "special_instruction":null,
            "neighbour_instruction":null,
            "temp_consignment_info_id":3,
            "is_urgent":0,
            "is_forced_delivery_service":0,
            "create_time":"2017-07-18 01:04:34",
            "finish_time":"2017-06-21 08:00:00",
            "arrive_time":null,
            "update_time":"2017-06-30 08:00:00",
            "status":"FINISHED",
            "primary_keys":[
                "id"
            ],
            "delivery_service_special_type":"HKSP",
            "delivery_service_is_use_delivery_agent_account_address":1,
            "consignment_delivery_agent-net17track_code":"ZZ",
            "country_name":"UNITED KINGDOM"
        }
    ],
    "success":true,
    "moduleName":"client"
}

删除

URIhttp://test.birdsystem.com/client/consignment
MethodDELETE
Content-Typeapplication/json
URL Paramid=1707170020000004
Body Param-
Response
{
    "success":true,
    "message":"删除成功",
    "refresh":false,
    "moduleName":"client"
}

三. 更多

在这个页面下的所有连接都可以进行restful操作

常用数据接口和规则