全部产品
云市场

OpenAPI 指南

更新时间:2018-12-10 20:27:02

简介

推送专有云为用户提供了一套服务端OpenAPI开放接口,用户可以在业务服务端使用API方式进行集成调用。

API定义

推送OpenAPI定义基于Swagger OpenAPI规范 编写(版本:3.0.0),客户端SDK与服务端API接口均严格遵循该定义(使用swagger-codegen工具自动生成)。

最新的API 定义文件在公共的Swagger Hub上

  1. API 定义文件

为了方便对照,这里贴了一份完整API定义(最新版本依然以上述链接为准):

  1. openapi: 3.0.0
  2. info:
  3. title: 移动推送服务端OpenAPI文档
  4. description: 移动推送服务端OpenAPI基于Swagger OpenAPI 3.0.0规范,本文档使用Swagger自动生成。
  5. version: '1.0.0'
  6. servers:
  7. - description: POC环境访问地址
  8. url: http://aserver.emas-poc.com/agoo/v1
  9. paths:
  10. /push:
  11. post:
  12. tags: [推送接口]
  13. description: |
  14. 执行推送调用,返回消息ID
  15. requestBody:
  16. content:
  17. application/json:
  18. schema:
  19. $ref: '#/components/schemas/PushRequest'
  20. description: 推送请求对象
  21. responses:
  22. '200':
  23. description: 推送成功
  24. content:
  25. application/json:
  26. schema:
  27. $ref: '#/components/schemas/PushResponse'
  28. '400':
  29. $ref: '#/components/responses/InvalidParam'
  30. '500':
  31. $ref: '#/components/responses/ServerError'
  32. components:
  33. responses:
  34. InvalidParam:
  35. description: 请求参数无效
  36. content:
  37. application/json:
  38. schema:
  39. $ref: '#/components/schemas/ErrorResponse'
  40. ServerError:
  41. description: 服务端异常
  42. content:
  43. application/json:
  44. schema:
  45. $ref: '#/components/schemas/ErrorResponse'
  46. schemas:
  47. PushRequest:
  48. type: object
  49. required:
  50. - appKey
  51. - serviceToken
  52. - title
  53. - content
  54. - sendType
  55. - expireTime
  56. properties:
  57. appKey:
  58. type: string
  59. description: 目标AppKey
  60. serviceToken:
  61. type: string
  62. description: 服务端Token
  63. title:
  64. type: string
  65. description: 推送标题
  66. subTitle:
  67. type: string
  68. description: 推送副标题(仅对iOS有效)
  69. content:
  70. type: string
  71. description: 推送内容
  72. sandbox:
  73. type: boolean
  74. description: 是否为开发环境(仅对iOS有效)
  75. actionType:
  76. type: string
  77. description: 后续操作类型:打开App/URL/ActivityiOS当前仅支持打开App
  78. enum:
  79. - OPEN_APP
  80. - OPEN_ACTIVITY
  81. - OPEN_URL
  82. default: OPEN_APP
  83. actionTarget:
  84. type: string
  85. description: 后续操作目标:具体要打开的URL/Activity
  86. sendType:
  87. type: string
  88. description: 发送类型:全推/按设备/按别名
  89. enum:
  90. - ALL
  91. - DEVICE
  92. - ALIAS
  93. targetDevices:
  94. type: array
  95. description: 目标设备列表
  96. items:
  97. type: string
  98. example: ['device1', 'device2']
  99. targetAliases:
  100. type: array
  101. description: 目标别名列表
  102. items:
  103. type: string
  104. example: ['alias1', 'alias2']
  105. badge:
  106. type: integer
  107. format: int32
  108. description: 角标数(仅对iOS有效)
  109. iconUrl:
  110. type: string
  111. description: 图标URL(仅对Android有效)
  112. remindType:
  113. type: string
  114. description: 提醒方式:震动、声音、震动+声音、无提醒(仅对Android有效)
  115. enum:
  116. - VIBRATION
  117. - SOUND
  118. - BOTH
  119. - NONE
  120. default: SOUND
  121. pictureResource:
  122. type: string
  123. description: 图片资源(仅对iOS有效)
  124. soundResource:
  125. type: string
  126. description: 声音资源
  127. silent:
  128. type: boolean
  129. description: 静默通知(仅对iOS有效)
  130. default: false
  131. notificationChannel:
  132. type: string
  133. description: Android 8.0 notification channel
  134. extParams:
  135. type: object
  136. description: 自定义参数
  137. example: {'k1': 'v1', 'k2': 'v2'}
  138. expireTime:
  139. type: string
  140. format: date-time
  141. description: 过期时间
  142. example: '2018-11-11T00:00:00.000Z'
  143. channel:
  144. type: string
  145. description: 指定通道:自有通道/华为/小米/魅族/OPPO(仅对Android有效)
  146. enum:
  147. - "accs"
  148. - "huawei"
  149. - "xiaomi"
  150. - "meizu"
  151. - "oppo"
  152. PushResponse:
  153. type: object
  154. required:
  155. - taskId
  156. properties:
  157. taskId:
  158. type: string
  159. ErrorResponse:
  160. type: object
  161. required:
  162. - code
  163. - message
  164. properties:
  165. code:
  166. type: integer
  167. message:
  168. type: string

SDK生成

打开Swagger Hub API定义页面,点击右上角Export->Client SDK,导出和下载指定语言版本的客户端SDK:

1

如果用户需要自己定制SDK的参数(比如包名、兼容的java版本),有两种方法:

  • 创建一个Hub账号,导入API定义文件,即可配置SDK生成参数(右上角的Codegen Options)。

