<strong>Scheduled Tasks API</strong>

概要

APIはタイミング機能をサポートするように設計されています。

これは比較的独立したタスク実行モジュールで、Scheduleオブジェクトを管理しています。

注意： スケジュール情報のクエリ/更新/削除には、API機能を呼び出してください。

呼び出し認証

詳細については、認証方法を参照してください。

スケジュールパラメータの説明

各スケジュールタスクには、name、enabled、trigger、pushの4つのフィールドが含まれています。

Keyword	Type	Optional	Description
name	string	required	スケジュールタスクの名前で、255バイトを超えることができず、漢字、英字、数字、アンダースコアで構成されます。
enabled	bool	required	タスクの現在の状態。タスク作成時にはtrueでなければなりません。
trigger	JSON Object	required	スケジュールタスクのトリガー条件とタイミング。現在、一度限りのタスク（`single`）、定期的なタスク（`periodical`）、インテリジェント配信（`intelligent`）をサポートしています。
push	JSON Object	required	プッシュコンテンツ情報。

Singleの説明

スケジュールタスクのトリガー条件を記述し、スケジュールタスクのトリガー時間とタイプを含みます。

パラメータ	型	オプション	説明
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の説明

パラメータ	型	オプション	説明
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の説明

パラメータ	型	必須/オプション	意味
backup_time	String	必須	インテリジェント配信はEngageLabの独自機能で、通知のクリック率を最適化するように設計されています。ユーザーがEngageLab SDKをインストールしたWebサイトまたはモバイルアプリからサービスにアクセスするたびに、最新のアクティブ時間が追跡されます。システムはこのデータを記録し、ユーザーの過去の使用習慣に基づいて、各ユーザーの端末タイムゾーンに従って適切な時間に通知を送信します。アクティブな履歴データのないユーザーの場合、即時送信するか、指定した時間に送信するかを選択する必要があります（エンドユーザーのタイムゾーンに基づきます）。即時送信の場合：now 予定送信の場合：形式は厳密に「yyyy-MM-dd HH:mm:ss」でなければならず、時間は24時間形式でなければなりません。

スケジュールタスクの作成

リクエストAPI

POST v4/schedules

呼び出し制限

有効なスケジュールタスク（現在有効期限が切れていない）の総数はデフォルトで1000です。総数を超えると、新しいスケジュールタスクは失敗を示します。
タスクの最大期間に制限はありませんが、1年を超えないことを推奨します。

リクエスト例

リクエストヘッダー

POST /v4/schedules Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              POST /v4/schedules
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

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

リクエストボディ

