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

TAG & Alias API

最新更新：2年以上前

TAG & Alias API は、サーバー側でデバイスのタグおよびエイリアス情報を照会、設定、更新、削除するために使用されます。利用時には、サーバー側で設定したタグがクライアント側によって上書きされないようご注意ください。

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

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

TAG使用時の制限とルール

  • TAG数の上限: 1つのAppKey配下で、最大100,000個のタグを作成できます。
  • TAG長の上限: 各タグの最大長は40バイトです。有効な文字には、英字（大文字・小文字を区別）、数字、アンダースコア、中国語文字が含まれます。
  • デバイスのTAGバインド上限: 各デバイスには最大100個のタグをバインドできます。
  • デバイス数の上限: 1つのタグ配下に、最大100,000台のデバイスを追加できます。

有料プランをご利用中で、有料AppKeyの利用上限の調整をご希望の場合は、弊社営業チーム（Sales@engagelab.com）までお問い合わせください。

Alias使用時の制限とルール

  • デバイスとエイリアスのマッピング: 1つのエイリアスは1台のデバイスにのみ対応でき、複数のデバイスには対応できません。同様に、AppKeyの範囲内では、各デバイスは1つのエイリアスにのみマッピングでき、複数のエイリアスにはマッピングできません。
  • Alias長の上限: 各エイリアスの最大長は40バイトです。有効な文字には、英字（大文字・小文字を区別）、数字、アンダースコア、中国語文字が含まれます。

有料プランをご利用中で、有料AppKeyの利用上限の調整をご希望の場合は、弊社営業チーム（Sales@engagelab.com）までお問い合わせください。

API概要

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

これには、device、tag、alias の3つのAPIグループが含まれます。各グループの用途は以下のとおりです。

  • device: タグや alias を含む各種デバイス属性の照会および設定に使用されます。
  • tag: デバイスタグの照会、設定、削除に使用されます。
  • alias: デバイスエイリアスの照会、設定、削除に使用されます。

もう1つ重要な情報として、registration ID があります。

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

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

AppKey配下のタグ数を照会する

Endpoint

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

リクエスト例

Request Header

GET /v4/tags_count Authorization: Basic (base64 auth string) Accept: application/json
              
              GET /v4/tags_count
Authorization: Basic (base64 auth string)
Accept: application/json
このコードブロックはフローティングウィンドウ内に表示されます

Request Example

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

Request Parameters

  • tags: 指定したタグ文字列を照会します。必須です。一度に最大1,000個のタグを照会できます（tags=tag1&tags=tag2&tags=tag3）。
  • platform: 指定したプラットフォームを照会します。必須です。有効な値は android、ios、hmos です。その他の値は使用できません。

レスポンス例

  • リクエストが成功すると、tagsCount フィールドを含むJSONオブジェクトが返されます。これはキーと値のペアの集合で、キーはタグ名、値はそのタグ配下の件数です。
  • リクエストが失敗した場合は、エラー情報を含むJSONオブジェクトが返されます。code フィールドはエラーコード、message フィールドはエラーメッセージを示します。

Successful Response

{ "tagsCount": { "tag1": 0, "tag2": 1, "tag3": 2 } }
              
              {
  "tagsCount": {
    "tag1": 0,
    "tag2": 1,
    "tag3": 2
  }
}
このコードブロックはフローティングウィンドウ内に表示されます

Failed Response

