在途开放接口SDK

旨在让开发者便捷的调用在途开放API、处理订阅的消息事件、处理服务端推送的卡片行为。

安装

运行环境：JDK 1.8及以上
最新版本 maven 坐标

<dependency>
    <groupId>io.gitee.z-trip</groupId>
    <artifactId>openapi-sdk</artifactId>
    <version>0.0.3</version>
</dependency>

API Client

开发者在调用 API 前，需要先创建一个 API Client，然后才可以基于 API Client 发起 API 调用。

创建API Client

对于自建应用，可使用下面代码来创建一个 API Client

  // 默认配置为自建应用 
  OpenapiClient openapiClient = DefaultOpenapiClient.newBuilder("${clientId}", "${clientSecret}")
          .serverUrl("https://openapi-uat.z-trip.cn").build();

配置API Client

创建 API Client 时，可对 API Client 进行一定的配置，比如我们可以在创建 API Client 时设置日志级别、设置 http 请求超时时间等等：

OpenapiClient openapiClient = DefaultOpenapiClient.newBuilder("${clientId}", "${clientSecret}")
        .serverUrl("https://openapi-uat.z-trip.cn") //设置服务端地址
        .connectTimeout() //设置连接超时时间
        .readTimeout() //设置读取超时时间
        .httpTransport() //设置http请求处理器
        .cache() //设置缓存处理器
        .build(); //创建API Client

每个配置选项的具体含义，如下表格：

配置选项	配置方式	描述
`serverUrl`	`client.serverUrl(String url)`	设置在途不同环境地址
`cache`	`client.cache(ICache cache)`	设置 token 缓存器，用来缓存 token, 默认实现为内存。如开发者想要定制 token 缓存器，需实现下面 Cache 接口: `public interface ICache { // 获取缓存值 String get(String key); // 设置缓存值 void set(String key, String value, int expire); }`
`connectTimeout`	`client.connectTimeout(long timeout)`	设置 SDK 内置的 Http Client 的请求超时时间，默认为0代表永不超时。
`readTimeout`	`client.readTimeout(long timeout)`	设置 SDK 内置的 Http Client 的超时时间，默认为0代表永不超时。
`httpTransport`	`client.httpTransport(IHttpTransport httpTransport)`	设置传输层实现，用于替换 SDK 提供的默认实现。开发者可通过实现下面的 IHttpTransport 接口来设置自定义的传输实现: `public interface IHttpTransport { String doGet(String url, Map<String, String> params); String doPost(String url, String content, int connectTimeout, int readTimeout, Map<String, String> headers); }`

API调用

创建完毕 API Client，我们可以使用 Client.业务域.资源.方法名称 来定位具体的 API 方法，然后对具体的 API 发起调用。

基本用法

如下示例我们通过 client 调用组织同步：

import com.openapi.api.DefaultOpenapiClient;
import com.openapi.api.OpenApiException;
import com.openapi.api.OpenapiClient;
import com.openapi.api.request.*;
import com.openapi.api.response.*;

public class OrgSyncSample {
  
  public static void main(String arg[]) throws Exception {
    // 构建client
    OpenapiClient openapiClient = DefaultOpenapiClient.newBuilder("${clientId}", "${clientSecret}")
                .serverUrl("https://openapi-uat.z-trip.cn").build();

    // 发起请求
    OrgSyncRequest orgSyncRequest = new OrgSyncRequest();
        orgSyncRequest.setCode("12345");
        orgSyncRequest.setName("测试组织");
        orgSyncRequest.setFullName("测试组织全称");
        orgSyncRequest.setType(1);
        orgSyncRequest.setParentCode("1234");


        OrgSyncResponse orgSyncResponse = openapiClient.execute(orgSyncRequest);

    // 处理服务端错误
    if (!orgSyncResponse.success()) {
      System.out.println("error");
      return;
    }

  }
}

如下示例我们通过 client 调用人员同步：

import com.openapi.api.DefaultOpenapiClient;
import com.openapi.api.OpenApiException;
import com.openapi.api.OpenapiClient;
import com.openapi.api.request.*;
import com.openapi.api.response.*;

public class UserSyncSample {
  
  public static void main(String arg[]) throws Exception {
    // 构建client
    OpenapiClient openapiClient = DefaultOpenapiClient.newBuilder("${clientId}", "${clientSecret}")
                .serverUrl("https://openapi-uat.z-trip.cn").build();

    // 发起请求
     UserSyncRequest syncRequest = new UserSyncRequest();
        syncRequest.setEmpCode("10001");
        syncRequest.setOrgId("12345");
        syncRequest.setStatus("0");
        syncRequest.setFullName("张三");


        UserSyncResponse userSyncResponse = openapiClient.execute(syncRequest);
        System.out.println(userSyncResponse.getError());
        System.out.println(userSyncResponse.getErrorDescription());

    // 处理服务端错误
    if (!userSyncResponse.success()) {
      System.out.println("error");
      return;
    }

  }
}

处理消息事件回调

关于消息事件回调相关的知识，可以点击这里查看

集成SpringBoot

本节将详细介绍，如何使用SpringBoot Web 框架集成Sdk。

安装集成包

要想把 Sdk 集成已有 SpringBoot 框架，开发者需要引入集成包

需在项目 pom 文件中引入下面 maven

<dependency>
    <groupId>io.gitee.z-trip</groupId>
    <artifactId>openapi-sdk</artifactId>
    <version>0.0.3</version>
</dependency>

集成示例

注入 EventServletAdapter 实例到 IOC 容器

import com.openapi.api.sdk.servlet.EventServletAdapter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class TripConfig {

    @Bean
    public EventServletAdapter servletAdapter(){
        return new EventServletAdapter();
    }
}

编写 Controller 注册事件处理器

import com.example.openapisdkexample.service.TripOpenapiService;
import com.openapi.api.sdk.servlet.EventServletAdapter;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@RestController
public class EventController {

    @Resource
    private EventServletAdapter eventServletAdapter;
    @Resource
    private TripOpenapiService tripOpenapiService;

    @RequestMapping("/webhook/event")
    public void eventHandler(HttpServletRequest request, HttpServletResponse response) throws Throwable {
        eventServletAdapter.handleEvent(request, response, tripOpenapiService.eventDispatcher());
    }
}

import com.openapi.api.event.EventDispatcher;
import com.openapi.api.event.order.v1.OrderService;
import V1HotelOrderIssued;
import V1HotelOrderPush;
import org.springframework.stereotype.Service;

@Service
public class TripOpenapiService {


    public EventDispatcher eventDispatcher() {

        return new EventDispatcher.Builder()
                .aesKey("${aesKey}")
                .onV1HotelOrderPush(new OrderService.V1HotelOrderPushHandler() {
                    @Override
                    public Void handle(V1HotelOrderPush v1HotelOrderPush) throws Exception {
                        // 处理业务逻辑
                        return null;
                    }
                })
                .onV1HotelOrderIssued(new OrderService.V1HotelOrderIssuedHandler() {
                    @Override
                    public Void handle(V1HotelOrderIssued v1HotelOrderIssued) throws Exception {
                        // 处理业务逻辑
                        return null;
                    }
                }).build();
    }
}

8、openapi-sdk