🆕 #1369 【企业微信】增加效率工具-日程相关接口

2025-12-16 20:28:11 +08:00 · 2020-12-25 17:09:18 +08:00
parent 55e1399fe8
commit 02d3c160b2
12 changed files with 501 additions and 48 deletions
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpOaScheduleService.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpOaScheduleService.java
@@ -0,0 +1,88 @@
+package me.chanjar.weixin.cp.api;
+
+import me.chanjar.weixin.common.error.WxErrorException;
+import me.chanjar.weixin.cp.bean.oa.WxCpOaSchedule;
+
+import java.util.List;
+
+/**
+ * 企业微信日程接口.
+ * 官方文档：https://work.weixin.qq.com/api/doc/90000/90135/93648
+ *
+ * @author <a href="https://github.com/binarywang">Binary Wang</a>
+ * @date 2020 -12-25
+ */
+public interface WxCpOaScheduleService {
+  /**
+   * 创建日程
+   * <p>
+   * 该接口用于在日历中创建一个日程。
+   * <p>
+   * 请求方式： POST（HTTPS）
+   * 请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/add?access_token=ACCESS_TOKEN
+   *
+   * @param schedule the schedule
+   * @param agentId  授权方安装的应用agentid。仅旧的第三方多应用套件需要填此参数
+   * @return 日程ID string
+   * @throws WxErrorException the wx error exception
+   */
+  String add(WxCpOaSchedule schedule, Integer agentId) throws WxErrorException;
+
+  /**
+   * 更新日程
+   * <p>
+   * 该接口用于在日历中更新指定的日程。
+   * <p>
+   * 注意，更新操作是覆盖式，而不是增量式
+   * 不可更新组织者和日程所属日历ID
+   * <p>
+   * 请求方式： POST（HTTPS）
+   * 请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/update?access_token=ACCESS_TOKEN
+   *
+   * @param schedule the schedule
+   * @throws WxErrorException the wx error exception
+   */
+  void update(WxCpOaSchedule schedule) throws WxErrorException;
+
+  /**
+   * 获取日程详情
+   * <p>
+   * 该接口用于获取指定的日程详情。
+   * <p>
+   * 请求方式： POST（HTTPS）
+   * 请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/get?access_token=ACCESS_TOKEN
+   *
+   * @param scheduleIds the schedule ids
+   * @return the details
+   * @throws WxErrorException the wx error exception
+   */
+  List<WxCpOaSchedule> getDetails(List<String> scheduleIds) throws WxErrorException;
+
+  /**
+   * 取消日程
+   * 该接口用于取消指定的日程。
+   * <p>
+   * 请求方式： POST（HTTPS）
+   * 请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/del?access_token=ACCESS_TOKEN
+   *
+   * @param scheduleId 日程id
+   * @throws WxErrorException the wx error exception
+   */
+  void delete(String scheduleId) throws WxErrorException;
+
+  /**
+   * 获取日历下的日程列表
+   * 该接口用于获取指定的日历下的日程列表。
+   * 仅可获取应用自己创建的日历下的日程。
+   * <p>
+   * 请求方式： POST（HTTPS）
+   * 请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/get_by_calendar?access_token=ACCESS_TOKEN
+   *
+   * @param calId  日历ID
+   * @param offset 分页，偏移量, 默认为0
+   * @param limit  分页，预期请求的数据量，默认为500，取值范围 1 ~ 1000
+   * @return the string
+   * @throws WxErrorException the wx error exception
+   */
+  List<WxCpOaSchedule> listByCalendar(String calId, Integer offset, Integer limit) throws WxErrorException;
+}
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpService.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpService.java
@@ -1,7 +1,5 @@
 package me.chanjar.weixin.cp.api;

-import com.google.gson.JsonObject;
-import me.chanjar.weixin.common.bean.ToJson;
 import me.chanjar.weixin.common.bean.WxJsapiSignature;
 import me.chanjar.weixin.common.error.WxErrorException;
 import me.chanjar.weixin.common.service.WxService;
