文档中心 SDK下载 Demo下载 合规指南 开发者社区
极光文档 > 极光推送 > REST API > 用户属性 API
极光文档 > 极光推送 > REST API > 用户属性 API
用户属性 API
最近更新：2022-08-16
展开全部

用户属性 API

概述

API 层面支持用户属性功能，此模块 API 主要功能是对应用和设备的用户属性进行查询、新增、更新、删除等操作，具体请求方式参考下文。

调用限制

API 请求频率限制与 推送 API 接口共享。

调用地址

https://api.jpush.cn/v3/property

调用验证

详情参见 REST API 概述的 鉴权方式 说明。

新增用户属性

在应用下新增用户属性。

调用地址

POST https://api.jpush.cn/v3/property

请求示例

请求报头

POST /v3/property Authorization: Basic (base64 auth string) Accept: application/json
          POST /v3/property
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求数据

{ "property_name": "property_name", "property_desc": "property_desc", "property_type": "string" }
          {
    "property_name": "property_name",
    "property_desc": "property_desc",
    "property_type": "string"
}
此代码块在浮窗中显示

请求参数

  • property_name 用户属性名称
    • 长度限制 50 字节
  • property_desc 用户属性描述
    • 长度限制 50 字节
  • property_type 用户属性字段类型
    • 传值范围 (string、number、bool、datetime)

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回参数

  • N/A

查询用户属性

查询用户属性列表，包括绑定设备数。

调用地址

GET https://api.jpush.cn/v3/property?page=1&page_size=10&keyword=&start_time=&end_time=

请求示例

请求报头

GET /v3/property?page=1&page_size=10&keyword=property_name&start_time=2022-08-03 09:00:00&end_time=2022-08-03 22:00:00 Authorization: Basic (base64 auth string) Accept: application/json
          GET /v3/property?page=1&page_size=10&keyword=property_name&start_time=2022-08-03 09:00:00&end_time=2022-08-03 22:00:00
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • page 页数，默认第 1 页
  • page_size 页码，默认 10 条
  • keyword 搜索框，用户属性名称或者描述搜索
  • start_time 搜索框，开始时间
    • 格式 yyyy-MM-dd HH:mm:ss
  • end_time 搜索框，结束时间
    • 格式 yyyy-MM-dd HH:mm:ss

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回数据

{ "total": 1, "data": [ { "property_name": "property_name", "property_desc": "property_desc", "property_type": "string", "device_num": 0, "last_update_time": "2022-08-03 14:55:35" } ] }
          {
    "total": 1,
    "data": [
        {
            "property_name": "property_name",
            "property_desc": "property_desc",
            "property_type": "string",
            "device_num": 0,
            "last_update_time": "2022-08-03 14:55:35"
        }
    ]
}
此代码块在浮窗中显示

返回参数

  • total 属性名称总数
  • data 属性名称数组数据
    • property_name 用户属性名称
    • property_desc 用户属性描述
    • property_type 用户属性字段类型
    • device_num 绑定设备数
    • last_update_time 最后更新时间
      • 格式 yyyy-MM-dd HH:mm:ss

更新用户属性

更新应用的用户属性。

调用地址

PUT https://api.jpush.cn/v3/property/{property_name}

请求示例

请求报头

PUT /v3/property/property_name Authorization: Basic (base64 auth string) Accept: application/json
          PUT /v3/property/property_name
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求数据

{ "property_desc": "update_sec" }
          {
    "property_desc": "update_sec"
}
此代码块在浮窗中显示

请求参数

  • property_name 具体的用户属性名称
  • property_desc 用户属性描述
    • 长度限制 50 字节

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回参数

  • N/A

删除用户属性

删除用户属性，同时解除和所有设备的绑定关系。

调用地址

DELETE https://api.jpush.cn/v3/property/{property_name}

请求示例

请求报头

DELETE /v3/property/property_name Authorization: Basic (base64 auth string) Accept: application/json
          DELETE /v3/property/property_name
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • property_name 具体的用户属性名称

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回参数

  • N/A

查询用户属性的设备详情

查询指定用户属性的绑定设备数和设备 regid 明细。

调用地址

GET https://api.jpush.cn/v3/property/{property_name}?page=1&page_size=1000

请求示例

请求报头

GET /v3/property/property_name?page=1&page_size=1000 Authorization: Basic (base64 auth string) Accept: application/json
          GET /v3/property/property_name?page=1&page_size=1000
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • property_name 具体的用户属性名称
  • page 页数，默认第 1 页
  • page_size 页码，默认 1000 条

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回数据

{ "device_num": 2, "registration_ids": [ "1a0018970aa97f72bb6", "121c83f7602bda9ba31" ] }
          {
    "device_num": 2,
    "registration_ids": [
        "1a0018970aa97f72bb6",
        "121c83f7602bda9ba31"
    ]
}
此代码块在浮窗中显示

返回参数

  • device_num 绑定设备数
  • registration_ids 设备 registration_id 数组

查询用户属性已创建总数量

查询用户属性已创建总数量。

调用地址

GET https://api.jpush.cn/v3/property/total_num

请求示例

请求报头

GET /v3/property/total_num Authorization: Basic (base64 auth string) Accept: application/json
          GET /v3/property/total_num
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • N/A

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回数据

