logo
简体中文
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
联系我们
登录
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTPicon Marketing Automation
EngageLab 文档 >WebPush >REST API >标签别名API
EngageLab 文档 >WebPush >REST API >标签别名API

标签别名 API

最新更新：2023-11-17

Device API 用于在服务器端查询、设置、更新、删除设备的 tag,alias 信息，使用时需要注意不要让服务端设置的标签又被客户端给覆盖了。

  • 如果不是熟悉 tag，alias 的逻辑建议只使用客户端或服务端二者中的一种。
  • 如果是两边同时使用，请确认自己应用可以处理好标签和别名的同步。

需要了解 tag,alias 的详细信息，请参考对应客户端平台的 API 说明。

限制条件与规则 for TAG使用

  • TAG的数量限制：在单个appkey下，你可以最多创建10万个Tag。
  • TAG的长度限制：每个Tag的最大长度是40字节。你可以使用的有效字符包括字母（需要注意大小写）、数字、下划线以及汉字。
  • 设备绑定TAG的数量限制：每个设备最多可以绑定100个Tag。
  • 设备数量限制：在单个Tag下，你可以最多添加10万个设备。

如果您是付费计划的用户，并希望调整付费AppKey的使用限额，请联系我们的商务团队：Sales@engagelab.com

限制条件与规则 for alias使用

  • 设备与alias的映射关系：一个alias只能对应一个设备，不能对应多个设备。同样，每个设备在appkey范围内也只能映射到一个alias，不能映射到多个alias。
  • alias的数量限制：在单个appkey下，你可以创建最多10万个alias。
  • alias的长度限制：每个alias的最大长度是40字节。你可以使用的有效字符包括字母（需要注意大小写）、数字、下划线以及汉字。

如果您是付费计划的用户，并希望调整付费AppKey的使用限额，请联系我们的商务团队：Sales@engagelab.com

API 概述

Device API 用于在服务器端查询、设置、更新、删除设备的 tag,alias 信息。

包含了 device, tag, alias 三组 API。其中：

  • device 用于查询 / 设置设备的各种属性，包含 tags, alias；
  • tag 用于查询 / 设置 / 删除设备的标签；
  • alias 用于查询 / 设置 / 删除设备的别名。

需要用到的关键信息还有 registration ID：

设备的 registration_id 在客户端集成后获取，详情查看 Web 的 API 文档；

服务端未提供 API 去获取设备的 registrationID 值，需要开发者在客户端获取到 registration ID 后上传给开发者服务器保存。

查询AppKey下的tag数量

调用地址

GET /v4/tags_count
          GET /v4/tags_count
此代码块在浮窗中显示

请求示例

请求报头

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

请求示例

curl -X GET http://127.0.0.1/v4/tags_count?tags=tag1&tags=tag2&platform=ios -u "appKey:appSecret"
          curl -X GET http://127.0.0.1/v4/tags_count?tags=tag1&tags=tag2&platform=ios -u "appKey:appSecret"
此代码块在浮窗中显示

请求参数

  • tags: 查询指定的tag字符串，必填字段，单次最多允许查询1000个tag( tags=tag1&tags=tag2&tags=tag3 )
  • platform: 查询指定的平台，必填字段，可选值为android、ios，不允许传入其他值。

返回示例

  • 成功的响应将返回一个JSON对象，其中包含一个tagsCount字段，这是一个键值对的集合，键是tag名称，值是该tag下的数量。
  • 如果请求失败，将返回一个包含错误信息的JSON对象。code字段表示错误码，message字段表示错误信息。

成功返回

{ "tagsCount": { "tag1": 0, "tag2": 1, "tag3": 2 } }
          {
    "tagsCount": {
        "tag1": 0,
        "tag2": 1,
        "tag3": 2
    }
}
此代码块在浮窗中显示

失败返回

{ "error": { "code": 21008, "message": "app_key is not a 24 size string or does not exist" } }
          {
    "error": {
        "code": 21008,
        "message": "app_key is not a 24 size string or does not exist"
    }
}
此代码块在浮窗中显示