@@ -39,7 +37,7 @@ public interface WxCpService extends WxService {
   *
   * @return the access token
   * @throws WxErrorException the wx error exception
-   * @see #getAccessToken(boolean) #getAccessToken(boolean)
+   * @see #getAccessToken(boolean) #getAccessToken(boolean)#getAccessToken(boolean)
   */
  String getAccessToken() throws WxErrorException;

@@ -63,7 +61,7 @@ public interface WxCpService extends WxService {
   *
   * @return the jsapi ticket
   * @throws WxErrorException the wx error exception
-   * @see #getJsapiTicket(boolean) #getJsapiTicket(boolean)
+   * @see #getJsapiTicket(boolean) #getJsapiTicket(boolean)#getJsapiTicket(boolean)
   */
  String getJsapiTicket() throws WxErrorException;

@@ -90,7 +88,7 @@ public interface WxCpService extends WxService {
   *
   * @return the agent jsapi ticket
   * @throws WxErrorException the wx error exception
-   * @see #getJsapiTicket(boolean) #getJsapiTicket(boolean)
+   * @see #getJsapiTicket(boolean) #getJsapiTicket(boolean)#getJsapiTicket(boolean)
   */
  String getAgentJsapiTicket() throws WxErrorException;

@@ -376,10 +374,17 @@ public interface WxCpService extends WxService {
  /**
   * 获取日历相关接口的服务类对象
   *
-   * @return the menu service
+   * @return the oa calendar service
   */
  WxCpOaCalendarService getOaCalendarService();

+  /**
+   * 获取日程相关接口的服务类对象
+   *
+   * @return the oa schedule service
+   */
+  WxCpOaScheduleService getOaScheduleService();
+
  /**
   * 获取群机器人消息推送服务
   *
@@ -387,11 +392,11 @@ public interface WxCpService extends WxService {
   */
  WxCpGroupRobotService getGroupRobotService();

-  /*
+  /**
   * 获取工作台服务
   *
   * @return the workbench service
-   * */
+   */
  WxCpAgentWorkBenchService getWorkBenchService();

  /**
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/BaseWxCpServiceImpl.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/BaseWxCpServiceImpl.java
@@ -55,6 +55,7 @@ public abstract class BaseWxCpServiceImpl<H, P> implements WxCpService, RequestH
  private WxCpGroupRobotService groupRobotService = new WxCpGroupRobotServiceImpl(this);
  private WxCpMessageService messageService = new WxCpMessageServiceImpl(this);
  private WxCpOaCalendarService oaCalendarService = new WxCpOaCalendarServiceImpl(this);
+  private WxCpOaScheduleService oaScheduleService = new WxCpOaOaScheduleServiceImpl(this);
  private WxCpAgentWorkBenchService workBenchService = new WxCpAgentWorkBenchServiceImpl(this);

  /**
@@ -512,4 +513,9 @@ public abstract class BaseWxCpServiceImpl<H, P> implements WxCpService, RequestH
  public void setAgentService(WxCpAgentService agentService) {
    this.agentService = agentService;
  }
+
+  @Override
+  public WxCpOaScheduleService getOaScheduleService() {
+    return this.oaScheduleService;
+  }
 }
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/WxCpOaOaScheduleServiceImpl.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/WxCpOaOaScheduleServiceImpl.java
@@ -0,0 +1,82 @@
+package me.chanjar.weixin.cp.api.impl;
+
+import com.google.common.collect.ImmutableMap;
+import com.google.gson.reflect.TypeToken;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import me.chanjar.weixin.common.error.WxErrorException;
+import me.chanjar.weixin.common.util.json.GsonParser;
+import me.chanjar.weixin.cp.api.WxCpOaScheduleService;
+import me.chanjar.weixin.cp.api.WxCpService;
+import me.chanjar.weixin.cp.bean.oa.WxCpOaSchedule;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.io.Serializable;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static me.chanjar.weixin.cp.constant.WxCpApiPathConsts.Oa.*;
+
+/**
+ * 企业微信日程接口实现类.
+ *
+ * @author <a href="https://github.com/binarywang">Binary Wang</a>
+ * @date 2020-12-25
+ */
+@Slf4j
+@RequiredArgsConstructor
+public class WxCpOaOaScheduleServiceImpl implements WxCpOaScheduleService {
+  private final WxCpService cpService;
+
+  @Override
+  public String add(WxCpOaSchedule schedule, Integer agentId) throws WxErrorException {
+    Map<String, Serializable> param;
+    if (agentId == null) {
+      param = ImmutableMap.of("schedule", schedule);
+    } else {
+      param = ImmutableMap.of("schedule", schedule, "agentid", agentId);
+    }
+
+    return this.cpService.post(this.cpService.getWxCpConfigStorage().getApiUrl(SCHEDULE_ADD),
+      WxCpGsonBuilder.create().toJson(param));
+  }
+
+  @Override
+  public void update(WxCpOaSchedule schedule) throws WxErrorException {
+    this.cpService.post(this.cpService.getWxCpConfigStorage().getApiUrl(SCHEDULE_UPDATE),
+      WxCpGsonBuilder.create().toJson(ImmutableMap.of("schedule", schedule)));
+  }
+
+  @Override
+  public List<WxCpOaSchedule> getDetails(List<String> scheduleIds) throws WxErrorException {
+    final String response = this.cpService.post(this.cpService.getWxCpConfigStorage().getApiUrl(SCHEDULE_GET),
+      WxCpGsonBuilder.create().toJson(ImmutableMap.of("schedule_id_list", scheduleIds)));
+    return WxCpGsonBuilder.create().fromJson(GsonParser.parse(response).get("schedule_list"),
+      new TypeToken<List<WxCpOaSchedule>>() {
+      }.getType());
+  }
+
+  @Override
+  public void delete(String scheduleId) throws WxErrorException {
+    this.cpService.post(this.cpService.getWxCpConfigStorage().getApiUrl(SCHEDULE_DEL),
+      WxCpGsonBuilder.create().toJson(ImmutableMap.of("schedule_id", scheduleId)));
+  }
+
+  @Override
+  public List<WxCpOaSchedule> listByCalendar(String calId, Integer offset, Integer limit) throws WxErrorException {
+    final Map<String, Object> param = new HashMap<>(3);
+    param.put("cal_id", calId);
+    if (offset != null) {
+      param.put("offset", offset);
+    }
+    if (limit != null) {
+      param.put("limit", limit);
+    }
+    final String response = this.cpService.post(this.cpService.getWxCpConfigStorage().getApiUrl(SCHEDULE_LIST),
+      WxCpGsonBuilder.create().toJson(param));
+    return WxCpGsonBuilder.create().fromJson(GsonParser.parse(response).get("schedule_list"),
+      new TypeToken<List<WxCpOaSchedule>>() {
+      }.getType());
+  }
+}
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/message/WxCpMessage.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/message/WxCpMessage.java
@@ -199,7 +199,7 @@ public class WxCpMessage implements Serializable {
    if (this.getDuplicateCheckInterval() != null) {
      messageJson.addProperty("duplicate_check_interval", this.getDuplicateCheckInterval());
    }
-    
+
    this.handleMsgType(messageJson);

    if (StringUtils.isNotBlank(this.getSafe())) {
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/oa/WxCpOaSchedule.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/oa/WxCpOaSchedule.java
@@ -0,0 +1,194 @@
+package me.chanjar.weixin.cp.bean.oa;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.experimental.Accessors;
+import me.chanjar.weixin.common.bean.ToJson;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * 日程信息bean.
+ *
+ * @author <a href="https://github.com/binarywang">Binary Wang</a>
+ * @date 2020-12-25
+ */
+@Data
+@Accessors(chain = true)
+public class WxCpOaSchedule implements Serializable, ToJson {
+  private static final long serialVersionUID = -6821274247372646346L;
+  /**
+   * 日程id
+   */
+  @SerializedName("schedule_id")
+  private String scheduleId;
+  /**
+   * 日程编号，是一个自增数字
+   */
+  @SerializedName("sequence")
+  private Integer sequence;
+  /**
+   * 组织者。不多于64字节
+   */
+  @SerializedName("organizer")
+  private String organizer;
+  /**
+   * 日程参与者列表。最多支持2000人
+   */
+  @SerializedName("attendees")
+  private List<Attendee> attendees;
+  /**
+   * 日程标题。0 ~ 128 字符。不填会默认显示为“新建事件”
+   */
+  @SerializedName("summary")
+  private String summary;
+  /**
+   * 日程描述。不多于512个字符
+   */
+  @SerializedName("description")
+  private String description;
+  /**
+   * 提醒相关信息
+   */
+  @SerializedName("reminders")
+  private Reminder reminders;
+  /**
+   * 日程地址。
+   * 不多于128个字符
+   */
+  @SerializedName("location")
+  private String location;
+  /**
+   * 日程开始时间，Unix时间戳
+   */
+  @SerializedName("start_time")
+  private Long startTime;
+  /**
+   * 日程结束时间，Unix时间戳
+   */
+  @SerializedName("end_time")
+  private Long endTime;
+  /**
+   *
+   */
+  @SerializedName("status")
+  private Integer status;
+  /**
+   * 日程所属日历ID。该日历必须是access_token所对应应用所创建的日历。
+   * 注意，这个日历必须是属于组织者(organizer)的日历；
+   * 如果不填，那么插入到组织者的默认日历上。
+   * 第三方应用必须指定cal_id
+   * 不多于64字节
+   */
+  @SerializedName("cal_id")
+  private String calId;
+
+  @Override
+  public String toJson() {
+    return WxCpGsonBuilder.create().toJson(this);
+  }
+
+  @Data
+  @Accessors(chain = true)
+  public static class Attendee implements Serializable {
+    private static final long serialVersionUID = 5419000348428480645L;
+    /**
+     * 日程参与者ID，
+     * 不多于64字节
+     */
+    @SerializedName("userid")
+    private String userid;
+    /**
+     * 日程参与者的接受状态。
+     * 0 - 未处理
+     * 1 - 待定
+     * 2 - 全部接受
+     * 3 - 仅接受一次
+     * 4 - 拒绝
+     */
+    @SerializedName("response_status")
+    private Integer responseStatus;
+  }
+
+  @Data
+  @Accessors(chain = true)
+  public static class Reminder implements Serializable {
+    private static final long serialVersionUID = 5030527150838243356L;
+
+    /**
+     * 是否需要提醒。0-否；1-是
+     */
+    @SerializedName("is_remind")
+    private Integer isRemind;
+    /**
+     * 是否重复日程。0-否；1-是
+     */
+    @SerializedName("is_repeat")
+    private Integer isRepeat;
+    /**
+     * 日程开始（start_time）前多少秒提醒，当is_remind为1时有效。
+     * 例如： 300表示日程开始前5分钟提醒。目前仅支持以下数值：
+     * 0 - 事件开始时
+     * 300 - 事件开始前5分钟
+     * 900 - 事件开始前15分钟
+     * 3600 - 事件开始前1小时
+     * 86400 - 事件开始前1天
+     */
+    @SerializedName("remind_before_event_secs")
+    private Integer remindBeforeEventSecs;
+    /**
+     * 重复类型，当is_repeat为1时有效。目前支持如下类型：
+     * 0 - 每日
+     * 1 - 每周
+     * 2 - 每月
+     * 5 - 每年
+     * 7 - 工作日
+     */
+    @SerializedName("repeat_type")
+    private Integer repeatType;
+    /**
+     * 重复结束时刻，Unix时间戳。不填或填0表示一直重复
+     */
+    @SerializedName("repeat_until")
+    private Long repeatUntil;
+    /**
+     * 是否自定义重复。0-否；1-是
+     */
+    @SerializedName("is_custom_repeat")
+    private Integer isCustomRepeat;
+    /**
+     * 重复间隔
+     * 仅当指定为自定义重复时有效
+     * 该字段随repeat_type不同而含义不同
+     * 例如：
+     * repeat_interval指定为3，repeat_type指定为每周重复，那么每3周重复一次；
+     * repeat_interval指定为3，repeat_type指定为每月重复，那么每3个月重复一次
+     */
+    @SerializedName("repeat_interval")
+    private Integer repeatInterval;
+    /**
+     * 每周周几重复
+     * 仅当指定为自定义重复且重复类型为每周时有效
+     * 取值范围：1 ~ 7，分别表示周一至周日
+     */
+    @SerializedName("repeat_day_of_week")
+    private List<Integer> repeatDayOfWeek;
+    /**
+     * 每月哪几天重复
+     * 仅当指定为自定义重复且重复类型为每月时有效
+     * 取值范围：1 ~ 31，分别表示1~31号
+     */
+    @SerializedName("repeat_day_of_month")
+    private List<Integer> repeatDayOfMonth;
+    /**
+     * 时区。UTC偏移量表示(即偏离零时区的小时数)，东区为正数，西区为负数。
+     * 例如：+8 表示北京时间东八区
+     * 默认为北京时间东八区
+     * 取值范围：-12 ~ +12
+     */
+    @SerializedName("timezone")
+    private Integer timezone;
+  }
+}
--- a/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/constant/WxCpApiPathConsts.java
+++ b/weixin-java-cp/src/main/java/me/chanjar/weixin/cp/constant/WxCpApiPathConsts.java
@@ -113,6 +113,12 @@ public final class WxCpApiPathConsts {
    public static final String CALENDAR_UPDATE = "/cgi-bin/oa/calendar/update";
    public static final String CALENDAR_GET = "/cgi-bin/oa/calendar/get";
    public static final String CALENDAR_DEL = "/cgi-bin/oa/calendar/del";
+
+    public static final String SCHEDULE_ADD = "/cgi-bin/oa/schedule/add";
+    public static final String SCHEDULE_UPDATE = "/cgi-bin/oa/schedule/update";
+    public static final String SCHEDULE_GET = "/cgi-bin/oa/schedule/get";
+    public static final String SCHEDULE_DEL = "/cgi-bin/oa/schedule/del";
+    public static final String SCHEDULE_LIST = "/cgi-bin/oa/schedule/get_by_calendar";
  }

  @UtilityClass
--- a/weixin-java-cp/src/test/java/me/chanjar/weixin/cp/api/impl/WxCpOaScheduleServiceImplTest.java
+++ b/weixin-java-cp/src/test/java/me/chanjar/weixin/cp/api/impl/WxCpOaScheduleServiceImplTest.java
@@ -0,0 +1,54 @@
+package me.chanjar.weixin.cp.api.impl;
+
+import com.google.inject.Inject;
+import me.chanjar.weixin.common.error.WxErrorException;
+import me.chanjar.weixin.cp.api.ApiTestModule;
+import me.chanjar.weixin.cp.api.WxCpService;
+import me.chanjar.weixin.cp.bean.oa.WxCpOaSchedule;
+import org.testng.annotations.Guice;
+import org.testng.annotations.Test;
+
+import java.util.Arrays;
+
+
+/**
+ * 单元测试类.
+ *
+ * @author <a href="https://github.com/binarywang">Binary Wang</a>
+ * @date 2020-12-25
+ */
+@Test
+@Guice(modules = ApiTestModule.class)
+public class WxCpOaScheduleServiceImplTest {
+  @Inject
+  protected WxCpService wxService;
+
+  @Test
+  public void testAdd() throws WxErrorException {
+    this.wxService.getOaScheduleService().add(new WxCpOaSchedule().setOrganizer("userid1")
+      .setDescription("description").setStartTime(111111111111L).setEndTime(222222222222L)
+      .setSummary("summary"), null);
+  }
+
+  @Test
+  public void testUpdate() throws WxErrorException {
+    this.wxService.getOaScheduleService().update(new WxCpOaSchedule().setScheduleId("2222").setOrganizer("userid1")
+      .setDescription("description").setStartTime(111111111111L).setEndTime(222222222222L)
+      .setSummary("summary"));
+  }
+
+  @Test
+  public void testGetDetails() throws WxErrorException {
+    this.wxService.getOaScheduleService().getDetails(Arrays.asList("11111"));
+  }
+
+  @Test
+  public void testDelete() throws WxErrorException {
+    this.wxService.getOaScheduleService().delete("111");
+  }
+
+  @Test
+  public void testListByCalendar() throws WxErrorException {
+    this.wxService.getOaScheduleService().listByCalendar("111", null, null);
+  }
+}