logoドキュメント
WebPush
ドキュメントホーム
ユーザーガイド開発者ガイドベストプラクティス
検索
日本語
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
ログイン
開発者ガイド / REST API / タグ・エイリアス API

Tag Alias API

最新更新：2025-07-22

Device APIは、サーバー側でデバイスのタグ（tag）とエイリアス（alias）情報のクエリ、設定、更新、削除に使用されます。使用時には、サーバー側で設定したタグがクライアント側によって上書きされないよう注意が必要です。

  • タグやエイリアスのロジックに慣れていない場合は、クライアントまたはサーバーのいずれか一方のみを使用することを推奨します。
  • 両側で同時に使用する場合は、タグとエイリアスの同期を処理できるようアプリケーションを設計してください。

TAG使用のルールと制限

  • TAG数量制限：単一appkey配下では、最大100,000個のTagを作成できます。
  • TAG長さ制限：各Tagの最大長は40バイトです。有効な文字には、英字（大文字小文字区別）、数字、アンダースコア、漢字が含まれます。
  • デバイスのTAGバインド制限：各デバイスは最大100個のTagをバインドできます。
  • デバイス数量制限：単一Tag配下では、最大100,000台のデバイスを追加できます。

有料プランのサブスクライバーで、有料AppKeyの使用制限を調整したい場合は、営業チームまでお問い合わせください：Sales@engagelab.com

alias使用のルールと制限

  • デバイスとaliasのマッピング：1つのaliasは1台のデバイスにのみ対応でき、複数のデバイスに対応することはできません。同様に、appkey範囲内の各デバイスは1つのaliasにのみマッピングでき、複数のaliasにマッピングすることはできません。
  • alias数量制限：単一appkey配下では、最大100,000個のaliasを作成できます。
  • alias長さ制限：各aliasの最大長は40バイトです。有効な文字には、英字（大文字小文字区別）、数字、アンダースコア、漢字が含まれます。

有料プランのサブスクライバーで、有料AppKeyの使用制限を調整したい場合は、営業チームまでお問い合わせください：Sales@engagelab.com

API概要

Device APIは、サーバー側でデバイスのtagとalias情報のクエリ、設定、更新、削除に使用されます。

以下の3セットのAPIを含みます：device、tag、alias。それぞれの用途は次のとおりです：

  • device：デバイスの各種属性（tag、aliasを含む）のクエリ/設定に使用されます。
  • tag：デバイスのtagのクエリ/設定/削除に使用されます。
  • alias：デバイスのaliasのクエリ/設定/削除に使用されます。

使用に必要なキー情報はregistration IDです：

デバイスのregistration_idは、クライアントを統合した後に取得できます。詳細はWebのAPIドキュメントを参照してください。

サーバーはデバイスのregistrationID値を取得するAPIを提供していません。開発者はクライアントからregistration IDを取得し、開発者サーバーにアップロードして保存する必要があります。

AppKey配下のTag数量のクエリ

宛先URL

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"
このコードブロックはフローティングウィンドウ内に表示されます

リクエストパラメータ

  • Tag：指定されたtag文字列をクエリする必須フィールドで、一度に最大1000個のtagをクエリできます（tags=tag1&tags=tag2&tags=tag3）。
  • platform：指定されたプラットフォームをクエリする必須フィールドで、オプションの値はandroid、iosです。その他の値は許可されません。

レスポンス例

  • 成功レスポンスには、tagsCountフィールドを含むJSONオブジェクトが返されます。これはキーと値のペアのコレクションで、キーは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"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

デバイスのaliasとラベルのクエリ

  • 現在のデバイスのすべての属性（tag、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になり、それ以外の場合は統計情報の値になります。

デバイスのaliasとラベルの設定

  • 現在のデバイスの指定された属性（tag、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パラメータが空文字列の場合は、すべてのtagをクリアすることを意味します。add/removeの下では、指定されたtagを追加または削除します。
  • alias：デバイスのalias属性を更新します。aliasが空文字列の場合は、指定されたデバイスの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"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

