API Tugas Terjadwal

Ringkasan

API ini mendukung fungsi penjadwalan waktu.

Ini adalah modul eksekusi tugas yang relatif independen yang memelihara objek Schedule.

Catatan: Fungsi API hanya dapat digunakan untuk menanyakan, memperbarui, atau menghapus info Schedule.

Validasi Panggilan

Untuk informasi lebih lanjut, lihat Metode Autentikasi

Deskripsi Parameter Schedule

Setiap tugas terjadwal mencakup empat field: name, enabled, trigger, push.

Kata Kunci	Tipe	Opsional	Deskripsi
name	string	wajib	Nama tugas terjadwal, maksimal 255 byte, terdiri dari karakter Tionghoa, huruf, angka, dan garis bawah.
enabled	bool	wajib	Status tugas saat ini. Harus true saat membuat tugas.
trigger	Objek JSON	wajib	Kondisi pemicu dan waktu tugas terjadwal. Mendukung tugas satu kali (`single`), tugas berkala (`periodical`), dan Pengiriman Cerdas (`intelligent`).
push	Objek JSON	wajib	Informasi konten push.

Deskripsi Single

Menjelaskan kondisi pemicu untuk tugas terjadwal, termasuk waktu pemicu dan tipe tugas.

Parameter	Tipe	Opsional	Deskripsi
time	String	Tidak	Waktu pemicu tugas terjadwal, format "yyyy-mm-dd hh:mm:ss", contoh "2014-02-15 13:16:59". Format tidak lengkap tidak diterima. Waktu tugas tidak boleh melebihi satu tahun.
zone_type	Int	Tidak	Jenis zona waktu: 1 untuk zona waktu utama, 2 untuk zona waktu pengguna.

Deskripsi Periodical

Parameter	Tipe	Opsional	Deskripsi
start	String	Tidak	Waktu mulai efektif, format "yyyy-MM-dd HH:mm:ss", wajib 24 jam.
end	String	Tidak	Waktu berakhir, format sama seperti start. Maksimal rentang satu tahun.
time	String	Tidak	Waktu spesifik pemicu, format "HH:mm:ss", wajib 24 jam.
time_unit	String	Tidak	Satuan waktu terkecil: "day", "week", atau "month". Tidak case sensitive.
point	String	Tidak	Daftar sesuai time_unit, lihat tabel di bawah.
zone_type	Int	Tidak	Jenis zona waktu: 1 utama, 2 pengguna.

Detail parameter point:

time_unit	point	Deskripsi
day	NULL	Untuk day, point tidak berlaku.
week	"MON","TUE","WED","THU","FRI","SAT","SUN"	Untuk week, point dapat satu atau lebih hari, tidak case sensitive.
month	"01","02","03" ... "31"	Untuk month, point sesuai tanggal valid dalam bulan, tidak akan memicu pada tanggal tidak valid.

Deskripsi Intelligent

Parameter	Tipe	Wajib/Opsional	Deskripsi
backup_time	String	Wajib	Pengiriman cerdas adalah fitur EngageLab untuk mengoptimalkan rasio klik notifikasi. Setiap pengguna yang mengakses layanan Anda melalui web atau aplikasi mobile dengan SDK EngageLab akan dicatat waktu aktif terakhirnya. Sistem akan mengirim notifikasi pada waktu yang sesuai menurut kebiasaan pengguna. Untuk pengguna tanpa data historis aktif, Anda bisa memilih kirim segera (now) atau waktu tertentu (format "yyyy-MM-dd HH:mm:ss", 24 jam).

Membuat Tugas Terjadwal

request api task

POST v4/schedules

Batasan Panggilan

Jumlah total tugas terjadwal yang valid (belum kedaluwarsa) maksimal 1000 secara default. Jika melebihi, tugas baru gagal dibuat.
Rentang waktu maksimal tugas tidak terbatas, namun disarankan tidak melebihi 1 tahun.

Contoh Permintaan

request header

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

Tampilkan blok kode ini di jendela mengambang

request body

{ "name":"contoh push terjadwal", "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": "selamat datang di engagelab", "title": "selamat datang di engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push untuk Anda" } } }

              
              {
    "name":"contoh push terjadwal",
    "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": "selamat datang di engagelab",
                    "title": "selamat datang di engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push untuk Anda"
    }
    }
}

Tampilkan blok kode ini di jendela mengambang

