繁體中文
English
繁體中文
简体中文
にほんご
ภาษาไทย
登入 註冊
icon AppPush icon WebPush icon WhatsApp icon Email icon SMS
EngageLab 檔案 > AppPush > REST API > 標簽別名API
EngageLab 檔案 > AppPush > REST API > 標簽別名API
標簽別名 API
最新更新：2023-11-17

標簽別名 API

Device API 用於在服務器端查詢、設置、更新、刪除設備的 tag,alias 信息，使用時需要註意不要讓服務端設置的標簽又被客戶端給覆蓋了。

  • 如果不是熟悉 tag，alias 的邏輯建議只使用客戶端或服務端二者中的一種。
  • 如果是兩邊同時使用，請確認自己應用可以處理好標簽和別名的同步。

需要了解 tag,alias 的詳細信息，請參考對應客戶端平臺的 API 說明。

TAG使用的規則與限制

  • TAG數量限制：在單一appkey下，你最多可以創建10萬個Tag。
  • TAG長度限制：每個Tag的最大長度是40字節。有效字符包括字母（區分大小寫）、數字、下劃線以及漢字。
  • 設備綁定TAG的數量限制：每個設備最多可以綁定100個Tag。
  • 設備數量限制：在單一Tag下，你可以最多添加10萬個設備。

如果您需要提高這些限制的上限，請聯繫我們：Sales@engagelab.com

alias使用的規則與限制

  • 設備與alias的映射關係：一個alias只能對應一個設備，不能對應多個設備。同樣，每個設備在appkey範圍內也只能映射到一個alias，不能映射到多個alias。
  • alias數量限制：在單一appkey下，你可以創建最多10萬個alias。
  • alias長度限制：每個alias的最大長度是40字節。有效字符包括字母（區分大小寫）、數字、下劃線以及漢字。

如果您需要提高這些限制的上限，請聯繫我們：Sales@engagelab.com

API 概述

Device API 用於在服務器端查詢、設置、更新、刪除設備的 tag,alias 信息。

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

  • device 用於查詢 / 設置設備的各種屬性，包含 tags, alias；
  • tag 用於查詢 / 設置 / 刪除設備的標簽；
  • alias 用於查詢 / 設置 / 刪除設備的別名。

需要用到的關鍵信息還有 registration ID：

設備的 registration_id 在客戶端集成後獲取，詳情查看 Android、iOS 的 API 文檔；

服務端未提供 API 去獲取設備的 registrationID 值，需要開發者在客戶端獲取到 registration ID 後上傳給開發者服務器保存。

調用地址

API URL: https://push.api.engagelab.cc/v4/devices

查詢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/ -u "appKey:appSecret"
          curl -X GET http://127.0.0.1/v4/tags_count/ -u "appKey:appSecret"
此代碼塊在浮窗中顯示

請求參數

  • N/A

返回範例

  • 成功的響應將返回一個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，手機號碼 mobile。

調用地址

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", "mobile": "13012345678" }
          {"tags": ["tag1", "tag2"],
 "alias": "alias1",
 "mobile": "13012345678"
}
此代碼塊在浮窗中顯示
  • 找不到統計項就是 null, 否則為統計項的值

設置設備的別名與標簽

  • 更新當前設備的指定屬性，當前支持 tags, alias，手機號碼 mobile。

調用地址

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", "mobile": "13012345678" }
          {
    "tags": {
        "add": [
            "tag1",
            "tag2"
        ],
        "remove": [
            "tag3",
            "tag4"
        ]
    },
    "alias": "alias1",
    "mobile": "13012345678"
}
此代碼塊在浮窗中顯示

請求參數

  • tags:  支持 add, remove 或者空字符串。當 tags 參數為空字符串的時候，表示清空所有的 tags；add/remove 下是增加或刪除指定的 tag；
  • alias:  更新設備的別名屬性；當別名為空串時，刪除指定設備的別名；
  • mobile：設備關聯的手機號碼；當 mobile 為空串時，表示清空設備關聯的手機號碼。

返回示例

成功返回

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
此代碼塊在浮窗中顯示

失敗返回

{"code":2xxxx, "message":"unknow err"}
          {"code":2xxxx, "message":"unknow err"}
此代碼塊在浮窗中顯示

查詢標簽列表

  • 獲取當前應用的所有標簽列表。

調用地址

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
此代碼塊在浮窗中顯示

失敗返回

{"code":2xxxx, "message":"unknow err"}
          {"code":2xxxx, "message":"unknow err"}
此代碼塊在浮窗中顯示

刪除標簽

刪除一個標簽，以及標簽與設備之間的關聯關系。

調用地址

DELETE /v4/tags/{tag_value}
          DELETE /v4/tags/{tag_value}
此代碼塊在浮窗中顯示

請求示例

請求報頭

DELETE /v4/tags/{tag_value}?platform=android,ios Authorization: Basic (base64 auth string) Accept: application/json
          DELETE /v4/tags/{tag_value}?platform=android,ios
  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

失敗返回

{"code":2xxxx, "message":"unknow err"}
            {"code":2xxxx, "message":"unknow err"}
此代碼塊在浮窗中顯示

查詢別名 （與設備的綁定關系）

GET /v4/aliases/{alias_value} 獲取指定 alias 下的設備；
          GET /v4/aliases/{alias_value}
獲取指定 alias 下的設備；
此代碼塊在浮窗中顯示

調用地址

GET /v4/aliases/{alias_value}
          GET /v4/aliases/{alias_value}
此代碼塊在浮窗中顯示

請求示例

請求報頭

GET /v4/aliases/{alias_value}?platform=android,ios Authorization: Basic (base64 auth string) Accept: application/json
          GET /v4/aliases/{alias_value}?platform=android,ios
  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_ids": [
    "registration_id1"
  ]
}
此代碼塊在浮窗中顯示
  • 找不到統計項就是 null，否則為統計項的值。

刪除別名

刪除一個別名，以及該別名與設備的綁定關系。

DELETE /v4/aliases/{alias_value}
          DELETE /v4/aliases/{alias_value}
此代碼塊在浮窗中顯示

請求示例

請求報頭

DELETE /v4/aliases/{alias_value}?platform=android,ios Authorization: Basic (base64 auth string) Accept: application/json
          DELETE /v4/aliases/{alias_value}?platform=android,ios
  Authorization: Basic (base64 auth string) 
  Accept: application/json
此代碼塊在浮窗中顯示

請求參數

  • platform 可選參數，不填則默認為所有平臺。

返回示例

  • 成功
success
            success
此代碼塊在浮窗中顯示
  • 失敗
{"code":2xxxx, "message":"unknow err"}
            {"code":2xxxx, "message":"unknow err"}
此代碼塊在浮窗中顯示

獲取用戶在線狀態

調用地址

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，會校驗失敗。

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
在文档中心打开