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

Tag Alias API

最新更新：2年以上前

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

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

tag と alias の詳細については、対応するクライアントプラットフォームの API ドキュメントを参照してください。

TAG 使用時の制約とルール

  • TAG 数量制限: 1 つの appkey につき、最大 100,000 個の Tags を作成できます。
  • TAG 長さ制限: 各 Tag の最大長は 40 バイトです。有効な文字は、英字（大文字・小文字を区別）、数字、アンダースコア、および中国語文字です。
  • デバイス TAG バインド数制限: 各デバイスには最大 100 個の Tags をバインドできます。
  • デバイス数制限: 1 つの Tag には最大 100,000 台のデバイスを追加できます。

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

alias 使用時の制約とルール

  • デバイスと alias のマッピング関係: 1 つの alias は 1 台のデバイスにのみ対応でき、複数のデバイスに対応させることはできません。同様に、各デバイスは appkey の範囲内で 1 つの alias にのみマッピングでき、複数の aliases にマッピングすることはできません。
  • alias 数量制限: 1 つの appkey につき、最大 100,000 個の aliases を作成できます。
  • alias 長さ制限: 各 alias の最大長は 40 バイトです。有効な文字は、英字（大文字・小文字を区別）、数字、アンダースコア、および中国語文字です。

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

API 概要

Device API は、サーバー側でデバイスの tag および alias 情報を照会、設定、更新、削除するために使用します。

この API は、device、tag、alias の 3 つの API グループで構成されています。各グループの用途は次のとおりです。

  • device は、tags や alias を含むデバイスの各種プロパティの照会／設定に使用されます。
  • tag は、device tags の照会／設定／削除に使用されます。
  • alias は、device aliases の照会／設定／削除に使用されます。

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

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

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

AppKey 配下の Tag 数を照会する

Endpoint

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

Request Example

Request Headers

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: 指定した tag 文字列を照会します。必須です。1 回のリクエストで最大 1000 個の tags を照会できます（tags=tag1&tags=tag2&tags=tag3）。
  • platform: 指定したプラットフォームを照会します。必須です。有効な値は android、ios、hmos、web です。その他の値は使用できません。

Response Example

  • リクエストが成功すると、tagsCount フィールドを含む JSON オブジェクトが返されます。これは、キーが tag 名、値がその tag 配下の件数であるキー・バリューのコレクションです。
  • リクエストが失敗すると、エラー情報を含む 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 と Tags を照会する

  • 現在のデバイスのすべてのプロパティを取得します。tags と alias を含みます。

Endpoint

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

Request Example

Request Headers

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。

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

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

  • 現在のデバイスの指定したプロパティを更新します。現在は tags と alias をサポートしています。

Endpoint

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

Request Example

Request Headers

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 パラメータが空文字列の場合、すべての tags がクリアされることを意味します。add / remove は、指定した tags の追加または削除に使用します。
  • alias: デバイスの alias プロパティを更新します。alias が空文字列の場合、指定したデバイスの alias は削除されます。

Response 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

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

Failed Response

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

Tag リストを照会する

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

Endpoint

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

Request Example

Request Headers

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

Request Parameters

  • None

Response 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、それ以外の場合はその統計項目の値が返されます。

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

  • デバイスが特定の tag に属しているかどうかを照会します。

Endpoint

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

Request Example

Request Headers

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: 必須。照会する tag。
  • registration_id: 必須。デバイスの registration_id。

Response 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

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

Tag を更新する

  • tag に紐づくデバイスを追加または削除します。

Endpoint

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

Request Example

Request Headers

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: 必須。照会する tag。
  • action: 操作種別。"add" と "remove" の 2 つがあり、このリクエストが追加か削除かを示します。
  • registration_ids: 追加または削除する対象のデバイス registration_id 値。
  • add / remove: それぞれ最大 1000 件までサポートします。

Response 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

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

Tag を削除する

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

Endpoint

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

Request Example

Request Headers

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

Request Parameters

  • tag_value: 必須。照会する tag。
  • platform: 任意。省略した場合のデフォルトは全プラットフォームです。

Response 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

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

Failed Response

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

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

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

Alias を照会する

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

Endpoint

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

Request Example

Request Headers

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

Request Parameters

  • alias_value: 必須。照会する alias。
  • platform: 任意。省略した場合のデフォルトは全プラットフォームです。

Response 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

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

Alias を削除する

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

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

Request Example

Request Headers

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

Request Parameters

  • alias_value: 必須。削除する alias。
  • platform: 任意。省略した場合のデフォルトは全プラットフォームです。

Response Example

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

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

Endpoint

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

Request Example

Request Headers

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 回の照会で最大 1000 件の registration_id 値をサポートします。
  • この API は、このサービスを申請して有効化した AppKeys に対してのみ呼び出すことができます。

Response 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

[ { "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、platform、および tag に関連するクォータ情報を照会します。一度に照会できる tags は 1000 個以下です。

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

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: アプリケーション配下の tag 総数のクォータを示します。
  • useTagQuota: 使用済みの tag クォータを示します。
  • totalAliasQuota: アプリケーション配下の alias 総数のクォータを示します。
  • useAliasQuota: 使用済みの alias クォータを示します。
  • tagUidQuota: 単一 tag 配下のデバイス数のクォータを示します。
  • useUidQuota: 各 tag にバインドされているデバイス数の詳細を示します。

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 認証エラー invalid appkey 401
27000 システムメモリエラー please try again 500
27001 パラメータエラー validation information is empty 401
27002 パラメータエラー invalid parameter 400
27004 パラメータエラー validation failed 401
27005 パラメータエラー invalid regisID format 400
21008 パラメータエラー app_key is not a 24-character string or does not exist 400
27010 パラメータエラー alias is already bound to another regid 400
27011 システム制限 デバイスにバインドされている tag 数が上限を超えています。1 台のデバイスには最大 100 個の Tags をバインドできます 401
27012 パラメータエラー デバイスにバインドする Tag が存在しません 401
27013 パラメータエラー アプリケーション配下の tag 数が上限を超えています。1 つのアプリケーションでは最大 100,000 個の Tags を作成できます 401
27014 システム制限 tag 配下の uid 数が上限を超えています。1 つの Tag には最大 100,000 台のデバイスをバインドできます 401
27015 パラメータエラー デバイスにバインドされた Alias が存在しません 401
27016 システム制限 アプリケーション配下の alias 数が上限を超えています。1 つのアプリケーションでは最大 100,000 個の Aliases を作成できます 401
27017 パラメータエラー tag の長さが 40 文字を超えています 401
Icon Solid Transparent White Qiyu
お問い合わせ