网络请求服务

一、简介

C端 APP 提供了默认的网络请求服务,默认情况下是针对 XLINK 的接口使用。网络请求服务用于 SDK 统一发起接口请求,并返回统一的错误码格式及信息的 HTTP 请求处理服务。如果是需要发起 XLINK 相关的 API 请求,推荐优先使用网络请求服务。

网络请求服务默认将会使用授权服务中的用户授权信息,不再需要另行指定 Access-Token;网络请求服务也预定义了部分 XLINK 接口服务实现,可以通过接口直接进行 XLINK API 的调用,不用再另行定义接口并调用。

tips:默认情况下,网络请求服务在 SDK 初始化时一并初始化,不需要再另行注册初始化。

二、XLINK API 请求

如果需要发起 XLINK API 请求时,可以优先使用请求框架中提供的请求接口。以用户登录操作请求为例:

XLinkApiImplUser.postUserAuth(RequestUserAuth("企业ID","账号","密码",false))
    .asFlow()
    .onEach { println(it.accessToken) }
    .launchIn(GlobalScope)

tips:flow 为 kotlin 中提供的协程类,具体的使用请参考 kotlin 官方说明。

所有的 XLINK 接口遵循以下的命名规范:

  1. 可以直接调用的 API 接口为XLinkApiImpl前缀,后接相应的 API 模块名称,如用户相关接口为XLinkApiImplUser,设备相关接口为XLinkApiImplDevice
  2. 所有的请求参数类以Request前缀,后接 API 接口的相关描述,如用户登录授权请求参数为RequestUserAuth
  3. 所有的响应参数类以Response前缀,后接 API 接口的相关描述,与Request请求基本对应,如用户授权登录响应参数为ResponseUserAuth

注意在 XLINK API 发生变更时,相应的接口的参数和返回信息也可能会发生变更,使用 XLINK API 请求时,将会有以下的默认配置。

  1. 默认将会使用指定的路径进行请求,所有的请求路径在XLinkApiPath前缀,不同模块的名称作为后缀,如用户相关接口路径XLinkApiPathUser
  2. 默认使用的路径为相对路径,将会拼接上网络请求服务配置的域名。域名信息在xlink_config.xf的初始化配置文件中定义。
  3. 默认请求接口都会使用授权信息中的数据,在请求时拼接上Access-Token的授权信息。

tips:XLINK API 接口的请求仅适用于 XLINK 平台的请求,并且初始化配置文件中使用的域名相应的 XLINK 平台域名,以确保服务接口可以正常调用。如需灵活或定制性更强的接口,请使用通用 HTTP 请求

三、通用的 HTTP 请求服务

网络请求服务允许发起任意类型的 HTTP 请求操作,包含 XLINK 平台的 API 与非 XLINK 平台的接口都是允许的。HTTP 请求默认是使用 retrofit 请求框架发起的请求。

//请求类
class Request(val userId:String)
//返回类
class Response{
    //此处使用的是 gson 的序列化
    @SerializedName("access_token")
    var accessToken:String=""
}

fun sendRequest(){
    val params = Request("用户ID")
    HttpRequest()
        //指定请求方式
        .post()
        //设置请求路径,可以是相对地址或绝对地址
        .setUrl("/v2/xlink/test/{path_1}")
        //设置header中的参数
        .addHeaderParams("Access-Token","授权信息")
        //设置路径中的参数
        .addPathParams("{path_1}","路径")
        //设置查询参数
        .addQueryParam("id","查询参数")
        //设置body
        .setBodyFormatByGson(params)
        .createExecutor<Response>()
        .asFlow()
        .onEach { println(it.accessToken) }
        .launchIn(GlobalScope)
}

一般情况下,参考上述的请求构建方式,即可发起一个 http 请求,满足大部分情况下的需求。

tips:XLINK API 请求时数据序列化依赖于 Gson,对于参数与返回数据序列化时,请使用 Gson 进行序列化标识

1、其它请求操作

HttpRequest 提供了多种场景的使用接口,根据接口的要求可以使用不同的功能。

1.1、设置完整的请求链接

如果需要使用完整的请求链接,而不需要拼接配置文件中定义好的 baseUrl 时,请使用以下方法。

HttpRequest()
    ...
    .setCompleteUrl("完整的URL")
    ...

1.2、设置 json 字符串形式的 body

如果请求的 body 比较复杂或者是临时性数据,不方便构建成一个对象时,可以直接设置字符串形式的 body。

HttpRequest()
    ...
    .setBodyAsJson("""{"参数":"值"}""")
    ...

2、构建定制的 XLINK API 请求

由于网络服务中包含了 XLINK API 的接口处理,其中就包含了 XLINK API 的路径定义。常用的一些 API 路径已经定义到接口中了。所以对于 XLINK API 的接口请求也可以通过通用 HTTP 请求构建出来,以下的处理方式适用于某些接口变更或参数定制性较强的场景

下面以用户登录授权接口为例,该操作与XLinkApiImplUser.postUserAuth()的方法调用是相同的。

val request=RequestUserAuth("企业ID","账号","密码",false)
HttpRequest()
    .post()
    .setBodyFormatByGson(request)
    .createExecutor<ResponseUserAuth>()
    .asFlow()
    ...
没找到需要的文档?
你可以提交工单反馈 或 阅读常见问题