简介

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

API定义

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

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

1. API 定义文件

为了方便对照，这里贴了一份完整API定义（最新版本依然以上述链接为准）：

openapi: 3.0.0
info:
  title: 移动推送服务端OpenAPI文档
  description: 移动推送服务端OpenAPI基于Swagger OpenAPI 3.0.0规范，本文档使用Swagger自动生成。
  version: '1.0.0'
servers:
- description: POC环境访问地址
  url: http://aserver.emas-poc.com/agoo/v1
paths:
  /push:
    post:
      tags: [推送接口]
      description: |
        执行推送调用，返回消息ID。
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushRequest'
        description: 推送请求对象
      responses:
        '200':
          description: 推送成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushResponse'
        '400':
          $ref: '#/components/responses/InvalidParam'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    InvalidParam:
      description: 请求参数无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: 服务端异常
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    PushRequest:
      type: object
      required:
      - appKey
      - serviceToken
      - title
      - content
      - sendType
      - expireTime
      properties:
        appKey:
          type: string
          description: 目标AppKey
        serviceToken:
          type: string
          description: 服务端Token
        title:
          type: string
          description: 推送标题
        subTitle:
          type: string
          description: 推送副标题（仅对iOS有效）
        content:
          type: string
          description: 推送内容
        sandbox:
          type: boolean
          description: 是否为开发环境（仅对iOS有效）
        actionType:
          type: string
          description: 后续操作类型：打开App/URL/Activity（iOS当前仅支持打开App）
          enum:
          - OPEN_APP
          - OPEN_ACTIVITY
          - OPEN_URL
          default: OPEN_APP
        actionTarget:
          type: string
          description: 后续操作目标：具体要打开的URL/Activity
        sendType:
          type: string
          description: 发送类型：全推/按设备/按别名
          enum:
          - ALL
          - DEVICE
          - ALIAS
        targetDevices:
          type: array
          description: 目标设备列表
          items:
            type: string
          example: ['device1', 'device2']
        targetAliases:
          type: array
          description: 目标别名列表
          items:
            type: string
          example: ['alias1', 'alias2']
        badge:
          type: integer
          format: int32
          description: 角标数（仅对iOS有效）
        iconUrl:
          type: string
          description: 图标URL（仅对Android有效）
        remindType:
          type: string
          description: 提醒方式：震动、声音、震动+声音、无提醒（仅对Android有效）
          enum:
          - VIBRATION
          - SOUND
          - BOTH
          - NONE
          default: SOUND
        pictureResource:
          type: string
          description: 图片资源（仅对iOS有效）
        soundResource:
          type: string
          description: 声音资源
        silent:
          type: boolean
          description: 静默通知（仅对iOS有效）
          default: false
        notificationChannel:
          type: string
          description: Android 8.0 notification channel
        extParams:
          type: object
          description: 自定义参数
          example: {'k1': 'v1', 'k2': 'v2'}
        expireTime:
          type: string
          format: date-time
          description: 过期时间
          example: '2018-11-11T00:00:00.000Z'
        channel:
          type: string
          description: 指定通道：自有通道/华为/小米/魅族/OPPO（仅对Android有效）
          enum:
          - "accs"
          - "huawei"
          - "xiaomi"
          - "meizu"
          - "oppo"
    PushResponse:
      type: object
      required:
      - taskId
      properties:
        taskId:
          type: string
    ErrorResponse:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
        message:
          type: string

SDK生成

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

如果用户需要自己定制SDK的参数（比如包名、兼容的java版本），有两种方法：

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

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

Demo代码

以Java客户端SDK为例，Demo代码如下（使用单元测试方式运行）：

public class PushDemoTest {
    // 推送API客户端
    private final DefaultApi api = new DefaultApi();
    @Test
    public void testPush() {
        // 默认为公共POC推送服务器地址，可修改为私有环境的对应地址
        api.getApiClient().setBasePath("http://localhost/agoo/v1");
        // 构造推送请求
        PushRequest pushRequest = new PushRequest();
        pushRequest.setAppKey("123456");
        pushRequest.setServiceToken("token");
        pushRequest.setTitle("title");
        pushRequest.setSubTitle("subTitle");
        pushRequest.setContent("content");
        pushRequest.setSandbox(true);
        pushRequest.setActionType(PushRequest.ActionTypeEnum.URL);
        pushRequest.setActionTarget("http://www.aliyun.com");
        pushRequest.setSendType(PushRequest.SendTypeEnum.ALIAS);
        pushRequest.setTargetAliases(Arrays.asList("alias1", "alias2"));
        pushRequest.setBadge(1);
        pushRequest.setIconUrl("iconUrl");
        pushRequest.setPictureResource("pictureResource");
        pushRequest.setRemindType(PushRequest.RemindTypeEnum.BOTH);
        pushRequest.setSoundResource("soundResource");
        pushRequest.setSilent(true);
        pushRequest.setNotificationChannel("notificationChannel");
        pushRequest.setChannel(PushRequest.ChannelEnum.ACCS);
        // 设置扩展参数
        Map<String, String> extParams = new HashMap<>();
        extParams.put("k1", "v1");
        extParams.put("k2", "v2");
        pushRequest.setExtParams(extParams);
        // 设置过期时间
        OffsetDateTime expireTime = OffsetDateTime.now().plusDays(1);
        pushRequest.setExpireTime(expireTime);
        try {
            // 发起推送请求
            PushResponse pushResponse = api.pushPost(pushRequest);
            // 推送成功，返回消息ID
            System.out.println("Push OK with taskID: " + pushResponse.getTaskId());
        } catch (ApiException e) {
            // 推送失败，抛出API异常
            if (e.getCode() == 0) {
                // 无HTTP状态码，本地连接错误
                System.err.println("Push failed locally with message: " + e.getMessage());
            } else {
                // 服务端返回错误，包含错误码和错误消息
                System.err.println("Push failed remotely with status '" + e.getCode()
                        + "' and error response: " + e.getResponseBody());
            }
            e.printStackTrace();
        }
    }
}

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

附录

错误码说明

参数限制说明