logo
繁體中文
English
繁體中文
简体中文
日本語
ภาษาไทย
聯絡我們
登錄
icon AppPushicon WebPushicon WhatsAppicon Emailicon SMSicon OTP
EngageLab 檔案 >WebPush >REST API >標簽別名API
EngageLab 檔案 >WebPush >REST API >標簽別名API

標籤別名 API

最新更新：2023-07-19

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

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

調用地址

https://webpush.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
此代碼塊在浮窗中顯示

請求參數

  • 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://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
在文档中心打开
icon
聯繫銷售