2

  • 使用官方Github中的codegen-cli工具,通过命令行方式进行配置和SDK生成。

Demo代码

以Java客户端SDK为例,Demo代码如下(使用单元测试方式运行):

  1. public class PushDemoTest {
  2. // 推送API客户端
  3. private final DefaultApi api = new DefaultApi();
  4. @Test
  5. public void testPush() {
  6. // 默认为公共POC推送服务器地址,可修改为私有环境的对应地址
  7. api.getApiClient().setBasePath("http://localhost/agoo/v1");
  8. // 构造推送请求
  9. PushRequest pushRequest = new PushRequest();
  10. pushRequest.setAppKey("123456");
  11. pushRequest.setServiceToken("token");
  12. pushRequest.setTitle("title");
  13. pushRequest.setSubTitle("subTitle");
  14. pushRequest.setContent("content");
  15. pushRequest.setSandbox(true);
  16. pushRequest.setActionType(PushRequest.ActionTypeEnum.URL);
  17. pushRequest.setActionTarget("http://www.aliyun.com");
  18. pushRequest.setSendType(PushRequest.SendTypeEnum.ALIAS);
  19. pushRequest.setTargetAliases(Arrays.asList("alias1", "alias2"));
  20. pushRequest.setBadge(1);
  21. pushRequest.setIconUrl("iconUrl");
  22. pushRequest.setPictureResource("pictureResource");
  23. pushRequest.setRemindType(PushRequest.RemindTypeEnum.BOTH);
  24. pushRequest.setSoundResource("soundResource");
  25. pushRequest.setSilent(true);
  26. pushRequest.setNotificationChannel("notificationChannel");
  27. pushRequest.setChannel(PushRequest.ChannelEnum.ACCS);
  28. // 设置扩展参数
  29. Map<String, String> extParams = new HashMap<>();
  30. extParams.put("k1", "v1");
  31. extParams.put("k2", "v2");
  32. pushRequest.setExtParams(extParams);
  33. // 设置过期时间
  34. OffsetDateTime expireTime = OffsetDateTime.now().plusDays(1);
  35. pushRequest.setExpireTime(expireTime);
  36. try {
  37. // 发起推送请求
  38. PushResponse pushResponse = api.pushPost(pushRequest);
  39. // 推送成功,返回消息ID
  40. System.out.println("Push OK with taskID: " + pushResponse.getTaskId());
  41. } catch (ApiException e) {
  42. // 推送失败,抛出API异常
  43. if (e.getCode() == 0) {
  44. // 无HTTP状态码,本地连接错误
  45. System.err.println("Push failed locally with message: " + e.getMessage());
  46. } else {
  47. // 服务端返回错误,包含错误码和错误消息
  48. System.err.println("Push failed remotely with status '" + e.getCode()
  49. + "' and error response: " + e.getResponseBody());
  50. }
  51. e.printStackTrace();
  52. }
  53. }
  54. }

推送 basePath地址:请查看推送控制台概览页。

附录

错误码说明

错误码 描述 HTTP状态码
119130 缺少AppKey参数 400
119131 缺少Title参数 400
119132 缺少Content参数 400
119134 缺少ActionTarget参数 400
119135 缺少SendType参数 400
119136 缺少TargetDevices参数 400
119137 缺少TargetAliases参数 400
119138 缺少ExpireTime参数 400
119139 缺少Sandbox参数 400
119140 缺少ServiceToken参数 400
119150 Title长度超出限制 400
119151 SubTitle长度超出限制 400
119152 Content长度超出限制 400
119153 ActionTarget长度超出限制 400
119154 IconUrl长度超出限制 400
119155 PictureResource长度超出限制 400
119156 SoundResource长度超出限制 400
119157 NotificationChannel长度超出限制 400
119158 ExtParams key长度超出限制 400
119159 ExtParams value长度超出限制 400
119160 TargetDevices列表个数超出限制 400
119161 TargetAliases列表个数超出限制 400
119162 ExtParams key/value个数超出限制 400
119170 ActionType参数无效 400
119171 RemindType参数无效 400
119172 SendType参数无效 400
119173 ExtParams参数无效 400
119174 Badge参数无效 400
119175 ExpireTime参数无效 400
119190 ServiceToken未授权 400
100006 Bad Request(请求格式无效) 400
100001 Internal Error(服务端内部错误) 500

参数限制说明

参数名 类型 是否必填 限制条件
appKey String App在控制台上已创建
serviceToken String Token在控制台上已授权
title String 长度 <= 32字符
subTitle String 长度 <= 32字符
content String 长度 <= 500字符
sandbox Boolean 可选值:true / false
actionType Enum 可选值:OPEN_APP / OPEN_ACTIVITY / OPEN_URL默认值:OPEN_APP
actionTarget String actionType为OPEN_ACTIVITY或OPEN_URL时必填长度 <= 200字符
sendType Enum 可选值:ALL / DEVICE / ALIAS
targetDevices Array sendType为DEVICE时必填数组大小 <= 100
targetAliases Array sendType为ALIAS时必填数组大小 <= 100
badge Integer 数值范围:[0, 99999]
iconUrl String 长度 <= 200字符
pictureResource String 长度 <= 200字符
soundResource String 长度 <= 20字符
remindType Enum 可选值:VIBRATION / SOUND / BOTH / NONE默认值:SOUND
silent Boolean 可选值:true / false
notificationChannel String 长度 <= 20字符
extParams Map 参数Key/Value对个数 <= 5Key长度 <= 20字符,Value长度 <= 100字符
expireTime DateTime 有效范围:[当前时间 + 3秒,当前时间 + 3天]
channel Enum 可选值:accs / huawei / xiaomi / meizu / oppo