deskripsi request body

zone_type wajib, nilainya 1 atau 2, jika tidak, akan dipush sesuai zona waktu server
enabled harus true saat pertama kali dibuat. Tidak dapat membuat tugas dengan enabled: false.
push harus berupa aksi push yang valid dan legal.

Contoh Respons：

Return Sukses

< 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

Tampilkan blok kode ini di jendela mengambang

{ "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6", "name": "nama tugas terjadwal" }

              
              {
    "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
    "name": "nama tugas terjadwal"
}

Tampilkan blok kode ini di jendela mengambang

Return Error

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

Tampilkan blok kode ini di jendela mengambang

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

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

Tampilkan blok kode ini di jendela mengambang

Contoh permintaan tugas terjadwal berulang

{ "name":"Contoh Push Terjadwal_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": "selamat datang di engagelab", "title": "selamat datang di engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"67890", "custom_args":{ "Engagelab": "push untuk Anda" } } }

              
              {
    "name":"Contoh Push Terjadwal_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": "selamat datang di engagelab",
                    "title": "selamat datang di engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"67890",
        "custom_args":{
             "Engagelab": "push untuk Anda"
    }
    }
}

Tampilkan blok kode ini di jendela mengambang

Mendapatkan Daftar Tugas Terjadwal yang Valid

Mendapatkan daftar schedule yang saat ini valid (belum kedaluwarsa).

URL Request API

GET v4/schedules?page=

Contoh Permintaan

Request Header

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

Tampilkan blok kode ini di jendela mengambang

Mengembalikan daftar detail schedule-task pada halaman permintaan saat ini. Jika tidak ada halaman yang ditentukan, halaman adalah 1.
Urutan: waktu pembuatan, diatur oleh schedule-service.
Jika halaman permintaan > total halaman, halaman adalah nilai permintaan dan schedules kosong.
Setiap halaman maksimal 50 tugas.

Contoh Respons

Return sukses

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

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

Tampilkan blok kode ini di jendela mengambang

{ "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
        }
    ]
}

Tampilkan blok kode ini di jendela mengambang

1000 schedule-task, 5 total halaman, halaman saat ini adalah 4, termasuk info 50 schedule-task.
Array schedules adalah daftar detail schedule-task

Mendapatkan Detail Tugas Terjadwal

Mendapatkan detail tugas terjadwal dengan schedule_id milik pengguna saat ini {schedule_id}

URL Request API

GET v4/schedules/{schedule_id}

Contoh Permintaan

Request Header

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

Tampilkan blok kode ini di jendela mengambang

Contoh Respons

Return Sukses

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

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

Tampilkan blok kode ini di jendela mengambang

Data Return

[{ "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512", "name": "contoh tugas terjadwal", "enabled": true, "trigger": {...}, "push": {...} }]

              
              [{
    "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
    "name": "contoh tugas terjadwal",
    "enabled": true,
    "trigger": {...},
    "push": {...}
}]

Tampilkan blok kode ini di jendela mengambang

Jika schedule_id tidak ada, maka return 404.

Mendapatkan Semua ID Pesan dari Tugas Terjadwal

Mendapatkan semua id pesan dari tugas terjadwal pengguna saat ini dengan id {schedule_id}

URL Request API

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

Contoh Permintaan

Request Header

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

Tampilkan blok kode ini di jendela mengambang

Contoh Respons

Respons Sukses

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

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

Tampilkan blok kode ini di jendela mengambang

Data Respons

Format data return diperbarui setelah fitur tugas terjadwal berulang online pada 22 Februari 2024, menambahkan data MsgIds untuk menggantikan msgids lama. Pastikan kode Anda kompatibel.
Field ts menunjukkan timestamp saat tugas terjadwal berhasil dijalankan, akurat hingga milidetik.

{ "count": 1, "MsgIds": [ "{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}", "{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Tidak dapat menemukan target pengiriman\"},\"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\":\"Tidak dapat menemukan target pengiriman\"},\"needRetry\":false,\"ts\":1707278411611}"
    ]
}

Tampilkan blok kode ini di jendela mengambang

Memperbarui Tugas Terjadwal

Memperbarui tugas terjadwal dengan id tertentu

URL Request API

PUT v4/schedules/{schedule_id}

Contoh Permintaan

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

Tampilkan blok kode ini di jendela mengambang

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

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

