TAG & Alias API Documentation

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

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

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

TAG使用的規則與限制

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

如果您是付費計畫的用戶，並希望調整付費AppKey的使用限額，請聯繫我們的商務團隊：Sales@engagelab.com

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 在客戶端集成後獲取，詳情查看 Android、iOS 的 API 文檔；

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

調用地址

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?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"

此代碼塊在浮窗中顯示

請求參數

標籤：查詢指定的標籤字串，必填字段，單次最多允許查詢1000個標籤(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

此代碼塊在浮窗中顯示

請求參數

返回示例

成功返回

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

此代碼塊在浮窗中顯示

失敗返回

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

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://push.api.engagelab.cc/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='

          curl --location 'https://push.api.engagelab.cc/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

業務返回碼

代碼	描述	詳細解釋	HTTP 狀態碼
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

標簽別名 API

TAG使用的規則與限制

alias使用的規則與限制

API 概述

調用地址

查詢AppKey下的tag數量

調用地址

請求範例

返回範例

查詢設備的別名與標簽

調用地址

請求示例

返回示例

設置設備的別名與標簽

調用地址

請求示例

返回示例

查詢標簽列表

調用地址

請求示例

請求示例

查詢設備與標簽的綁定關系

調用地址

請求示例

返回示例

更新標簽

調用地址

請求示例

返回示例

刪除標簽

調用地址

請求示例

返回示例

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

調用地址

請求示例

返回示例

刪除別名

請求示例

返回示例

獲取用戶在線狀態

調用地址

請求示例

返回示例

TAG/alias配額資訊查詢接口

調用地址

請求示例

HTTP 狀態碼

業務返回碼

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