標籤別名 API

Device API 用於在伺服器端查詢、設定、更新、刪除裝置的 tag、alias 資訊，使用時需要注意，不要讓伺服器端設定的標籤又被用戶端覆蓋。

如果您不熟悉 tag、alias 的邏輯，建議只使用用戶端或伺服器端其中一種方式。
如果兩邊同時使用，請確認您的應用可以妥善處理標籤與別名的同步。

若要了解 tag、alias 的詳細資訊，請參考對應用戶端平台的 API 說明。

web - tag,alias

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 後，上傳至開發者伺服器保存。

查詢 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、hmos 和 web，不允許傳入其他值。

返回範例

成功的回應會返回一個 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

此代碼塊在浮窗中顯示

請求參數

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

此代碼塊在浮窗中顯示

返回資料

{"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"
}

此代碼塊在浮窗中顯示

請求參數

registration_id：必填，裝置的 registration_id
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

此代碼塊在浮窗中顯示

請求參數

tag_value：必填，需要查詢的 tag
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"
    ]
  }
}

此代碼塊在浮窗中顯示

請求參數

tag_value：必填，需要查詢的 tag
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

此代碼塊在浮窗中顯示

請求參數

tag_value：必填，需要查詢的 tag
platform：選填參數，不填則預設為所有平台。

返回範例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-

              
              HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-

此代碼塊在浮窗中顯示

返回資料

success

              
              success

此代碼塊在浮窗中顯示

失敗返回

{ "error":{ "code":27002, "message":"unknown error" } }

              
              {
  "error":{
    "code":27002, 
    "message":"unknown error"
    }
}

此代碼塊在浮窗中顯示

查詢別名（與裝置的綁定關係）

GET /v4/aliases/{alias_value} 取得指定 alias 下的裝置；

              
              GET /v4/aliases/{alias_value}
取得指定 alias 下的裝置；

此代碼塊在浮窗中顯示

查詢別名

取得指定 alias 下的裝置。

呼叫位址

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

此代碼塊在浮窗中顯示

請求參數

alias_value：必填，需要查詢的 alias
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

此代碼塊在浮窗中顯示

請求參數

alias_value：必填，需要刪除的 alias
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