Tampilkan blok kode ini di jendela mengambang

Tidak dapat memperbarui tugas terjadwal yang sudah kedaluwarsa
Tugas terjadwal berdasarkan zona waktu terminal dan zona waktu utama tidak dapat diperbarui satu sama lain.
Dapat memperbarui satu atau beberapa field dalam array ["name", "enabled", "trigger", "push"]. Body update tidak bisa sebagian, harus seluruh body.

{ "name":"contoh tugas terjadwal", "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": "selamat datang di engagelab", "title": "selamat datang di engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push untuk Anda" } } }

              
              {
    "name":"contoh tugas terjadwal",
    "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": "selamat datang di engagelab",
                    "title": "selamat datang di engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push untuk Anda"
    }
    }
}

Tampilkan blok kode ini di jendela mengambang

Contoh update salah dan benar：

## Salah: hanya update alert di field push： { "push": { "alert": "tugas terjadwal web" } } ## Benar: update alert di field push： { "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"tugas terjadwal web", "notification":{ "web": { "alert": "selamat datang di engagelab", "title": "selamat datang di engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push untuk Anda" } } }

              
              ## Salah: hanya update alert di field push：
{
    "push": {
        "alert": "tugas terjadwal web"
    }
}
## Benar: update alert di field push：
{
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"tugas terjadwal web",
            "notification":{
                "web": {
                    "alert": "selamat datang di engagelab",
                    "title": "selamat datang di engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push untuk Anda"
    }
    }
}

Tampilkan blok kode ini di jendela mengambang

field push harus valid, jika tidak update akan gagal

Contoh Respons

Return Sukses

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

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

Tampilkan blok kode ini di jendela mengambang

{ "name":"Contoh push terjadwal", "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": "selamat datang di engagelab", "title": "selamat datang di engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push untuk Anda" } } }

              
              {
    "name":"Contoh push terjadwal",
    "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": "selamat datang di engagelab",
                    "title": "selamat datang di engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push untuk Anda"
    }
    }
}

Tampilkan blok kode ini di jendela mengambang

Return Error

schedule_id tidak valid

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

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

Tampilkan blok kode ini di jendela mengambang

Operasi update tidak sah

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

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

Tampilkan blok kode ini di jendela mengambang

Menghapus Tugas Terjadwal

URL Request API

DELETE v4/schedules/{schedule_id}

schedule_id adalah id dari tugas terjadwal yang ada. Jika schedule_id tidak valid, hasilnya error 404.

contoh permintaan

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

Tampilkan blok kode ini di jendela mengambang

contoh respons

Return Sukses

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

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

Tampilkan blok kode ini di jendela mengambang

Return Error

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

Tampilkan blok kode ini di jendela mengambang

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

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

Tampilkan blok kode ini di jendela mengambang

Kode Error

Kode	HTTP	Deskripsi	Pesan Error	Penjelasan Detail
28000	200	Return Benar	-	Status sukses
28100	400	Parameter Tidak Valid	Tugas terjadwal tidak valid: bagian tidak valid; sudah habis masa berlaku; kedaluwarsa; data permintaan bukan JSON; update target tugas; hapus target tugas; permintaan schedule tidak ada	Parameter ilegal atau tidak valid. Push melebihi batas (misal, push broadcast melebihi batas, tugas terjadwal melebihi batas, tugas rate-limit melebihi batas). Body parameter terlalu panjang.
28101	401	Autentikasi Gagal	Autentikasi Basic gagal.	appkey dan masterSecret tidak cocok.
28102	400	Parameter Push Tidak Valid	push param kosong atau tidak valid	Parameter push tidak valid, detail error dikembalikan.
28103	400	Parameter Waktu Push Tidak Valid	format waktu single atau trigger salah	Parameter waktu push tidak valid, detail error dikembalikan.
28104	404	Tugas Terjadwal Tidak Ada	Operasi schedule yang diminta tidak ada	Tugas sudah dikirim, atau schedule ID salah.
28105	404	Tidak Ada Target Push	Tugas push tidak valid. Tidak ada target push untuk waktu yang dijadwalkan	Parameter waktu push salah.
28200	500	Internal Server Error	Kesalahan Internal Server.	Terjadi error tak terduga.
28203	503	Internal Server Error, Coba Lagi Nanti	Timeout eksekusi aksi, coba lagi nanti	Error komunikasi dengan schedule-server.