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

タグエイリアスAPI

最新更新：2025-07-22

デバイスAPIは、サーバー側でデバイスのタグ、エイリアス情報の照会、設定、更新、削除に使用されます。使用する際は、サーバー側に設定されたタグがクライアントによって上書きされないよう注意する必要があります。

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

タグ、エイリアスの詳細については、対応するクライアントプラットフォームのAPI説明を参照してください。

TAG使用のルールと制限

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

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

エイリアス使用のルールと制限

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

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

API概要

デバイスAPIは、サーバー側でデバイスのタグ、エイリアス情報の照会、設定、更新、削除に使用されます。

デバイスAPIには3つのAPIが含まれています：device、tag、alias：

  • deviceは、デバイスのさまざまな属性（タグ、エイリアスを含む）の照会/設定に使用されます。
  • tagは、デバイスのタグの照会/設定/削除に使用されます。
  • aliasは、デバイスのエイリアスの照会/設定/削除に使用されます。

登録ID（registration ID）も使用する必要がある重要な情報です：

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

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

呼び出しアドレス

https://pushapi-sgp.engagelab.com/v4/devices

AppKeyの下のタグ数の照会

宛先URL

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

リクエスト例

リクエストヘッダー

GET /v4/tags_count Authorization: Basic (base64認証文字列) Accept: application/json
              
              GET /v4/tags_count
Authorization: Basic (base64認証文字列)
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：指定されたタグ文字列を照会する必要があります。必須フィールドで、一度に最大1000個のタグを照会できます（tags=tag1&tags=tag2&tags=tag3）。
  • platform：指定されたプラットフォームを照会する必要があります。必須フィールドで、オプションの値はandroid、iosです。その他の値は許可されていません。

レスポンス例

  • 成功したレスポンスには、tagsCountフィールドを含むJSONオブジェクトが返されます。これはキー値ペアのコレクションで、キーはタグ名、値はそのタグのカウントです。
  • リクエストが失敗した場合は、エラー情報を含む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"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

デバイスのエイリアスとラベルの照会

  • 現在のデバイスのすべての属性（タグ、エイリアスを含む）を取得します。

呼び出しアドレス

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

リクエスト例

リクエストヘッダー

GET /v4/devices/{registration_id} Authorization: Basic (base64認証文字列) Accept: application/json
              
              GET /v4/devices/{registration_id}
  Authorization: Basic (base64認証文字列) 
  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になり、それ以外の場合は統計情報の値になります。

デバイスのエイリアスとラベルの設定

  • 現在のデバイスの指定された属性を更新します。現在、タグ、エイリアスをサポートしています。

呼び出しアドレス

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

リクエスト例

リクエストヘッダー

POST /v4/devices/{registration_id} Authorization: Basic (base64認証文字列) Accept: application/json
              
              POST /v4/devices/{registration_id}
  Authorization: Basic (base64認証文字列) 
  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パラメータが空の文字列の場合は、すべてのタグをクリアすることを意味します。add/removeの下では、指定されたタグが追加または削除されます。
  • 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認証文字列) Accept: application/json
              
              DELETE /v4/devices/{registration_id}
   Authorization: Basic (base64認証文字列)
   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"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

タグリストの照会

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

呼び出しアドレス

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

リクエスト例

リクエストヘッダー

GET /v4/tags/ Authorization: Basic (base64認証文字列) Accept: application/json
              
              GET /v4/tags/
  Authorization: Basic (base64認証文字列) 
  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になり、それ以外の場合は統計情報の値になります。

デバイスとタグのバインディング関係の照会

  • デバイスがタグの下にあるかどうかを照会します。

呼び出しアドレス

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認証文字列) Accept: application/json
              
              GET /v4/tags/{tag_value}/registration_ids/090c1f59f89
  Authorization: Basic (base64認証文字列) 
  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認証文字列) Accept: application/json
              
              POST /v4/tags/{tag_value}
  Authorization: Basic (base64認証文字列) 
  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\"]}"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

タグの削除

タグ、およびタグとデバイスの関連付けを削除します。

呼び出しアドレス

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

リクエスト例

リクエストヘッダー

DELETE /v4/tags/{tag_value}?platform=android,ios Authorization: Basic (base64認証文字列) Accept: application/json
              
              DELETE /v4/tags/{tag_value}?platform=android,ios
  Authorization: Basic (base64認証文字列) 
  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}
              
              GET /v4/aliases/{alias_value}
このコードブロックはフローティングウィンドウ内に表示されます
  • 指定されたエイリアスの下のデバイスを取得します。

呼び出しアドレス

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

リクエスト例

リクエストヘッダー

GET /v4/aliases/{alias_value}?platform=android,ios Authorization: Basic (base64認証文字列) Accept: application/json
              
              GET /v4/aliases/{alias_value}?platform=android,ios
  Authorization: Basic (base64認証文字列) 
  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=android,ios Authorization: Basic (base64認証文字列) Accept: application/json
              
              DELETE /v4/aliases/{alias_value}?platform=android,ios
  Authorization: Basic (base64認証文字列) 
  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認証文字列) Accept: application/json
              
              POST /v4/devices/status/
  Authorization: Basic (base64認証文字列) 
  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/エイリアスクォータ情報照会インターフェース

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

呼び出しアドレス

GET /v4/tags/quota-info?tags=tag1&platform=android Authorization: Basic (base64認証文字列) Accept: application/json
              
              GET /v4/tags/quota-info?tags=tag1&platform=android
Authorization: Basic (base64認証文字列)
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": "Illegal parameter" } }
              
              {
    "error": {
        "code": 27002,
        "message": "Illegal parameter"
    }
}
このコードブロックはフローティングウィンドウ内に表示されます

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