{ "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とタグを照会する

  • 現在のデバイスのすべての属性を取得します。タグおよび alias を含みます。

Endpoint

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

Request Example

Request Header

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

Request Parameters

  • registration_id: 必須。デバイスの registration_id です。

レスポンス例

Successful Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
このコードブロックはフローティングウィンドウ内に表示されます

Response Data

{ "tags": ["tag1", "tag2"], "alias": "alias1" }
              
              {
  "tags": ["tag1", "tag2"],
  "alias": "alias1"
}
このコードブロックはフローティングウィンドウ内に表示されます
  • 統計項目が見つからない場合は null、それ以外の場合はその統計項目の値が返されます。

デバイスのAliasとタグを設定する

  • 現在のデバイスの指定属性を更新します。現在はタグと alias をサポートしています。

Endpoint

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

Request Example

Request Header

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

Request Data

{ "tags": { "add": [ "tag1", "tag2" ], "remove": [ "tag3", "tag4" ] }, "alias": "alias1" }
              
              {
  "tags": {
    "add": [
      "tag1",
      "tag2"
    ],
    "remove": [
      "tag3",
      "tag4"
    ]
  },
  "alias": "alias1"
}
このコードブロックはフローティングウィンドウ内に表示されます

Request Parameters

  • registration_id: 必須。デバイスの registration_id です。
  • tags: add、remove、または空文字列をサポートします。tags パラメータが空文字列の場合、すべてのタグをクリアします。add / remove は、指定したタグを追加または削除することを意味します。
  • alias: デバイスのエイリアス属性を更新します。alias が空文字列の場合、指定したデバイスのエイリアスは削除されます。

レスポンス例

Successful Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
このコードブロックはフローティングウィンドウ内に表示されます

Response Data

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

Failed Response

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

タグ一覧を照会する

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

Endpoint

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

Request Example

Request Header

GET /v4/tags/ Authorization: Basic (base64 auth string) Accept: application/json
              
              GET /v4/tags/
Authorization: Basic (base64 auth string)
Accept: application/json
このコードブロックはフローティングウィンドウ内に表示されます

Request Parameters

  • なし

Request Example

Successful Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
このコードブロックはフローティングウィンドウ内に表示されます

Response Data

{ "tags": [ "tag1", "tag2" ] }
              
              {
  "tags": [
    "tag1",
    "tag2"
  ]
}
このコードブロックはフローティングウィンドウ内に表示されます
  • 統計項目が見つからない場合は null、それ以外の場合はその統計項目の値が返されます。

デバイスとタグのバインド関係を照会する

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

Endpoint

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

Request Example

Request Header

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

Request Parameters

  • tag_value: 必須。照会するタグです。
  • registration_id: 必須。デバイスの registration_id です。

レスポンス例

Successful Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
このコードブロックはフローティングウィンドウ内に表示されます

Response Data

{ "result": true }
              
              {
  "result": true
}
このコードブロックはフローティングウィンドウ内に表示されます

タグを更新する

  • タグに対してデバイスを追加または削除します。

Endpoint

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

Request Example

Request Header

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

Request Data

{ "registration_ids": { "add": [ "registration_id1", "registration_id2" ], "remove": [ "registration_id1", "registration_id2" ] } }
              
              {
  "registration_ids": {
    "add": [
      "registration_id1",
      "registration_id2"
    ],
    "remove": [
      "registration_id1",
      "registration_id2"
    ]
  }
}
このコードブロックはフローティングウィンドウ内に表示されます

Request Parameters

  • tag_value: 必須。対象のタグです。
  • action: 操作タイプ。add と remove の2種類があり、このリクエストでデバイスを追加するか削除するかを示します。
  • registration_ids: 追加または削除するデバイスの registration_id 値です。
  • add / remove: それぞれ最大1,000件までサポートします。

レスポンス例

Successful Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
このコードブロックはフローティングウィンドウ内に表示されます

Response Data

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

Failed Response

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

タグを削除する

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

Endpoint

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

Request Example

Request Header

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

Request Parameters

  • tag_value: 必須。削除するタグです。
  • platform: 任意。指定しない場合、デフォルトですべてのプラットフォームが対象となります。

レスポンス例

Successful Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
このコードブロックはフローティングウィンドウ内に表示されます

Response Data

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

Failed Response

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

Alias（デバイスとのバインド関係）を照会する

GET /v4/aliases/{alias_value} 指定した alias 配下のデバイスを取得します。
              
              GET /v4/aliases/{alias_value}
指定した alias 配下のデバイスを取得します。
このコードブロックはフローティングウィンドウ内に表示されます

Aliasを照会する

  • 指定した alias 配下のデバイスを取得します。

Endpoint

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

Request Example

Request Header

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

Request Parameters

  • alias_value: 必須。照会する alias です。
  • platform: 任意。指定しない場合、デフォルトですべてのプラットフォームが対象となります。

レスポンス例

Successful Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
このコードブロックはフローティングウィンドウ内に表示されます

Response Data

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

Request Example

Request Header

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

Request Parameters

  • alias_value: 必須。削除する alias です。
  • platform: 任意。指定しない場合、デフォルトですべてのプラットフォームが対象となります。

レスポンス例

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

ユーザーのオンライン状態を取得する

Endpoint

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

Request Example

Request Header

POST /v4/devices/status/ Authorization: Basic (base64 auth string) Accept: application/json
              
              POST /v4/devices/status/
Authorization: Basic (base64 auth string)
Accept: application/json
このコードブロックはフローティングウィンドウ内に表示されます

Request Data

{ "registration_ids": [ "010b81b3582", "0207870f1b8", "0207870f9b8" ] }
              
              {
  "registration_ids": [
    "010b81b3582",
    "0207870f1b8",
    "0207870f9b8"
  ]
}
このコードブロックはフローティングウィンドウ内に表示されます

Request Parameters

  • registration_ids: オンライン状態を確認したいユーザーの registration_id 値です。1回の照会で最大1,000件の registration_id 値をサポートします。
  • このAPIは、この機能の承認を受けた AppKey に対してのみ呼び出すことができます。

レスポンス例

Successful Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
このコードブロックはフローティングウィンドウ内に表示されます

Response Data

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

Response Data

  • online
    • true: 直近10分以内にオンラインです。
    • false: 直近10分以内にオンラインではありません。
  • last_online_time
    • online が true の場合、このフィールドは返されません。
    • online が false で、このフィールドも返されない場合、最終オンライン時刻が2日以上前であることを意味します。
  • 無効な regid 値、または AppKey に属していない regid 値は検証に失敗します。

TAG/Alias クォータ情報照会API

指定した AppKey、プラットフォーム、タグに関連するクォータ情報を照会します。一度に照会できるタグは1,000個以下です。

Endpoint

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

Request Example

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

Successful Response

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

Response Field Descriptions:

  • totalTagQuota: アプリケーション配下のタグ総数のクォータを示します。
  • useTagQuota: 使用済みのタグクォータを示します。
  • totalAliasQuota: アプリケーション配下のエイリアス総数のクォータを示します。
  • useAliasQuota: 使用済みのエイリアスクォータを示します。
  • tagUidQuota: 単一タグのデバイスクォータを示します。
  • useUidQuota: 各タグにバインドされているデバイス数の詳細を示します。

Failed Response

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

HTTPステータスコード

参考ドキュメント: Http-Status-Code

ビジネス返却コード

Code Description Detailed Explanation 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 システム制限 デバイスにバインドされているタグ数が上限を超えています。1台のデバイスには最大100個のタグをバインドできます 401
27012 パラメータエラー デバイスにバインドしようとしているタグが存在しません 401
27013 パラメータエラー アプリケーション配下のタグ数が上限を超えています。1つのアプリケーションで最大100,000個のタグを作成できます 401
27014 システム制限 タグ配下のUID数が上限を超えています。1つのタグには最大100,000台のデバイスをバインドできます 401
27015 パラメータエラー デバイスにバインドされているエイリアスが存在しません 401
27016 システム制限 アプリケーション配下のエイリアス数が上限を超えています。1つのアプリケーションで最大100,000個のエイリアスを作成できます 401
27017 パラメータエラー タグ長が40文字を超えています 401
Icon Solid Transparent White Qiyu
お問い合わせ