查询设备的别名与标签

  • 获取当前设备的所有属性，包含 tags, alias。

调用地址

GET /v4/devices/{registration_id}
          GET /v4/devices/{registration_id}
此代码块在浮窗中显示

请求示例

请求报头

GET /v4/devices/{registration_id} Authorization: Basic (base64 auth string) Accept: application/json
          GET /v4/devices/{registration_id}
  Authorization: Basic (base64 auth string) 
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • N/A

返回示例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示

返回数据

{"tags": ["tag1", "tag2"], "alias": "alias1" }
          {"tags": ["tag1", "tag2"],
 "alias": "alias1"
}
此代码块在浮窗中显示
  • 找不到统计项就是 null, 否则为统计项的值

设置设备的别名与标签

  • 更新当前设备的指定属性，当前支持 tags, alias。

调用地址

POST /v4/devices/{registration_id}
          POST /v4/devices/{registration_id}
此代码块在浮窗中显示

请求示例

请求报头

POST /v4/devices/{registration_id} Authorization: Basic (base64 auth string) Accept: application/json
          POST /v4/devices/{registration_id}
  Authorization: Basic (base64 auth string) 
  Accept: application/json
此代码块在浮窗中显示

请求数据

{ "tags": { "add": [ "tag1", "tag2" ], "remove": [ "tag3", "tag4" ] }, "alias": "alias1" }
          {
    "tags": {
        "add": [
            "tag1",
            "tag2"
        ],
        "remove": [
            "tag3",
            "tag4"
        ]
    },
    "alias": "alias1"
}
此代码块在浮窗中显示

请求参数

  • tags:  支持 add, remove 或者空字符串。当 tags 参数为空字符串的时候，表示清空所有的 tags；add/remove 下是增加或删除指定的 tag；
  • alias:  更新设备的别名属性；当别名为空串时，删除指定设备的别名。

返回示例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示

返回数据

success
          success
此代码块在浮窗中显示

失败返回

{ "error":{ "code":27002, "message":"unknown error" } }
          {
  "error":{
    "code":27002, 
    "message":"unknown error"
    }
}
此代码块在浮窗中显示

查询标签列表

  • 获取当前应用的所有标签列表。

调用地址

GET /v4/tags/
          GET /v4/tags/
此代码块在浮窗中显示

请求示例

请求报头

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

请求参数

  • None

请求示例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示

返回数据

{ "tags": [ "tag1", "tag2" ] }
          {
  "tags": [
    "tag1",
    "tag2"
  ]
}
此代码块在浮窗中显示
  • 找不到统计项就是 null，否则为统计项的值。

查询设备与标签的绑定关系

  • 查询某个设备是否在 tag 下。

调用地址

GET /v4/tags/{tag_value}/registration_ids/{registration_id}
          GET /v4/tags/{tag_value}/registration_ids/{registration_id}
此代码块在浮窗中显示

请求示例

请求报头

GET /v4/tags/{tag_value}/registration_ids/090c1f59f89 Authorization: Basic (base64 auth string) Accept: application/json
          GET /v4/tags/{tag_value}/registration_ids/090c1f59f89
  Authorization: Basic (base64 auth string) 
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • registration_id  必须，设备的 registration_id

返回示例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示

返回数据

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

更新标签

  • 为一个标签添加或者删除设备。

调用地址

POST /v4/tags/{tag_value}
          POST /v4/tags/{tag_value}
此代码块在浮窗中显示

请求示例

请求报头

POST /v4/tags/{tag_value} Authorization: Basic (base64 auth string) Accept: application/json
          POST /v4/tags/{tag_value}
  Authorization: Basic (base64 auth string) 
  Accept: application/json
此代码块在浮窗中显示

请求数据

{ "registration_ids":{ "add": [ "registration_id1", "registration_id2" ], "remove": [ "registration_id1", "registration_id2" ] } }
          {  
  "registration_ids":{
    "add": [
      "registration_id1",
      "registration_id2"
    ],
    "remove": [
      "registration_id1",
      "registration_id2"
    ]
  }
}
此代码块在浮窗中显示