{ "total": 94 }
          {
    "total": 94
}
此代码块在浮窗中显示

返回参数

  • total 用户属性已创建数量

查询设备的用户属性

查询 registration_id 的用户属性。

调用地址

GET https://api.jpush.cn/v3/property/bind/{registration_id}

请求示例

请求报头

GET /v3/property/bind/121c83f7602bda9ba31 Authorization: Basic (base64 auth string) Accept: application/json
          GET /v3/property/bind/121c83f7602bda9ba31
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • registration_id 设备的 registration_id。

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回数据

[ { "property_name": "autotest_key", "property_value": "myvalue1", "bind_time": "2022-07-21 15:17:12" }, { "property_name": "property_name", "property_value": "property_name", "bind_time": "2022-08-03 16:50:18" } ]
          [
    {
        "property_name": "autotest_key",
        "property_value": "myvalue1",
        "bind_time": "2022-07-21 15:17:12"
    },
    {
        "property_name": "property_name",
        "property_value": "property_name",
        "bind_time": "2022-08-03 16:50:18"
    }
]
此代码块在浮窗中显示

返回参数

  • 返回数组
  • property_name 用户属性名称
  • property_value 用户属性值
  • bind_time 绑定时间
    • 格式 yyyy-MM-dd HH:mm:ss

新增/更新设备的用户属性

给指定的 registration_ids 绑定用户属性。

  • 如果传递的用户属性与该设备未存在绑定关系，则是给该设备绑定用户属性。
  • 如果传递的用户属性与该设备已经存在绑定关系，则是更新该设备的用户属性值。

调用地址

POST https://api.jpush.cn/v3/property/bind/registration_ids

请求示例

POST /v3/property/bind/registration_ids Authorization: Basic (base64 auth string) Accept: application/json
          POST /v3/property/bind/registration_ids
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求数据

{ "registration_id1": { "property_name1": "property_value1", "property_name2": "property_value2" }, "registration_id2": { "property_name1": "property_value1" } }
          {
    "registration_id1": {
        "property_name1": "property_value1",
        "property_name2": "property_value2"
    },
    "registration_id2": {
        "property_name1": "property_value1"
    }
}
此代码块在浮窗中显示

请求参数

  • registration_id* 具体 registration_id
    • 数量限制，一次 1000 个 registration_id
  • property_name* 具体的用户属性名称
  • property_value* 具体绑定到用户属性名称下的用户属性值，推送的时候会用 value 进行替换

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回数据

{ "success": [ "registration_id1", "registration_id2" ], "error": { "registration_id3": { "code": 1101, "msg": "property name exist" } } }
          
{
    "success": [
        "registration_id1",
        "registration_id2"
    ],
    "error": {
        "registration_id3": {
            "code": 1101,
            "msg": "property name exist"
        }
    }
}
此代码块在浮窗中显示

返回参数

JSON Array

  • success：成功的 registration_id 数组。
  • error 部分失败信息。
    • registration_id 下的错误信息

删除设备的用户属性

解除指定 registration_id 和用户属性的绑定关系。

调用地址

DELETE https://api.jpush.cn/v3/property/{property_name}/bind/{registration_id}

请求示例

请求报头

DELETE /v3/property/property_name/bind/121c83f7602bda9ba31 Authorization: Basic (base64 auth string) Accept: application/json
          DELETE /v3/property/property_name/bind/121c83f7602bda9ba31
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • registration_id 设备的 registration_id
  • property_name 具体的用户属性名称

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回参数

  • N/A

查询设备和用户属性的绑定关系

查询某个设备是否有绑定该用户属性。

调用地址

GET https://api.jpush.cn/v3/property/{property_name}/bind/{registration_id}

请求示例

请求报头

GET /v3/property/property_name/bind/121c83f7602bda9ba31 Authorization: Basic (base64 auth string) Accept: application/json
          GET /v3/property/property_name/bind/121c83f7602bda9ba31
  Authorization: Basic (base64 auth string)
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • registration_id 设备的 registration_id
  • property_name 具体的用户属性名称

返回示例

成功返回

HTTP/1.1 200
          HTTP/1.1 200
此代码块在浮窗中显示

返回数据

{ "result": true }
          {
    "result": true
}
此代码块在浮窗中显示

返回参数

  • result
    • true: 绑定关系
    • false: 非绑定关系

调用返回

Code 描述 详细解释 HTTP Status Code
9001 权限错误 鉴权失败，必须改正。检查 Appkey 与 MasterSecret，详情请看： 调用验证 。 401
9002 权限错误 无权调用此接口，请联系商务开通权限。 401
9003 业务错误 请求参数不合法，可能情况：
  • property_name 或 property_value 超过 50 字符长度。
  • page、page_size 非整数。
  • registration_id 传参不合法。
  • registration_id 不属于 appkey。
  • 指定 property_name 不属于 appkey。
  • property_value 和 property_type 不匹配。
  • property_type 类型仅支持 bool、number、string、datetime。
  • registration_id 最多允许 1000 个。
    		• 400
    9004 服务器错误 系统服务异常，请稍后重试。 500
    文档内容是否对您有帮助？

    Copyright 2011-2022, jiguang.cn, All Rights Reserved. 粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

    在文档中心打开