> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/user/id/guide/account/iot-logic/nodes/data-source-node.md).
# Sumber Data
## Ikhtisar teknis dan kemampuan
{% columns %}
{% column %}
**Sumber Data** node adalah titik masuk untuk data telemetri dari perangkat IoT dan platform OEM dalam sistem IoT Logic. Node ini berfungsi sebagai penerjemah universal, menerima data melalui protokol TCP/UDP/HTTP pada antarmuka jaringan dan melalui antrean MQTT, lalu mendekode aliran data masuk sesuai protokol yang dipilih. Node ini mengubah pesan perangkat menjadi format standar yang dapat diproses lebih lanjut dalam aliran Anda.
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
Selain menerima telemetri, sebuah **Sumber Data** node juga dapat memperkaya perangkat yang sudah Anda tambahkan ke dalamnya. Sistem eksternal, seperti platform telematika terpisah yang secara default tidak mengirim data ke Navixy, mendorong atribut tambahan ke aliran perangkat. Terkadang platform eksternal itu adalah milik produsen perangkat itu sendiri. Alih-alih memigrasikan perangkat ke ingest bawaan Navixy, the **Software** tab mempertahankannya tetap terdaftar apa adanya. Tab ini terus memperkaya aliran perangkat dengan data dari platform lain itu, sehingga kedua aliran berjalan paralel. Lihat [Bagaimana data yang didorong ditangani](#how-pushed-data-is-handled) untuk mekanismenya, dan [Opsi konfigurasi](#configuration-options) untuk menyiapkannya.
### Integrasi arsitektur aliran
**node Sumber Data** berfungsi sebagai titik masuk data dalam aliran IoT Logic. Satu aliran dapat berisi beberapa node sumber, masing-masing dengan konfigurasi independen. Arsitektur ini memungkinkan:
* Akuisisi data awal dari berbagai jenis perangkat dan format protokol
* Transformasi data terstandar dari berbagai produsen ke format terpadu
* Jalur pemrosesan paralel dengan menghubungkan satu sumber data ke beberapa node hilir
* Penyaringan perangkat selektif untuk hanya menyertakan sumber data yang relevan dalam aliran Anda
* Pengayaan aliran untuk perangkat yang sudah terhubung, menggunakan atribut yang didorong dari sistem eksternal melalui HTTP
### Kemampuan node
Laporan **node Sumber Data** sendiri menawarkan:
* **Keberagaman protokol**: Mendukung berbagai produsen perangkat, termasuk Teltonika, Queclink, Suntech, Jimi, dan lainnya, melalui parser dan dekoder Navixy bawaan
* **Fleksibilitas transport**: Mendukung protokol TCP, UDP, HTTP, dan koneksi broker MQTT
* **Transformasi data terpadu**: Mengonversi pesan spesifik perangkat ke format standar untuk pemrosesan yang konsisten
* **Penyaringan perangkat**: Menyediakan kemampuan penyaringan untuk memilih model atau protokol tertentu
* **Pemrosesan real-time**: Menangani aliran data telemetri masuk secara real-time untuk pemrosesan segera
* **Pengayaan push HTTP**: Menggabungkan atribut yang didorong dari sistem eksternal ke dalam aliran perangkat yang sudah dipilih pada node ini. HTTP adalah satu-satunya jenis push yang didukung saat ini, dengan arsitektur yang dirancang untuk lebih banyak di masa mendatang
## Opsi konfigurasi
{% columns %}
{% column width="58.333333333333336%" valign="middle" %}
Mengonfigurasi sebuah **Sumber Data** node menentukan perangkat mana yang mengirim data ke aliran Anda dan, secara opsional, bagaimana sistem eksternal dapat memperkaya perangkat tersebut dengan data yang didorong.
Dialog konfigurasi disusun dalam dua tab:
* **Perangkat**: memilih perangkat mana yang mengirim telemetri ke aliran. Diperlukan, dan bekerja persis seperti sebelumnya.
* **Software**: mengonfigurasi pengayaan push HTTP untuk perangkat yang Anda pilih di tab Devices. Opsional, dan bergantung pada pilihan itu.
{% endcolumn %}
{% column width="41.666666666666664%" %}
{% endcolumn %}
{% endcolumns %}
{% hint style="info" %}
Laporan **Software** tab bergantung pada **Perangkat** tab. Pemilihnya **Perangkat sumber** hanya mencantumkan perangkat yang sudah dipilih di **Perangkat**, dan tidak menampilkan data yang tersedia hingga Anda memilih setidaknya satu di sana.
{% endhint %}
Mari lihat elemen apa saja yang digunakan node ini dan apa yang dapat Anda konfigurasi saat menggunakannya:
### Langkah konfigurasi
{% stepper %}
{% step %}
#### Tentukan nama node
Masukkan nama deskriptif untuk sumber data ini:
* Gunakan nama yang membantu Anda mengidentifikasi produsen, model, atau informasi relevan lainnya.
* Nama ini akan ditampilkan dalam diagram aliran agar mudah diidentifikasi.
{% endstep %}
{% step %}
#### Pilih sumber
Dari daftar yang telah difilter, pilih perangkat yang akan disertakan. Hanya perangkat yang terdaftar di akun pengguna Navixy Anda yang tersedia untuk dipilih. Pilihan ini juga merupakan prasyarat untuk **Software** tab opsional, yang hanya dapat memetakan perangkat yang dipilih di sini.
{% endstep %}
{% step %}
#### Simpan konfigurasi node
Klik **Terapkan perubahan** untuk menyelesaikan pembuatan node.
{% endstep %}
{% step %}
#### Konfigurasikan pengayaan push HTTP (opsional)
Beralih ke **Software** tab untuk memperkaya perangkat yang Anda pilih di Devices dengan data yang didorong dari sistem eksternal. Langkah ini opsional. Lihat [Mengonfigurasi pengayaan push HTTP](#configuring-http-push-enrichment) untuk pengaturan lengkap.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
Jika Anda mengubah pengaturan produsen atau model setelah memilih perangkat, Navixy akan memberi tahu Anda jika ada perangkat yang dipilih yang tidak cocok dengan parameter baru, tetapi tidak secara otomatis menghapusnya dari pilihan Anda.
{% endhint %}
### Mengonfigurasi pengayaan push HTTP
Pengayaan push HTTP memungkinkan sistem eksternal menambahkan atribut ke perangkat yang sudah dipilih di tab **Perangkat** node ini, dengan mendorong data ke URL yang dihasilkan. Fitur ini opsional, dan memerlukan setidaknya satu perangkat yang dipilih di bawah [Langkah konfigurasi](#configuration-steps) terlebih dahulu.
Ini berguna ketika sebuah perangkat sudah melaporkan ke sistem terpisah yang secara default tidak mengalirkan data ke Navixy, misalnya platform manajemen baterai yang melacak SoC kendaraan yang sama. Alih-alih memigrasikan perangkat ke ingest bawaan Navixy, Anda dapat membiarkannya tetap terdaftar apa adanya dan membiarkan platform lain itu mendorong pembacaannya ke sini. Sebuah push dengan `vehicle_id: "truck_12"`, `bms_battery_soc: 76`, dan `bms_battery_temp: 34,2` menambahkan `bms_battery_soc` dan `bms_battery_temp` sebagai atribut baru pada perangkat yang dipetakan, bersama telemetri GPS bawaannya.
{% stepper %}
{% step %}
#### Atur tipe konektor
Beralih ke **Software** tab dan atur **Tipe konektor** ke **HTTP**, saat ini satu-satunya opsi.
{% endstep %}
{% step %}
#### Simpan aliran dan salin URL yang dihasilkan
Simpan seluruh aliran, bukan hanya node ini. Kolom **URL** ini hanya menghasilkan nilai setelah aliran disimpan dengan **Tipe konektor** ditetapkan. Sampai saat itu, kolom ini menampilkan placeholder yang meminta Anda menyimpan aliran. Setelah URL muncul, klik ikon salin di sebelahnya, yang dinonaktifkan hanya saat kolom kosong.
{% endstep %}
{% step %}
#### Autentikasi sistem eksternal
Berikan sistem eksternal sebuah kunci API Navixy yang valid [Navixy API key](/docs/user/id/guide/account/api-keys.md), dan konfigurasikan sistem tersebut untuk mengirim `Authorization: NVX ` dengan setiap permintaan push, beserta URL. Push tanpa header ini gagal, jadi URL dan header sama-sama diperlukan sebelum data dapat diterima.
{% endstep %}
{% step %}
#### Tentukan kunci utama dan pemetaan
Masukkan sebuah **Kunci utama**: nama bidang yang digunakan sistem eksternal untuk mengidentifikasi perangkat mana yang menjadi milik catatan yang dikirim. Bidang ini menerima maksimal 64 karakter, hanya huruf, digit, dan garis bawah.
Tambahkan satu **Pemetaan** baris per perangkat yang akan diperkaya. Untuk setiap baris, pilih **Perangkat sumber**, terbatas pada perangkat yang sudah dipilih di Devices, lalu masukkan **Nilai kunci** yang mengidentifikasi perangkat tersebut dalam push masuk. Bidang ini menyimpan hingga 255 karakter, tetapi endpoint push itu sendiri hanya menerima hingga 100 karakter per bidang, jadi dalam praktiknya sebaiknya nilai dijaga jauh di bawah 100 karakter.
{% hint style="warning" %}
Baik Kunci utama maupun Nilai kunci hanya menerima huruf, digit, dan garis bawah, tanpa tanda hubung atau tanda baca lainnya. Validasi bidang umum pada endpoint push lebih permisif dan menerima tanda hubung di bidang mana pun tanpa peringatan, tetapi nilai yang mengandung tanda hubung tidak akan pernah cocok dengan Nilai kunci yang tersimpan, sehingga push yang menggunakannya akan dibuang secara diam-diam, sama seperti jika nilainya tidak cocok. Jika pengenal sistem eksternal Anda menggunakan tanda hubung (misalnya `truck-12`), terjemahkan menjadi, misalnya menjadi `truck_12`, sebelum mendorongnya.
{% endhint %}
{% endstep %}
{% step %}
#### Terapkan dan simpan
Klik **Terapkan perubahan**, lalu simpan aliran lagi jika Anda mengonfigurasi tab Software setelah penyimpanan awal.
{% endstep %}
{% endstepper %}
### Rincian pemrosesan data
**node Sumber Data** mewarisi semua parser dan decoder dari Navixy, sehingga menyediakan kompatibilitas dengan berbagai perangkat IoT. Saat data tiba di node ini, data tersebut melalui proses berikut:
1. Aliran data yang masuk diterima melalui protokol transport yang ditentukan
2. Data diteruskan ke decoder protokol yang sesuai berdasarkan konfigurasi Anda
3. Pesan perangkat diubah menjadi format terstandar yang dapat diproses oleh IoT Logic
4. Data terpadu diteruskan ke node berikutnya dalam aliran Anda
Proses standardisasi ini memungkinkan Anda membangun alur pemrosesan yang konsisten terlepas dari format data asli dari berbagai produsen perangkat.
### Bagaimana data yang didorong ditangani
Navixy mencocokkan setiap push masuk berdasarkan nilai primary key-nya dengan yang dikonfigurasi pada node **Pemetaan**, lalu menggabungkan field yang tersisa ke aliran data perangkat yang dipetakan sebagai atribut: baru jika nama field tersebut baru, atau ditulis ke riwayat atribut yang sudah ada jika namanya cocok dengan yang sudah ada, baik dilaporkan secara bawaan oleh perangkat maupun dikirim oleh konektor aliran lain. Hal tersebut tidak memengaruhi lokasi atau telemetri lainnya. Field yang disebut dalam **Kunci utama**, beserta `aliran_id` dan `node_id`, digunakan untuk routing dan tidak pernah menjadi atribut itu sendiri. Sebuah permintaan dapat berakhir dalam salah satu dari tiga status:
| Hasil | Respons HTTP | Data digabungkan? |
| ------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nilai kunci utama cocok dengan pemetaan | 200, `success: true` | Ya. Field yang tersisa digabungkan sebagai atribut, baru jika namanya baru, riwayat yang sudah ada jika cocok dengan salah satu yang sudah digunakan |
| Nilai kunci utama tidak cocok dengan pemetaan mana pun | 200, `success: true` | Tidak. Dibuang tanpa pemberitahuan |
| Hilang atau tidak valid `Authorization` header | kesalahan 400 | Tidak. Ditolak sebelum Navixy memeriksa kunci utama |
{% hint style="info" %}
Respons 200 hanya mengonfirmasi bahwa Navixy menerima permintaan, bukan bahwa data digabungkan. Nilai kunci utama yang tidak cocok dibuang tanpa pemberitahuan, tanpa error untuk menandakannya. Jika Anda tidak yakin sebuah push dicocokkan, periksa atribut perangkat yang dipetakan di [Penganalisis Data](/docs/user/id/guide/account/iot-logic/data-stream-analyzer.md) daripada mengandalkan respons.
{% endhint %}
{% hint style="warning" %}
Nama field yang dipush berbagi satu ruang nama dengan atribut bawaan perangkat itu sendiri, dan dengan nama yang dipush oleh konektor aliran lain yang memperkaya perangkat yang sama. Jika nama tersebut cocok dengan nama yang sudah digunakan, baik yang bawaan perangkat maupun yang dipush oleh aliran lain, push akan menimpa riwayat atribut yang sudah ada alih-alih membuat yang terpisah.
Sensor, laporan, dan aturan peringatan membaca nilai gabungan sebagai pembacaan nyata, sehingga nama yang bertabrakan dapat menghasilkan data palsu di hilir. Misalnya, field yang dipush bernama `level_bahan_bakar` yang cocok dengan atribut bahan bakar bawaan perangkat akan menyuntikkan pembacaan palsu, sehingga menghasilkan peristiwa penurunan bahan bakar atau pengisian bahan bakar palsu dalam laporan.
Untuk menghindarinya, awali nama field yang dipush sehingga tidak dapat bertabrakan dengan atribut bawaan perangkat atau nama yang dipush oleh aliran lain, misalnya `bms_battery_soc` daripada `battery_soc`.
Field pesan sistem seperti `kecepatan`, `latitude`, `longitude`, `heading`, `satelit`, dan `hdop` tidak dapat ditimpa dengan cara ini. Push hanya pernah membuat atau memperbarui atribut, bukan telemetri tingkat pesan. Field yang dipush menggunakan salah satu nama itu tetap muncul dengan nama tersebut di [Penganalisis Data](/docs/user/id/guide/account/iot-logic/data-stream-analyzer.md), terpisah dari telemetri nyata perangkat.
{% endhint %}
Atribut yang digabungkan muncul sebagai entri pada satu titik waktu dalam riwayat atribut perangkat, bukan nilai saat ini yang melekat. Jika perangkat melaporkan telemetrinya sendiri jauh lebih sering daripada sistem eksternal mengirim pembaruan, paket perangkat sendiri dapat memajukan riwayat atribut melewati nilai yang dipush dalam hitungan detik, meskipun penggabungan berhasil.
{% hint style="info" %}
Ini adalah konsekuensi yang diharapkan dari dua aliran data yang berjalan pada kecepatan berbeda, bukan cacat. Rujuk atribut di hilir sebagai `value('attribute_name', 0, 'valid')` alih-alih namanya saja. `'valid'` menelusuri kembali riwayat atribut hingga pembacaan non-null terakhir, sehingga node hilir mendapatkan nilai yang dipush tanpa memandang waktunya.
{% endhint %}
Endpoint push menerima hingga 1 permintaan per detik untuk setiap kunci API, dengan ukuran burst 1. Atur laju permintaan sistem eksternal sesuai itu.
## Pertanyaan yang sering diajukan
#### Bisakah saya menggunakan beberapa node Sumber Data dalam satu aliran?
Ya, Anda dapat menggunakan beberapa **node Sumber Data** dalam satu ruang kerja. Ini berguna ketika Anda perlu memproses data dari berbagai jenis perangkat dengan cara yang berbeda atau ingin menggabungkan beberapa aliran data setelah transformasi tertentu.
#### Apa yang terjadi jika perangkat sudah digunakan di aliran lain?
Sebuah perangkat dapat menjadi bagian dari beberapa aliran sekaligus. Jika Anda menambahkan perangkat yang sudah digunakan di aliran lain, kedua aliran memproses datanya secara bersamaan dan hasilnya digabungkan untuk menghindari kehilangan data. Menjadi bagian dari aliran lain bukanlah batasan. Namun, jika konektor dari dua aliran mendorong nama atribut yang sama ke perangkat itu, keduanya tidak bergabung tanpa konsekuensi. Riwayat satu push menimpa riwayat yang lain. Lihat [Bagaimana data yang didorong ditangani](#how-pushed-data-is-handled) untuk menghindari nama yang bertabrakan.
#### Apakah semua perangkat Navixy saya otomatis tersedia di IoT Logic?
Ya, semua perangkat dari akun pengguna Navixy Anda dapat digunakan dalam pemrosesan IoT Logic. Ini mencakup perangkat GPS, platform OEM, perangkat dan gateway MQTT, serta konektor MQTT/Kafka. Perangkat yang sudah dipilih di sebuah **Sumber Data** node juga dapat diperkaya dengan atribut yang dipush dari sistem eksternal melalui HTTP, melalui node-nya **Software** tab.
#### Bagaimana saya tahu produsen mana yang harus dipilih untuk perangkat saya?
Protokol harus sesuai dengan protokol komunikasi yang digunakan oleh produsen perangkat Anda. Sebagian besar perangkat menggunakan protokol yang terkait dengan produsennya (misalnya, perangkat Teltonika menggunakan protokol Teltonika). Periksa dokumentasi perangkat Anda atau hubungi penyedia perangkat Anda jika Anda tidak yakin.
#### Bisakah saya menghubungkan node Sumber Data ke beberapa node hilir?
Ya, Anda dapat menghubungkan sebuah **node Sumber Data** ke beberapa node pemrosesan untuk membuat jalur pemrosesan paralel. Ini memungkinkan Anda menerapkan transformasi yang berbeda pada aliran data yang sama. Berikut contohnya:
#### Bisakah saya memasukkan data dari sistem yang bukan perangkat Navixy?
Ya, melalui **Software** tab, tetapi hanya untuk memperkaya perangkat yang sudah Anda tambahkan di **Perangkat** tab. Ini bukan cara untuk membuat aliran tanpa perangkat di dalamnya.
#### Sistem yang saya gunakan untuk push melaporkan lebih jarang daripada perangkat saya, apakah data yang dipush akan hilang?
Tidak, tetapi atribut yang dipush dapat cepat berhenti menjadi nilai saat ini jika perangkat melaporkan jauh lebih sering, karena kedua sumber berbagi riwayat bergulir yang sama. Rujuk atribut di hilir sebagai `value('attribute_name', 0, 'valid')` alih-alih nama dasarnya, untuk mendapatkan pembacaan nyata terakhir secara andal terlepas dari waktunya. Ini adalah konsekuensi yang diharapkan dari dua aliran yang berjalan dengan kecepatan berbeda, bukan cacat.
#### Saya mengirim data, tetapi tidak muncul. Apa yang salah?
Periksa ini secara berurutan:
1. Pastikan permintaan menyertakan header yang valid `Authorization: NVX ` Header yang hilang atau tidak valid akan gagal dengan jelas dengan kesalahan HTTP 400.
2. Pastikan nama field yang dikirim cocok dengan **Kunci utama** pengaturan node secara tepat, dan nilainya cocok dengan salah satu **Pemetaan** Key yang dikonfigurasi, hanya huruf, digit, dan garis bawah. Nilai dengan tanda hubung adalah penyebab paling umum: nilai itu lolos validasi endpoint push sendiri tanpa error, tetapi tidak akan pernah cocok dengan nilai Key yang tersimpan, sehingga permintaan tetap mengembalikan sukses sementara tidak ada yang digabungkan.
3. Periksa riwayat atribut di Penganalisis Data, bukan hanya nilai saat ini. Perangkat yang melaporkan telemetry-nya sendiri sering kali dapat menggeser nilai gabungan keluar dari slot saat ini dalam hitungan detik, meskipun penggabungan berhasil.
#### Saya mengirim sebuah field dan pembacaan perangkat itu sendiri tampak salah
Nama field yang dikirim kemungkinan cocok dengan atribut bawaan yang sudah dilaporkan perangkat, atau yang dikirim oleh konektor aliran lain, dan menimpa riwayatnya alih-alih membuat atribut terpisah. Ganti nama field yang dikirim dengan prefiks yang berbeda, lalu periksa riwayat atribut di [Penganalisis Data](/docs/user/id/guide/account/iot-logic/data-stream-analyzer.md) untuk memastikan nilai yang dikirim dan nilai bawaan tidak lagi tercampur.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://navixy.com/docs/user/id/guide/account/iot-logic/nodes/data-source-node.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.