Export data from bot applications, Absensi karyawan
Ini adalah dokumentasi bagaimana carannya melakukan export data dari program bot telegram yang di hosting oleh Netzku. Sebelum melanjutkan, perlu di pahami terlebih dahulu. Netzku menghosting bot telegram berdasarkan core mereka tersendiri, core bot adalah bagian inti untuk memproses dan mengelolah data yang di berikan oleh telegram.
Core inti selalu di perbaruhi dan di sesuaikan terhadap bugs, dan pembaruhan layanan telegram. Saat ini telegram tengah gencar sekali melakukan update pada layanan mereka, dan secara tidak langsung mempengaruhi bagaimana model bot dapat berkomunikasi dengan telegram. Panel netzku memang terbatas untuk pengelolaan data lanjutan, tapi anda bisa mengembangkan app sendiri untuk mengelolah data tersebut.
Jika pemilik sudah mempunyai aplikasi dashboard pengelolah data mandiri yang lebih kompleks lagi dari dashboard yang di tawarkan, maka bisa saling bertukar data dengan Netzku melalui Rest API. Netzku terbuka untuk berbagai API pihak ketiga termasuk cms management sendiri yang di kelolah oleh author/pemilik bot. Berikut ini adalah bagaimana API dapat di jalankan.
Memahami Rest API Netzku
Netzku punya struktur rest api yang tetap, dan masing-masing bot telegram yang di hosted oleh netzku dapat menggunakan endpoint api yang sama. Setiap bot hanya di pisahkan oleh UUID ( Universal Unique Identifier ). String ini bersifat acak untuk setiap bot, dan mengacuh pada di mana data bot di simpan di dbms netzku.
URL endpoin yang dapat di akses adalah domain.com/api/telegram/{UUID}. Data output yang di hasilkan dalam bentuk Application/Json, setiap api yang mengarah ke endpoin tersebut harus menetapkan nilai parameter actions, untuk bot absensi nilai ini dapat di isi dengan kata getData.
parameter dalam actions adalah case sensitive, yang artinya antara huruf besar berbeda dengan huruf kecil. Misalnya, getdata akan berbeda dengan getData. Perhatikan dengan baik, jangan sampai salah dalam mengarahkan endpoint dan actions. Nilai actions ini akan merujuk ke program mana target akan di proses.
| domain.com | https://netzku.com |
POST JSON yang di butuhkan untuk fetch data
Dalam permintaan ke API netzku anda membutuhkan authentikasi berjenis API KEY, api key ini tidak terlalu banyak mekanisme enkripsi nya. Parameter ini harus di sertakan dalam permintaan JSON INPUT, dengan field bernama api_key. Nilai pada string ini adalah karakter enkripsi hash dari hasil kode API key yang sudah anda buat di menu dashboard.
Parameter api_key penting di sertakan dalam setiap permintaan API, selain itu terdapat parameter lain yang juga dapat digunakan untuk mengontrol dan memfilter data yang akan di tampilkan. Setiap permintaan api mempunyai limit data terbatas, dalam API bot absensi kali ini satu kali permintaan API hanya dapat menghasilkan maksimal 2000 baris data.
Berikut ini ada beberapa parameter yang opsional untuk di sertkaan dalam setiap permintaan. Semua parameter berikut harus di kirim dalam bentuk JSON INPUT data, bukan GET, POST, dan PUT.
| api_key | Hash md5 dari API key anda ( wajib ) |
| per_page | Hasil per halaman, intiger 1 - 2000 ( Opsional ) |
| halaman | Angka untuk page selanjutnya, intiger ( Opsional ) |
| short_by | Penyortiran, nilai newest atau oldest ( Opsional ) |
Contoh penggunaan dan pengaplikasian dengan PHP
Anda dapat menggunakan bahasa pemroraman apapun untuk mengaplikasikan program, javascript, python, nodejs, PHP, GoLang, Rust dan sebagainya. Berikut ini adalah salah satu contoh, bagaimana cara mengaplikasikan data sesuai dengan prinsip yang sudah di jelaskan sebelumnya.
// URL API yang akan diakses
$url = 'http://host-domain.com/api/telegram/{UUID}?actions=getData';
// Data yang akan dikirimkan dalam format JSON
$data = array(
'api_key' => md5("YOUR API KEY"),
'per_page' => 2,
'halaman' => 1
);
// Mengubah data menjadi format JSON
$postData = json_encode($data);
// Pengaturan header HTTP
$headers = array(
'Content-Type: application/json',
'Content-Length: ' . strlen($postData)
);
// Inisialisasi cURL
$ch = curl_init();
// Pengaturan cURL
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Eksekusi cURL
$response = curl_exec($ch);
// Menangani kesalahan jika terjadi
if(curl_errno($ch)){
echo 'Error: ' . curl_error($ch);
}
// Menutup koneksi cURL
curl_close($ch);
// Menampilkan hasil respons dari API
echo $response;Hasil Output Sample :
{
"sukses": true,
"sucess_in": "0.02 detik.",
"data": [
{
"nama": "Tips Shoping",
"kegiatan": "EAT",
"waktu_mulai": "2024-03-31 14:30:06",
"waktu_akhir": "2024-03-31 14:31:17",
"durasi": "1 menit, 11 detik",
"bot_user": "SampelDoangBot",
"uid": "92154"
},
{
"nama": "Tips Shoping",
"kegiatan": "MASUK\/PULANG KERJA",
"waktu_mulai": "2024-03-31 14:30:00",
"waktu_akhir": "2024-03-31 14:31:45",
"durasi": "1 menit, 45 detik",
"bot_user": "SampelDoangBot",
"uid": "92153"
}
],
"per_request": 2,
"page_tersisa": 24,
"sekarang": 1,
"selanjutnya": 2
}
Tips mengelolah data hasil pencatatan
Buat program pada aplikasi anda untuk mengambil data misalnya untuk mengambil data setiap hari, jadwalkan menggunakan program cron job, simpan hasil ke dalam database. Saat melakukan fetch data ke API, perhatikan bahwa nilai hasil per_page hanya dapat di set dari angka 1 hingga 2000, artinya hanya bisa mendapatkan maksimal 2000 data.
Apabila data yang tersisa masih banyak, anda bisa memeriksa nilai pada kunci page_tersisa. Kunci ini menghasilkan jumlah halaman tersisa yang dapat di fetch ulang untuk mengambil data selanjutnya. Untuk mengatur agar API mengembalikan data selanjutnya, tambahkan parameter halaman dengan di isi angka yang di kembalikna pada kunci selanjutnya.
Nama yang di kembalikan oleh API bersifat dinamis, yang artinya nama tersebut akan sesuai dengan nama saat ini yang di gunakan oleh pengguna telegram. Apabila aplikasi anda menggunakan nama ini sebagai identifikasi pengguna, maka tidak di sarakan untuk melakukan edit terhadap nama-nama yang muncul di aplikasi anda.
Error handling, berikut ini adalah respon error apabila terdapat kesalahan pada input parameter, keterangan dapat membantu anda memperbaiki kesalahan.
| Code error 100 | Kesalahan terhadap penempatan parameter per_page |
| Code error 101 | Anda lupa menempatkan dan mengisi parameter api_key |
| code error 102 | Kode api_key berubah atau tidak valid ( lihat documentasi ) |
| code error 103 | Tidak ada hasil yang dapat di tampilkan dari permintaan |
| code error 104 | Internal error pada bot anda, bisa jadi karena server mati/crash |
Cara mendapatkan UUID unik dari bot anda
Implementasi UUID di terapkan di berbagai bot telegram yang di hosted oleh netzku. UUID bukan merupakan kunci rahasia, tapi merupakan identifikasi unik mengenai lokasi database bot di simpan. Kunci ini dapat di lihat oleh siapa saja yang dapat mengakses dashboard dan account netzku anda.
Untuk menemukan UUID, sikakan buka dashboard halaman netzku. Login menggunakan akun anda yang sudah terdaftar dan memiliki bot telegram di dalamnya. Kemudian, pilih salah satu program bot telegram yang ingin di lihat datanya. Saat melakukan hal tersebut perhatikan pada parameter URL addressbar.
Pada halaman cloudpanel akan terlihat UUID pada URL yang menandakan itu adalah identifikasi unik untuk setiap program akun bot telegram yang terpasang dan di hosted oleh netzku.
Menggunakan mekanisme Otomatis
Pendekatan ini akan menggunakan runtime yang di jalankan oleh Netzku, tanpa perlu membuat cron job ataupun worker lain untuk mengeksekusi tugas berkala. Server netzku mendukung pengiriman data terjadwal, dengan data yang di kirim sama seperti sebelumnya. Tapi pada mekanisme ini data yang di export akan mendukung maksimal sampai dengan 5000 rows.
Untuk format data bisa di lihat pada string teks json sebelumnya. Untuk melakukan setup fitur ini, bisa langsung saja tambahkan URL API endpoint target server anda di bagian dashboard netzku. Matikan semua fitur export ke gdrive, caranya hapus kode SheetID, aktifkan fitur export 5000 baris terakhir, tambahkan URL api endpoint.
Pada saat menyimpan, jika fitur export 5000 baris terakhir di aktifkan, server netzku akan mengirimkan data sebanyak jumlah saat ini. Di sarankan untuk menunda, dan tidak melakukan centang pada fitur ini, karena server anda akan menerima doble data. Sebaiknya gunakan fitur bawaan, yaitu netzku akan mengirimkan hasil rekapan setiap jam 00:00 malam.
Pastikan server anda dapat di hubungi, dan memberikan respon header 200 Ok. Apabila saat pengiriman, server merespon dengan code respon lain selain dari itu, maka server netzku akan terus mencoba pengiriman data secara berkala. Umumnya pengulangan pengiriman data setiap kelipatan 5 menit, seiring waktu akan bertamba 5 menit sampai server anda merespon dengan kode 200 Ok.
Silakan di aplikasikan sendiri untuk datanya ke halaman cms ( content management system ) versi aplikasi anda sendiri. Semua data yang tersimpan oleh netzku dapat di akses menggunakan URL tersebut, dan data lama yang dapat di akses adalah maksimal 1 tahun terakhir. Dengan mengintegrasikan layanan Netzku ke cms management anda, anda bisa mengelolah dengan sendiri data tersebut.
Netzku menghost bot telegram untuk memastikan program selalu berjalan, dan sesuai dengan layanan telegram versi terbaru. Tanpa perlu repot untuk memperbaruhi mekanisme apabila telegram melakukan update. Namun data yang anda terima dari netzku format nya tetap sama.