スケジュールタスクAPI
API層はタイムド機能をサポートし、独立したタスク実行のためにScheduleオブジェクトを維持します。
注記: APIを通じて作成されたスケジュールタスクは、API呼び出しを介してのみ取得、修正、または削除することができます。
認証
詳細については、REST API概要の認証方法を参照してください。
スケジュールパラメータの説明
各スケジュールタスクは、名前、有効状態、トリガー、プッシュの4つのセクションで構成されています。
パラメータ | タイプ | オプション | 説明 |
---|---|---|---|
name | String | 必須 | スケジュールタスクの名前で、255バイトを超えてはならず、漢字、英字、数字、アンダースコアで構成されます。 |
enabled | Boolean | 必須 | タスクの現在の状態を示します。タスク作成時にはtrueでなければなりません。 |
trigger | JSONオブジェクト | 必須 | スケジュールタスクのトリガー条件とタイミング。現在、一度限りのタスク(single )、定期的なタスク(periodical )、インテリジェント配信(intelligent )をサポートしています。詳細は単一タスクの説明を参照してください。 |
push | JSONオブジェクト | 必須 | プッシュの内容情報で、アプリプッシュドキュメントのフィールドを参照してください。 |
単一タスクの説明(Single Description)
スケジュールタスクのトリガー条件を説明し、スケジュールタスクのトリガー時間とタイプを含みます。
パラメータ | タイプ | オプション | 説明 |
---|---|---|---|
time | String | 必須 | スケジュールタスクのトリガー時間で、標準時間形式「yyyy-mm-dd hh:mm:ss」(例:「2014-02-15 13:16:59」)で指定します。「2014-2-15 13:16:59」や「2014-12-15 13:16」などの不完全な形式は受け付けられません。スケジュールタスクの最遅時間は1年を超えてはなりません。 |
zone_type | Int | 必須 | スケジュールタスクのタイプを示します:1はメインサイトに設定されたタイムゾーンに従ってトリガーされることを意味し、2はユーザー端末のタイムゾーンに従ってトリガーされることを意味します。 |
定期タスクの説明(Periodical Description)
パラメータ | タイプ | オプション | 説明 |
---|---|---|---|
start | String | 必須 | 定期タスクの有効開始時間で、厳密に「yyyy-MM-dd HH:mm:ss」形式で指定し、24時間形式でなければなりません。 |
end | String | 必須 | 定期タスクの有効期限で、形式は上記と同じです。定期タスクの最大期間は1年を超えてはなりません。 |
time | String | 必須 | 定期タスクがトリガーされる特定の時間で、厳密に「HH:mm:ss」形式で指定し、24時間形式でなければなりません。 |
time_unit | String | 必須 | 定期タスク実行の最小時間単位で、「day」(日)、「week」(週)、「month」(月)の3つのオプションをサポートしています。大文字と小文字は区別されません。 |
point | String | 必須 | time_unitに対応するリスト:以下の表を参照してください。 |
zone_type | Int | 必須 | スケジュールタスクのタイプを示します:1はメインサイトに設定されたタイムゾーンに従ってトリガーされることを意味し、2はユーザー端末のタイムゾーンに従ってトリガーされることを意味します。 |
pointパラメータの詳細情報:
time_unit | point | 説明 |
---|---|---|
day | NULL | time_unitがdayの場合、pointは適用されません。 |
week | "MON","TUE","WED","THU","FRI","SAT","SUN" | weekの場合、pointはトリガーする曜日を示し、1つまたは複数の曜日を指定できます。大文字と小文字は区別されません。 |
month | "01","02","03" ... "31" | monthの場合、pointは月の有効な日付に対応し、無効な日付(例:2月の31日や30日)にはトリガーされません。 |
インテリジェント配信の説明(Intelligent Description)
パラメータ | タイプ | 必須/オプション | 意味 |
---|---|---|---|
backup_time | String | 必須 | インテリジェント配信はEngageLabの独自機能で、通知のクリック率を最適化するよう設計されています。ユーザーがEngageLab SDKをインストールしたウェブサイトまたはモバイルアプリを通じてサービスにアクセスするたびに、ユーザーの直近のアクティブ時間を追跡します。システムはこのデータを記録し、ユーザーの過去の使用習慣に基づいて、各ユーザーの端末タイムゾーンに従って適切な時間に通知を送信します。アクティブな履歴データのないユーザーについては、即時送信するか、指定した時間に送信するかを選択する必要があります(エンドユーザーのタイムゾーンに基づきます)。 |
スケジュールタスクの作成
エンドポイント
POST v4/schedules
制限事項
- 有効なスケジュールタスク(未期限)の総数はデフォルトで1000に制限されています。この数を超えると、新しいタスクの作成は失敗します。
- スケジュールタスクの最大期間に制限はありませんが、1年を超えないことを推奨します。
リクエスト例
リクエストヘッダー
POST /v4/schedules
Authorization: Basic (base64認証文字列)
Content-Type: application/json
Accept: application/json
リクエストボディ
単一スケジュールタスクのリクエスト例
{
"name":"タイムドプッシュ例_single",
"enabled":true,
"trigger":{
"single":{
"time":"2022-11-23 19:20:00",
"zone_type":1
}
},
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"android",
"notification":{
"alert":"APIからのスケジュールタスク",
"android":{
"title":"APIからのスケジュールタスク",
"extras":{
"key1":"value1"
}
}
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":{
"Engagelab": "push to you"
}
}
}
定期スケジュールタスクのリクエスト例
{
"name":"タイムドプッシュ例_periodical",
"enabled":true,
"trigger":{
"periodical": {
"start": "2024-01-01 00:00:00",
"end": "2024-02-10 00:00:00",
"time": "12:00:00",
"time_unit": "day",
"point": [],
"zone_type": 1
}
},
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"android",
"notification":{
"alert":"定期タスクの繰り返し",
"android":{
"title":"定期タスクの繰り返し",
"extras":{
"key1":"value1"
}
}
},
"options":{
"time_to_live":60
}
},
"request_id":"67890",
"custom_args":{
"Engagelab": "push to you"
}
}
}
インテリジェント配信のリクエスト例
{
"name":"インテリジェント配信",
"enabled":true,
"trigger":{
"intelligent": {
"backup_time":"2024-01-01 00:00:00"
}
} ,
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"android",
"notification":{
"alert":"APIからのスケジュールタスク",
"android":{
"title":"APIからのスケジュールタスク",
"extras":{
"key1":"value1"
}
}
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":{
"Engagelab": "push to you"
}
}
}
リクエストデータの説明
zone_type
は指定されたフィールド値(1または2)で入力する必要があります。そうしない場合、サーバーのタイムゾーンに従ってプッシュが実行されます。- スケジュールタスクを最初に作成するときは、
enabled
フィールドはtrueでなければなりません。enabled: false
のタスクの作成は失敗します。 push
は有効で合法的なプッシュアクションでなければなりません。そうしない場合、作成は失敗します。
レスポンス例
成功レスポンス
HTTP/1.1 200 OK
Content-Type: application/json
{
"schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
"name": "タイムドタスク名"
}
失敗レスポンス
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json; charset=utf-8
{
"error": {
"code": 28400,
"message": "エラーメッセージ"
}
}
有効なスケジュールタスクリストの取得
- 現在有効な(期限切れでない)スケジュールのリストを取得します。
エンドポイント
GET v4/schedules?page=
リクエスト例
リクエストヘッダー
GET /v4/schedules?page=
Authorization: Basic (base64認証文字列)
Content-Type: application/json
Accept: application/json
- 現在のリクエストページのスケジュールタスクリストの詳細が返されます。ページが指定されていない場合は、デフォルトでページ1になります。
- ソートは作成時間で行われ、schedule-serviceによって処理されます。
- リクエストされたページ番号が総ページ数を超える場合、
page
はリクエストされた値になり、schedules
は空になります。 - 1ページあたりの最大タスク数は50です。リクエストされたページの実際のタスク数が50未満の場合は、実際のタスク数が返されます。
レスポンス例
成功レスポンス
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"total_count": 1000,
"total_pages": 5,
"page": 4,
"schedules": [
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "",
"enabled": true
},
{} // 詳細情報のリスト。
]
}
- これは合計1000個のスケジュールタスクがあり、5ページに分かれていることを示しています。現在のページは4ページで、50個のスケジュールタスクの情報が含まれています。
- 返される
schedules
はスケジュールタスク情報の詳細リストです。
スケジュールタスクの詳細を取得
- 現在のユーザーの
{schedule_id}
のIDを持つスケジュールタスクの詳細を取得します。
エンドポイント
GET v4/schedules/{schedule_id}
リクエスト例
リクエストヘッダー
GET /v4/schedules/{schedule_id}
Authorization: Basic (base64認証文字列)
Content-Type: application/json
Accept: application/json
レスポンス例
成功レスポンス
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
レスポンスデータ
[{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "定时推送示例",
"enabled": true,
"trigger": {...},
"push": {...}
}]
スケジュールタスクのすべてのメッセージIDを取得
- 現在のユーザーに属する
{schedule_id}
のIDを持つスケジュールタスクのすべてのメッセージIDのリストを取得します。
エンドポイント
GET v4/schedules/{schedule_id}/msg-ids
リクエスト例
リクエストヘッダー
GET /v4/schedules/{schedule_id}/msg-ids
Authorization: Basic (base64認証文字列)
Content-Type: application/json
Accept: application/json
レスポンス例
成功レスポンス
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
レスポンスデータ
繰り返しスケジュールタスク機能が2024年2月22日にオンラインになった後、返されるデータ形式が更新され、古いmsgidsに置き換えてMsgIdsデータが追加されました。コードが互換性を持つようにしてください。
tsフィールドはスケジュールタスクが正常に実行されたタイムスタンプを示し、ミリ秒単位で正確です。
{
"count": 1,
"MsgIds": [
"{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}",
"{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Cannot find sending target\"},\"needRetry\":false,\"ts\":1707278411611}"
]
}
スケジュールタスクを更新
- IDによって指定されたスケジュールタスクを更新します。
エンドポイント
PUT v4/schedules/{schedule_id}
リクエスト例
リクエストヘッダー
PUT /v4/schedules/{schedule_id}
Authorization: Basic (base64認証文字列)
Content-Type: application/x-www-form-urlencoded
Accept: application/json
リクエストボディ
{
"name": "task",
"enabled": true,
"trigger": {...},
"push": {...}
}
注記:
- 期限切れのスケジュールタスクは更新できません。
- 端末タイムゾーンによってスケジュールされたタスクをメインサイトのタイムゾーンに更新することはできず、その逆も同様です。
- 更新操作には「name」、「enabled」、「trigger」、「push」の変更を含めることができます。部分的な更新はサポートされていません。
不正な更新操作の例
// 不正:プラットフォームをiOSに更新するだけ:
{
"push": {
"body": {
"platform": "ios"
}
}
}
// 不正:終了日を更新するだけ:
{
"trigger": {
"periodical": {
"end": "2024-03-10 00:00:00"
}
}
}
正しい更新操作の例
更新する場合は、push
フィールドのすべての関連サブフィールドを含めて、完全な更新の要件を満たす必要があります。以下は、プラットフォームをiOSに変更した後の更新された完全なpush
構成です:
// 正しい:プラットフォームをiOSに更新:
{
"name": "Scheduled Push Example",
"enabled": true,
"trigger": {
"periodical": {
"start": "2024-01-01 00:00:00",
"end": "2024-02-10 00:00:00",
"time": "12:00:00",
"time_unit": "day",
"point": [],
"zone_type": 1
}
},
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform": "ios",
"notification": {
"alert": "API terminal scheduled task",
"ios": {
"title": "API terminal scheduled task",
"extras": {
"key1": "value1"
}
}
},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args": {
"Engagelab": "push to you"
}
}
}
// 正しい:定期トリガーの終了日を1か月延長:
{
"name": "Scheduled Push Example",
"enabled": true,
"trigger": {
"periodical": {
"start": "2024-01-01 00:00:00", // 元の開始時間を維持
"end": "2024-03-10 00:00:00", // 3月10日まで1か月延長
"time": "12:00:00", // 元のトリガー時間を維持
"time_unit": "day", // 元の時間単位を維持
"point": [], // 元のポイント構成を維持
"zone_type": 1 // 元のタイムゾーンタイプを維持
}
},
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform": "android",
"notification": {
"alert": "API terminal scheduled task",
"android": {
"title": "API terminal scheduled task",
"extras": {
"key1": "value1"
}
}
},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args": {
"Engagelab": "push to you"
}
}
}
これらの更新では、プッシュが有効で効果的なままであることを確認してください。そうしない場合、更新は失敗します。部分的な更新による失敗を避けるため、更新操作では常に完全な構造を送信してください。
レスポンス例
成功レスポンス
HTTP/1.0 200 CREATED
Content-Type: application/json
レスポンスデータ
{
"name": "タイムドプッシュ例",
"enabled": true,
"trigger": {...},
"push": {...}
}
失敗レスポンス
schedule_id
が無効または有効なIDでない場合:
HTTP/1.0 404 Not Found
Content-Type: application/json
- 更新操作が無効な場合:
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
スケジュールタスクの削除
エンドポイント
DELETE v4/schedules/{schedule_id}
schedule_id
は既存のスケジュールタスクのIDです。schedule_id
が無効または有効なIDでない場合、結果は404エラーになります。
リクエスト例
DELETE /v4/schedules/{schedule_id}
Authorization: Basic (base64認証文字列)
Content-Type: application/json
Accept: application/json
レスポンス例
成功レスポンス
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 0
失敗レスポンス
HTTP/1.0 404 Not Found
Content-Type: application/json
Content-Length: 0
{
"error": {
"code": 28404,
"message": "エラーメッセージ"
}
}
エラーコード
以下は、スケジュールタスクAPIを使用するときに発生する可能性のあるエラーコードの表です。
コード | HTTP | 説明 | エラーメッセージ | 詳細な説明 |
---|---|---|---|---|
28000 | 200 | 正しい戻り値 | nil | 成功ステータスコード。 |
28100 | 400 | 無効なパラメータ | スケジュールタスクが無効です:セクションが無効です;期限が切れています;リクエストデータがJSONではありません;ターゲットタスクを更新;ターゲットタスクを削除;スケジュールリクエストが存在しません | 無効または不正なパラメータ、またはプッシュが制限を超えています。 |
28101 | 401 | 認証に失敗しました | Basic認証に失敗しました。 | Appkeyとmaster secretが一致しません。 |
28104 | 404 | リクエストされたスケジュールタスクが存在しません | リクエストされたスケジュール操作は存在しません | タスクはすでに送信されているか、スケジュールIDが正しくありません。 |
28105 | 404 | 設定された時間にプッシュターゲットがありません | プッシュタスクが無効です。スケジュールされた時間にプッシュターゲットがありません | プッシュ時間パラメータが正しくありません。 |
28200 | 500 | サーバー内部エラー | サーバー内部エラー。 | 予期しないエラーが発生しました。 |
28203 | 503 | サーバー内部エラー、後で再試行してください | アクションの実行がタイムアウトしました。後で再試行してください | schedule-serverとの通信エラー。 |