请求参数

  • action 操作类型，有两个可选："add"，"remove"，标识本次请求是 "添加" 还是 "删除";
  • registration_ids  需要添加 / 删除的设备 registration_id;
  • add/remove 最多各支持 1000 个.

返回示例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
          HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示

返回数据

success
          success
此代码块在浮窗中显示

失败返回

{ "error": { "code": 27005, "message": "registration id is illegal", "data": "{\"invalid_regids\":[\"18071adc021ff8df80\",\"100d85592955c1f1058\"]}" } }
          {
    "error": {
        "code": 27005,
        "message": "registration id is illegal",
        "data": "{\"invalid_regids\":[\"18071adc021ff8df80\",\"100d85592955c1f1058\"]}"
    }
}
此代码块在浮窗中显示

删除标签

删除一个标签，以及标签与设备之间的关联关系。

调用地址

DELETE /v4/tags/{tag_value}
          DELETE /v4/tags/{tag_value}
此代码块在浮窗中显示

请求示例

请求报头

DELETE /v4/tags/{tag_value}?platform=web Authorization: Basic (base64 auth string) Accept: application/json
          DELETE /v4/tags/{tag_value}?platform=web
  Authorization: Basic (base64 auth string) 
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • platform 可选参数，不填则默认为所有平台。

返回示例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-
          HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-
此代码块在浮窗中显示

返回数据 success

失败返回

{ "error":{ "code":27002, "message":"unknown error" } }
          {
  "error":{
    "code":27002, 
    "message":"unknown error"
    }
}
此代码块在浮窗中显示

查询别名 （与设备的绑定关系）

GET /v4/aliases/{alias_value} 获取指定 alias 下的设备，最多输出 10 个；
          GET /v4/aliases/{alias_value}
获取指定 alias 下的设备，最多输出 10 个；
此代码块在浮窗中显示

查询别名

  • 获取指定 alias 下的设备，最多输出 10 个，超过 10 个默认输出 10 个。

调用地址

GET /v4/aliases/{alias_value}
          GET /v4/aliases/{alias_value}
此代码块在浮窗中显示

请求示例

请求报头

GET /v4/aliases/{alias_value}?platform=web Authorization: Basic (base64 auth string) Accept: application/json
          GET /v4/aliases/{alias_value}?platform=web
  Authorization: Basic (base64 auth string) 
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • platform 可选参数，不填则默认为所有平台。

返回示例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示

返回数据

{ "registration_ids": [ "registration_id1", "registration_id2" ] }
          {
  "registration_ids": [
    "registration_id1",
    "registration_id2"
  ]
}
此代码块在浮窗中显示
  • 找不到统计项就是 null，否则为统计项的值。

删除别名

删除一个别名，以及该别名与设备的绑定关系。

DELETE /v4/aliases/{alias_value}
          DELETE /v4/aliases/{alias_value}
此代码块在浮窗中显示

请求示例

请求报头

DELETE /v4/aliases/{alias_value}?platform=web Authorization: Basic (base64 auth string) Accept: application/json
          DELETE /v4/aliases/{alias_value}?platform=web
  Authorization: Basic (base64 auth string) 
  Accept: application/json
此代码块在浮窗中显示

请求参数

  • platform 可选参数，不填则默认为所有平台。

返回示例

  • 成功
success
            success
此代码块在浮窗中显示
  • 失败
{ "error":{ "code":27002, "message":"unknown error" } }
          {
  "error":{
    "code":27002, 
    "message":"unknown error"
    }
}
此代码块在浮窗中显示

获取用户在线状态

调用地址

POST /v4/devices/status/
          POST /v4/devices/status/
此代码块在浮窗中显示

请求示例

请求报头

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

请求数据

{ "registration_ids": [ "010b81b3582", "0207870f1b8", "0207870f9b8" ] }
          {
  "registration_ids": [
    "010b81b3582",
    "0207870f1b8",
    "0207870f9b8"
  ]
}
此代码块在浮窗中显示

请求参数

  • registration_ids  需要在线状态的用户 registration_id， 最多支持查询 1000 个 registration_id。
  • 需要申请开通了这个业务的 Appkey 才可以调用此 API。