{ "name":"schedule push example", "enabled":true, "trigger":{ "single":{ "time":"2022-11-23 19:20:00", "zone_type":1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

              
              {
    "name":"schedule push example",
    "enabled":true,
    "trigger":{
        "single":{
            "time":"2022-11-23 19:20:00",
            "zone_type":1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "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 < Server: fasthttp < Date: Thu, 01 Dec 2022 07:17:45 GMT < Content-Type: application/json < Content-Length: 85

              
              < HTTP/1.1 200 OK
< Server: fasthttp
< Date: Thu, 01 Dec 2022 07:17:45 GMT
< Content-Type: application/json
< Content-Length: 85

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

{ "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6", "name": "the schedule task name" }

              
              {
    "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
    "name": "the schedule task name"
}

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

エラーレスポンス

HTTP/1.1 400 BAD REQUEST Content-Type: application/json; charset=utf-8

              
              HTTP/1.1 400 BAD REQUEST
 Content-Type: application/json; charset=utf-8

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

{ "error": { "code": 28400, "message": "error message" } }

              
              {
    "error": {
        "code": 28400,
        "message": "error message"
    }
}

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

繰り返しスケジュールタスクのリクエスト例

{ "name":"Timed Push Example_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":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"67890", "custom_args":{ "Engagelab": "push to you" } } }

              
              {
    "name":"Timed Push Example_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":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"67890",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

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

有効なスケジュールタスクリストの取得

現在有効な（有効期限が切れていない）スケジュールのリストを取得します。

リクエストAPI URL

GET v4/schedules?page=

リクエスト例

リクエストヘッダー

GET /v4/schedules?page= Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              GET /v4/schedules?page=
 Authorization: Basic (base64 auth string) 
 Content-Type: application/json
 Accept: application/json

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

現在のリクエストページの詳細なスケジュールタスクリストを返します。pageを指定しない場合、ページは1になります。
ソートルール：作成時間によるもので、schedule-serviceによって実行されます。
リクエストされたページ数が総ページ数を超える場合、ページはリクエスト値になり、scheduleは空になります。
1ページあたり最大50件のタスクを返すことができます。リクエストページの実際のタスク数が50件未満の場合、実際の数が返されます。

レスポンス例

成功レスポンス

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8

              
              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 }, {} // 詳細情報リスト ] }

              
              {
    "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 task id {schedule_id}のスケジュールタスクの詳細を取得します。

リクエストAPI URL

GET v4/schedules/{schedule_id}

リクエスト例

リクエストヘッダー

GET /v4/schedules/{schedule_id} Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              GET /v4/schedules/{schedule_id}
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 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

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

レスポンスデータ

[{ "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512", "name": "the scheduled task example", "enabled": true, "trigger": {...}, "push": {...} }]

              
              [{
    "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
    "name": "the scheduled task example",
    "enabled": true,
    "trigger": {...},
    "push": {...}
}]

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

schedule_idが存在しない場合、404を返します。それ以外の場合、スケジュールタスクの詳細を返します。

スケジュールタスクのすべてのmessage idの取得

現在のユーザーのid {schedule_id}のスケジュールタスクのすべてのmessage idを取得します。

リクエストAPI URL

GET v4/schedules/{schedule_id}/msg-ids

リクエスト例

リクエストヘッダー

GET /v4/schedules/{schedule_id}/msg-ids Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              GET /v4/schedules/{schedule_id}/msg-ids
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 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

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

レスポンスデータ

繰り返しスケジュールタスク機能が2024年2月22日にオンラインになった後、返されるデータ形式が更新され、古いmsgidの代わりに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}" ] }

              
              {
    "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のスケジュールタスクを更新します。

リクエストAPI URL

PUT v4/schedules/{schedule_id}

リクエスト例

PUT /v4/schedules/{schedule_id} Authorization: Basic (base64 auth string) Content-Type: application/x-www-form-urlencoded Accept: application/json

              
              PUT /v4/schedules/{schedule_id}
 Authorization: Basic (base64 auth string) 
 Content-Type: application/x-www-form-urlencoded
 Accept: application/json

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

{ "name": "task", "enabled": true, "trigger": {...}, "push": {...} }

              
              {
  "name": "task", 
  "enabled": true, 
  "trigger": {...},
  "push": {...} 
}

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

有効期限が切れたスケジュールタスクを更新することはできません。
端末タイムゾーンでプッシュされるタイミングタスクとメインタイムゾーンでプッシュされるタイミングタスクは相互に更新できず、その逆も同様です。
["name", "enabled", "trigger", "push"]配列の中の1つまたは複数のフィールドを更新することができます。更新ボディは一部にすることができず、全体のボディでなければなりません。以下に例を示します：

{ "name":"the scheduled task example", "enabled":true, "trigger":{ "single":{ "time":"2022-11-23 19:20:00", "zone_type":1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

              
              {
    "name":"the scheduled task example",
    "enabled":true,
    "trigger":{
        "single":{
            "time":"2022-11-23 19:20:00",
            "zone_type":1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

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

以下は、不正な更新の例と対応する正しい更新の例です：

## 不正：pushフィールドのalertのみを更新する： { "push": { "alert": "web scheduled task" } } ## 正しい：pushフィールドのalertを更新する： { "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web scheduled task", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } } ## pushフィールドは有効でなければなりません。それ以外の場合、更新は失敗します。

              
              ## 不正：pushフィールドのalertのみを更新する：
{
    "push": {
        "alert": "web scheduled task"
    }
}
## 正しい：pushフィールドのalertを更新する：
{
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web scheduled task",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

## pushフィールドは有効でなければなりません。それ以外の場合、更新は失敗します。

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

レスポンス例

成功レスポンス

HTTP/1.0 200 CREATED Content-Type: application/json

              
              HTTP/1.0 200 CREATED
 Content-Type: application/json

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

{ "name":"Timed push example", "enabled":true, "trigger":{ "single":{ "time":"2022-11-23 19:20:00", "zone_type":1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

              
              {
    "name":"Timed push example",
    "enabled":true,
    "trigger":{
        "single":{
            "time":"2022-11-23 19:20:00",
            "zone_type":1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

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

エラーレスポンス

schedule_idが無効

HTTP/1.0 404 Not Found Content-Type: application/json

              
              HTTP/1.0 404 Not Found
 Content-Type: application/json

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

不正な更新操作

HTTP/1.0 400 BAD REQUEST Content-Type: application/json

              
              HTTP/1.0 400 BAD REQUEST
 Content-Type: application/json

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

スケジュールタスクの削除

リクエストAPI URL

DELETE v4/schedules/{schedule_id}

schedule_id は既存のスケジュールタスクのidです。schedule_idが無効または有効なidでない場合、結果は404エラーになります。

リクエスト例

DELETE /v4/schedules/{schedule_id} Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              DELETE /v4/schedules/{schedule_id}
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

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

レスポンス例

成功レスポンス

HTTP/1.0 200 Content-Type: application/json Content-Length: 0

              
              HTTP/1.0 200 
  Content-Type: application/json
  Content-Length: 0

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

エラーレスポンス

HTTP/1.0 404 Not Found Content-Type: application/json Content-Length: 0

              
              HTTP/1.0 404 Not Found 
  Content-Type: application/json
  Content-Length: 0

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

{ "error":{ "code":28404, "message":"error message" } }

              
              {
  "error":{
    "code":28404,
    "message":"error message"
  }
}

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

エラーコード

コード	HTTP	説明	エラーメッセージ	詳細説明
-	200	成功を返す	-	成功状態
28100	400	パラメータが無効	The schedule-task is invalid：section is invalid;has been at term;expired;request data is not json;update target task;Delete target task;schedule request is not exist	パラメータが不正または無効です。プッシュが制限を超えています（例：プッシュブロードキャストが制限を超えている、スケジュールタスクの数が制限を超えている、定速タスクが制限を超えているなど）。パラメータボディが長すぎます。
28101	401	認証に失敗しました	Basic authentication failed.	appkey、masterscrectがschedule serverと一致しません
28104	404	スケジュールタスクが存在しません	Request schedule operation doesn't exist	対応するタスクは既に送信されているか、schedule idが正しくありません。
28105	404	設定された時間に対応するプッシュ対象がありません	The push task is invalid. There is no push target for the scheduled time	push timeパラメータが無効です
28200	500	内部エラー	Server Internal error.	予期しないエラーが発生しました。
28203	503	内部システムエラー、後で再試行してください	Execute action timeout, please try later again	schedule-serverとの通信エラーです。