TAG 與 Alias API 文件

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 的長度限制：每個 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、HarmonyOS 的 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，不允許傳入其他值。

回傳範例

成功的回應會回傳一個 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=android,ios,hmos Authorization: Basic (base64 auth string) Accept: application/json

              
              DELETE /v4/tags/{tag_value}?platform=android,ios,hmos
  Authorization: Basic (base64 auth string) 
  Accept: application/json

此代碼塊在浮窗中顯示

請求參數

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

此代碼塊在浮窗中顯示

回傳資料

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=android,ios,hmos Authorization: Basic (base64 auth string) Accept: application/json

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

              
              DELETE /v4/aliases/{alias_value}?platform=android,ios,hmos
  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://pushapi-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://pushapi-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

標籤別名 API

限制條件與規則 for TAG 使用

限制條件與規則 for alias 使用

API 概述

查詢 AppKey 下的 tag 數量

呼叫位址

請求範例

回傳範例

查詢裝置的別名與標籤

呼叫位址

請求範例

回傳範例

設定裝置的別名與標籤

呼叫位址

請求範例

回傳範例

查詢標籤列表

呼叫位址

請求範例

請求範例

查詢裝置與標籤的綁定關係

呼叫位址

請求範例

回傳範例

更新標籤

呼叫位址

請求範例

回傳範例

刪除標籤

呼叫位址

請求範例

回傳範例

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

查詢別名

呼叫位址

請求範例

回傳範例

刪除別名

請求範例

回傳範例

取得使用者在線狀態

呼叫位址

請求範例

回傳範例

TAG/alias 配額資訊查詢介面

呼叫位址

請求範例

HTTP 狀態碼

業務回傳碼