返回示例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示

返回数据

[ { "regid": "010b81b3582", "online": true }, { "regid": "0207870f1b8", "online": false, "last_online_time": "2014-12-16 10:57:07" }, { "regid": "0207870f9b8", "online": false } ]
          [
  {
    "regid": "010b81b3582",
    "online": true
  },
  {
    "regid": "0207870f1b8",
    "online": false,
    "last_online_time": "2014-12-16 10:57:07"
  },
  {
    "regid": "0207870f9b8",
    "online": false
  }
]
此代码块在浮窗中显示

返回数据

  • online
    • true: 10 分钟之内在线；
    • false: 10 分钟之内不在线；
  • last_online_time
    • 当 online 为 true 时，该字段不返回;
    • 当 online 为 false，且该字段不返回时，则表示最后一次在线时间是两天之前；
  • 对于无效的 regid 或者不属于该 appkey 的 regid，会校验失败。

TAG/alias配额信息查询接口

查询指定AppKey、平台、tag的相关配额信息。单次查询tag个数不能超过1000。

调用地址

GET /v4/tags/quota-info?tags=tag1&platform=android Authorization: Basic (base64 auth string) Accept: application/json
          GET  /v4/tags/quota-info?tags=tag1&platform=android
Authorization: Basic (base64 auth string) 
Accept: application/json
此代码块在浮窗中显示

请求示例

curl --location 'https://webpushapi-sgp.engagelab.com/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='
          curl --location 'https://webpushapi-sgp.engagelab.com/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='
此代码块在浮窗中显示

成功返回

{ "data": { "totalTagQuota": 100000, "useTagQuota": 1, "totalAliasQuota": 100000, "useAliasQuota": 3, "tagUidQuotaDetail": [ { "tagName": "tag1", "totalUidQuota": 100000, "useUidQuota": 0 }, { "tagName": "tag2", "totalUidQuota": 100000, "useUidQuota": 0 } ] } } 
          {
    "data": {
        "totalTagQuota": 100000,
        "useTagQuota": 1,
        "totalAliasQuota": 100000,
        "useAliasQuota": 3,
        "tagUidQuotaDetail": [
            {
                "tagName": "tag1",
                "totalUidQuota": 100000,
                "useUidQuota": 0
            },
            {
                "tagName": "tag2",
                "totalUidQuota": 100000,
                "useUidQuota": 0
            }
        ]
    }
}
此代码块在浮窗中显示

返回字段释义：

  • totalTagQuota：表示应用下标签个数总配额。
  • useTagQuota：表示已使用的标签配额。
  • totalAliasQuota：表示应用下别名个数总配额。
  • useAliasQuota：表示已使用的别名配额。
  • tagUidQuota：表示单个标签设备数配额。
  • useUidQuota: 表示每个标签绑定的设备数目明细。

失败返回

{ "error": { "code": 27002, "message": "参数非法" } }
          {
    "error": {
        "code": 27002,
        "message": "参数非法"
    }
}
此代码块在浮窗中显示

HTTP 状态码

参考文档：Http-Status-Code

业务返回码

Code 描述 详细解释 HTTP Status Code
21004 鉴权错误 appkey非法 401
27000 系统内存错误 请重试 500
27001 参数错误 校验信息为空 401
27002 参数错误 参数非法 400
27004 参数错误 校验失败 401
27005 参数错误 regisID 格式非法 400
21008 参数错误 app_key不是24位字符串或者不存在 400
27010 参数错误 alias已经绑定另外一个regid 400
27011 系统限制 设备下绑定的tag数量超限，单个设备最多绑定100个Tag 401
27012 参数错误 设备要绑定的Tag不存在 401
27013 参数错误 应用下的tag数量超限，单个应用最多创建10万个Tag 401
27014 系统限制 tag下的uid数量超限，单个Tag最多绑定10万设备 401
27015 参数错误 设备绑定的Alias不存在 401
27016 系统限制 应用下alias数量超限，单个应用最多创建10万个Alias 401
27017 参数错误 tag长度超过40个字符 401
在文档中心打开
icon
联系销售