デバイスの削除

  • デバイスを削除します。

呼び出しアドレス

DELETE /v4/devices/{registration_id}
              
              DELETE /v4/devices/{registration_id}
このコードブロックはフローティングウィンドウ内に表示されます

リクエスト例

リクエストヘッダー

DELETE /v4/devices/{registration_id} Authorization: Basic (base64 auth string) Accept: application/json
              
              DELETE /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
このコードブロックはフローティングウィンドウ内に表示されます

レスポンスデータ

success
              
              success
このコードブロックはフローティングウィンドウ内に表示されます

失敗レスポンス

{ "error":{ "code":27002, "message":"unknown error" } }
              
              {
  "error":{
    "code":27002, 
    "message":"unknown error"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

タグリストのクエリ

  • 現在のアプリケーションのすべてのtagのリストを取得します。

呼び出しアドレス

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
このコードブロックはフローティングウィンドウ内に表示されます

リクエストパラメータ

  • なし

レスポンス例

成功レスポンス

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のバインド関係のクエリ

  • デバイスが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}
このコードブロックはフローティングウィンドウ内に表示されます

タグの更新

  • tagに対してデバイスの追加または削除を行います。

呼び出しアドレス

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"の2つのオプションがあり、リクエストが「追加」还是「削除」を識別します。
  • 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\"]}"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

タグの削除

tagを削除し、tagとデバイスの関連付けを解除します。

呼び出しアドレス

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"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

alias（デバイスとのバインド関係）のクエリ

GET /v4/aliases/{alias_value}
              
              GET /v4/aliases/{alias_value}
このコードブロックはフローティングウィンドウ内に表示されます
  • 指定された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
このコードブロックはフローティングウィンドウ内に表示されます

リクエストパラメータ

  • 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になり、それ以外の場合は統計情報の値になります。

Aliasの削除

aliasと、aliasとデバイスのバインド関係を削除します。

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_idsをクエリできます。
  • このAPIを呼び出すには、事前にこのサービスを開通したAppkeyを申請する必要があります。

レスポンス例

成功レスポンス

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で、このフィールドが返されない場合は、最終オンライン時間は2日前です。
  • 無効なregidまたはappkeyに属さないregidの場合は、検証に失敗します。

TAG/aliasクォータ情報クエリインターフェース

指定されたAppKey、プラットフォーム、tagの関連クォータ情報をクエリします。単一クエリのtag数は1,000を超えることができません。

呼び出しアドレス

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：アプリケーション配下のtagの総クォータを示します。
  • useTagQuota：使用済みのtagクォータを示します。
  • totalAliasQuota：アプリケーション配下のaliasの総クォータを示します。
  • useAliasQuota：使用済みのaliasクォータを示します。
  • tagUidQuotaDetail：各tagのデバイスクォータの詳細を示します。

失敗レスポンス

{ "error": { "code": 27002, "message": "Illegal parameter" } }
              
              {
    "error": {
        "code": 27002,
        "message": "Illegal parameter"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

業務戻りコード

コード 説明 詳細説明 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の数が制限を超えています。1台のデバイスは最大100個のtagをバインドできます。 401
27012 パラメータエラー デバイスがバインドしようとしているtagが存在しません。 401
27013 パラメータエラー アプリケーション内のtagの数が制限を超えています。1つのアプリケーションは最大100,000個のtagを作成できます。 401
27014 システム制限 tag内のデバイスバインド数が制限を超えています。1つのtagは最大100,000台のデバイスをバインドできます。 401
27015 パラメータエラー デバイスにバインドされているAliasが存在しません。 401
27016 システム制限 アプリケーション内のaliasの数が制限を超えています。1つのアプリケーションは最大100,000個のaliasを作成できます。 401
27017 パラメータエラー tagの長さが40文字を超えています。 401
icon
お問い合わせ