Sumber data dan kunci akses
Ambil katalog dari layanan lain atau kirim pesanan ke sana: simpan alamat layanan, kunci akses, lalu gunakan dalam reaksi.
Di halaman ini
Jika daftar produk ada di situs Anda, bot dapat mengambilnya dari sana. Setelah pelanggan memesan, bot juga dapat mengirim data pesanan kembali. Layanan tersebut perlu memiliki API, yaitu cara program bertukar data.
Di bagian Sumber, simpan sambungan ke layanan sebagai konektor. Konektor berisi alamat API dan pengaturan permintaan. Di bagian Kunci, simpan data akses. Dalam reaksi, pilih konektor melalui tindakan Permintaan ke sumber atau Tulis ke sumber. Untuk layanan yang sudah memiliki pengaturan siap pakai, periksa Integrasi terlebih dahulu.
Konektor di bagian Sumber
Buka Sumber → Konektor. Konektor memiliki Nama, Jenis, URL dasar, data akses yang digunakan, dan header tambahan.
| Jenis | Kegunaan | Yang perlu diketahui |
|---|---|---|
| REST | API HTTP/JSON apa pun. | Isi alamat dan data akses layanan. |
| OzmaDB | Basis data OzmaDB/FunDB Anda. | Isi alamat utama REST API. Membaca tampilan (view) anonim lebih mudah diatur. |
| IMAP | Koneksi lama. | Koneksi IMAP baru tidak dapat dibuat. Koneksi lama tetap muncul dengan tanda tidak didukung dan dapat dihapus. |
Tombol Periksa mengirim permintaan uji dan menampilkan status serta waktu respons atau kesalahannya. Gunakan untuk memeriksa alamat dan kunci.
Data akses di bagian Kunci
Buka Kunci → Data akses. Pilih cara masuk sesuai petunjuk layanan tujuan. Kunci disimpan dalam bentuk terenkripsi.
| Cara mengakses | Data yang diperlukan |
|---|---|
| Kunci API | Kunci dan nama header, secara bawaan Authorization. |
| Token Bearer | Token untuk Authorization: Bearer. |
| OAuth2 dengan kata sandi | Token URL, Client ID/Secret, nama pengguna, kata sandi, dan scope. |
| OAuth2 dengan token pembaruan | Token URL, Client ID/Secret, refresh token, dan scope. |
Untuk OAuth2, GetMyBot mengambil token akses sementara dan memperbaruinya saat kedaluwarsa atau ketika layanan membalas 401. Jika layanan memberi refresh token baru, GetMyBot menyimpannya. Saat Anda mengubah data akses, kolom rahasia yang dibiarkan kosong berarti pertahankan nilai lama.
Membaca dan menulis data melalui reaksi
- Permintaan ke sumber (
ds_query) membaca data dan menyimpannya dalam data sementara reaksi (ctx). Isi alamat relatif permintaan, jalur menuju daftar di respons (JSONPath), dan nama hasil. Misalnya, daftarproductsdapat dipakai untuk tombol dinamis atau perulangan daftar. - Tulis ke sumber (
ds_write) mengirim data denganPOST,PUT, atauDELETEdan isi berformat JSON.
Isi permintaan, pengulangan, dan pemeriksaan respons
Untuk POST atau PUT pada Permintaan web dan Tulis ke sumber, Anda dapat menyusun isi sebagai pohon JSON. Setiap nilai memiliki jenis sendiri: teks, angka, benar/salah, JSON, atau null. Variabel tetap dapat dimasukkan tanpa mengubah angka menjadi teks atau menulis tanda kutip khusus untuk objek bersarang. Contoh data pesanan:
{
"customer": { "name": "{{param.name}}", "phone": "{{user.phone}}" },
"amount": 4900,
"paid": false
}
Isi permintaan lama yang ditulis sebagai teks tetap bekerja. Mengganti mode isi tidak menghapus teks yang sudah Anda tulis.
Pengulangan otomatis (retry_count) hanya berlaku untuk gangguan jaringan, 429, dan 5xx. Respons 4xx tidak diulang. GET, HEAD, OPTIONS, PUT, dan DELETE dapat diulang. POST dan PATCH hanya diulang jika Anda sendiri menyertakan header Idempotency-Key, yang berarti API tujuan dapat mengenali dan menolak permintaan ganda. GetMyBot memang mengirim kunci internal untuk setiap langkah, tetapi kunci itu saja tidak mengaktifkan pengulangan POST atau PATCH. Tanpa jaminan dari layanan tujuan, pengulangan bisa membuat dua pesanan. GetMyBot juga tidak mengulang penulisan melalui integrasi atau CRM jika hasilnya tidak jelas. Pengecualian satu-satunya ialah permintaan web dengan Idempotency-Key yang Anda isi.
Pada konektor REST, Periksa respons mengirim satu GET dengan alamat dan parameter tetap, tanpa mengganti variabel. Hasilnya menunjukkan status, jenis data, dan hingga 64 KB isi respons. Pemeriksaan tidak menulis data. Jika respons berupa JSON, Anda dapat menjadikannya contoh untuk Membaca bagian respons.
Membaca bagian respons tersedia pada permintaan web, permintaan dan penulisan ke sumber, AI, Google Sheets, Google Drive, GetCourse, dan tindakan CRM. Pilih Hasil tindakan untuk hasil yang sudah disiapkan GetMyBot, atau Respons lengkap untuk isi asli. Semua aturan diterapkan bersama: jika satu aturan gagal, tidak ada variabel yang disimpan.
Untuk permintaan satu kali tanpa konektor tersimpan, gunakan Permintaan web. Untuk mengambil teks halaman, gunakan Muat URL. Lihat Tindakan.
Tampilan dan tabel OzmaDB dengan nama tetap
Simpan konektor jenis OzmaDB, lalu pilih dalam Permintaan ke sumber atau Tulis ke sumber dan aktifkan mode OzmaDB. Tindakan HTTP yang sudah ada tetap memakai pengaturan lamanya. Saat Anda beralih mode dalam editor, kolom HTTP tetap tersimpan dan pengaturan Ozma dapat dibuka kembali selama editor masih terbuka.
Untuk membaca, isi nama Skema dan Tampilan (view) atau klik Muat katalog. Muat lagi mengambil halaman katalog berikutnya tanpa menghilangkan objek yang sudah dipilih. Muat argumen dan kolom memberi saran dari informasi objek. Isi nama, jenis, dan nilai setiap argumen. Jika Anda tidak memiliki akses membaca katalog, objek dan nilainya dapat dimasukkan secara manual.
Tampilan (view) adalah permintaan tersimpan yang dapat menggabungkan tabel dan menghitung nilai. Gunakan tampilan untuk membaca. Untuk membuat atau mengubah baris, pilih Tabel (entity) secara terpisah.
Contoh membaca usr.people_by_team dengan argumen angka team_id:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"view": "people_by_team",
"args": { "team_id": { "type": "number", "value": "42" } },
"limit": 100,
"offset": 0
},
"save_to_ctx": "people"
}
ctx.people berisi daftar objek menurut nama kolom, misalnya [{"id":7,"name":"Alex"}]. Daftar ini dapat dipakai dalam perulangan dan tindakan berikutnya. Ukuran halaman bawaan 100, maksimum 500, dengan offset dari 0 sampai 100000. Untuk membaca beberapa halaman tanpa melewatkan data, tentukan urutan yang tetap di tampilan.
Pratinjau pembacaan hanya membaca data, paling banyak 20 baris. Argumen harus berisi nilai tetap tanpa variabel dari kejadian. Untuk memeriksa tindakan yang memakai variabel, ganti sementara dengan nilai contoh. Tidak ada pratinjau untuk penulisan.
Untuk menulis, pilih Skema, Tabel (entity), tindakan Buat atau Ubah, lalu tambahkan kolom beserta jenis nilainya. Mengubah baris memerlukan ID baris positif, yang dapat diambil dari tindakan sebelumnya:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"entity": "person",
"operation": "update",
"id": "{{ctx.person_id}}",
"fields": {
"name": { "type": "string", "value": "{{text}}" },
"active": { "type": "boolean", "value": "true" },
"details": { "type": "json", "value": "{\"tags\":[\"member\"]}" },
"note": { "type": "null", "value": "" }
}
},
"save_to_ctx": "saved_person"
}
Jika nama hasil diisi, respons transaksi disimpan, misalnya ID baris pertama di ctx.saved_person.results[0].id. Untuk membuat baris, gunakan insert tanpa id. Pada pembuatan, fields kosong memakai nilai bawaan tabel; pada perubahan, setidaknya satu kolom harus diisi. Saran metadata tidak menampilkan kolom hasil perhitungan atau kolom yang tidak boleh diubah. OzmaDB tetap memeriksa izin dan batas akhirnya.
Jenis yang didukung: string, number, boolean, json, dan null. Di JSON tindakan, value selalu teks; jenis yang dipilih diterapkan saat tindakan dijalankan setelah variabel diganti. Angka tidak kehilangan ketepatannya, sedangkan string tidak diubah menjadi sintaks JSON. json menerima JSON yang benar atau variabel yang persis berisi JSON. JSON yang salah menyebabkan kesalahan. Nama skema, objek, dan kolom harus tetap, tidak boleh memakai variabel.
Jika respons hilang setelah permintaan penulisan terkirim, Anda mungkin tidak tahu apakah data sudah tersimpan. Periksa OzmaDB sebelum mengulang. Pengulangan otomatis tanpa perlindungan dari duplikasi tidak aman. Untuk transaksi beberapa tindakan yang dibuat secara khusus, gunakan mode Permintaan HTTP.
Mengambil bagian data apa pun dari JSON
Dalam kedua tindakan sumber, termasuk mode Permintaan HTTP, buka Membaca bagian respons. Aktifkan pilihan itu, lalu pilih Hasil tindakan setelah result_path atau penyiapan Ozma, atau Respons lengkap sebelum perubahan. Nama hasil utama tetap bekerja; aturan tambahan menyimpan nilai dalam nama data sementara (ctx) yang Anda pilih.
Setelah Pratinjau pembacaan, baris tampil sebagai pohon data. Pratinjau tidak mengaktifkan pembacaan bagian respons dan tidak mengubah tindakan. Klik kolom untuk membuat variabel bernama, atau Kumpulkan dari semua baris untuk mengambil nilai kolom itu dari seluruh baris, misalnya id menjadi daftar ids. Aturan baru ditambahkan ke aturan lama. Nama yang sama mendapat akhiran unik; Anda dapat mengubah nama atau menyalin variabel yang sudah jadi.
Tombol Seluruh respons, Baris pertama, dan Semua ID membantu memilih hasil umum. Dua pilihan terakhir memerlukan daftar yang sesuai dalam contoh. Pada penulisan, ID baris yang dibuat menambahkan variabel wajib created_id tanpa perlu membuat baris uji. Aturan baru memakai respons lengkap, sedangkan sumber aturan lama tetap. Anda dapat mengubah sumber, menempel contoh JSON, dan menyesuaikan jalur atau cara membaca JSON di dalam teks. Pohon besar hanya ditampilkan sebagian. Contoh tidak disimpan sebagai pengaturan tindakan. Periksa pembacaan hanya menguji contoh, tanpa menghubungi sumber data.
Contoh respons yang memiliki data bersarang:
{
"results": [{ "id": 9007199254740993 }],
"groups": [
{ "members": [{ "name": "Alex", "active": false }] },
{ "members": [{ "name": "Sam", "active": true }] }
],
"extra": "{\"status\":{\"ready\":false}}"
}
Tambahkan aturan berikut pada tindakan:
{
"response_parser": {
"source": "raw",
"decode_json_strings": true,
"rules": [
{ "path": "$.results[0].id", "save_to_ctx": "created_id", "mode": "value", "required": true },
{ "path": "$.groups[*].members[*].name", "save_to_ctx": "member_names", "mode": "list" },
{ "path": "/extra/status/ready", "save_to_ctx": "ready", "mode": "value" }
]
}
}
Aturan tersebut menyimpan created_id dengan nilai angka yang tepat, member_names sebagai ["Alex","Sam"], dan ready sebagai false. Setelah membuat baris, masukkan {{ctx.created_id}} ke ID baris pada tindakan berikutnya. Anda dapat mengambil teks, angka, benar/salah, objek, daftar, null, atau seluruh respons melalui $. Pilihan Baca JSON dalam teks juga membuka JSON bersarang pada pohon contoh.
Jalur yang didukung mencakup .name, ["a.b"] dengan aturan pengutipan JSON, indeks positif dan negatif ([0], [-1]), semua anggota ([*], .*), potongan ([1:3]), dan JSON Pointer menurut RFC 6901. Untuk nama kolom a/b, gunakan /a~1b; tanda ~ menjadi ~0, dan jalur / memilih nama kosong. Filter, rumus, dan skrip tidak didukung.
Mode Satu nilai memberi kesalahan jika ada beberapa hasil. Untuk jalur dengan *, pilih Daftar nilai. Aturan wajib memberi kesalahan jika hasil tidak ditemukan. Aturan tidak wajib yang kosong menjadi null atau [] untuk daftar; null yang benar-benar ditemukan berbeda dari nilai yang tidak ditemukan dalam pratinjau. Semua aturan dihitung sebelum ctx diubah. Batasnya 32 aturan, 1.024 byte per jalur, 1 MiB untuk masukan dan keluaran, 1.000 hasil per aturan, serta batas kedalaman dan jumlah data yang diperiksa.
ID baris dan keterangan hubungan Ozma
Pilihan Sertakan ID baris utama (mainId) dan Sertakan keterangan nilai terkait (pun) pada pembacaan dapat diaktifkan sendiri-sendiri. include_main_id: true menyimpan mainId. parse_pun: true mengubah sel berketerangan menjadi { "id": 42, "data": "Keterangan" }. Jika kolom sudah bernama mainId, tindakan memberi kesalahan. Respons asli tidak berubah.
Setelah membaca, Anda dapat memilih lagi antara baris yang sudah disiapkan dan respons lengkap di Pengaturan pembacaan tambahan. Contoh yang sesuai ditampilkan untuk aturan lama yang memakai respons lengkap. Mengubah objek, argumen, atau pilihan pembacaan menghapus contoh otomatis lama. Pohon data langsung terlihat; editor Contoh JSON dan Respons JSON terbuka jika diklik. Jika contoh terlalu besar, pesan batas dan editor ditampilkan otomatis.
Pada tindakan berikutnya, buka Variabel, cari created_id pada kelompok Dari tindakan sebelumnya, lalu klik Sisipkan di samping {{ctx.created_id}} pada kolom ID baris atau nilai argumen. Variabel masuk di posisi kursor. Daftar ini hanya berisi hasil tindakan sebelumnya dalam blok yang sama dan diperbarui saat tindakan diubah, dihapus, atau dipindahkan.
Mencari katalog dan informasi objek
Pada pembacaan Ozma baru, kolom Nama hasil di konteks berada sebelum pengaturan objek. Saat Ozma dipilih, nama ozma_rows ditawarkan, dengan akhiran jika sudah digunakan oleh aturan lain. Nama lama dan kolom yang sengaja Anda kosongkan tetap dipertahankan. Nama hasil wajib untuk pembacaan, tetapi boleh kosong untuk penulisan; jika tidak diisi pada pembacaan, muncul pesan kesalahan di dekat kolomnya.
Klik Muat katalog untuk mengambil 50 tampilan yang dapat dibaca atau 50 tabel yang dapat ditulis. Di Objek dari katalog, cari schema.name di seluruh katalog. Pencarian tidak membedakan huruf besar dan kecil serta mencari teks secara harfiah; _ dan % bukan karakter khusus. Muat lagi melanjutkan pencarian dari posisi yang diberikan server. Objek yang dipilih tetap terlihat saat mencari ulang. Anda dapat mengisi nama skema dan objek secara manual jika katalog tidak dapat diakses, mengubah pencarian, atau mengulang halaman yang gagal.
Muat argumen dan kolom menunjukkan argumen wajib, tujuan hubungan, jenis kolom, dan tabel utama. Informasi tambahan menampilkan kolom yang tidak dikenal serta objek atau daftar yang dikodekan sebagai teks JSON. Angka mempertahankan penulisan tepatnya. Untuk data terlalu besar atau bersarang terlalu dalam, editor menampilkan batas tampilannya. Membuka informasi ini tidak mengubah tindakan atau aturan pembacaan respons.
Urutan lengkap pengaturan Ozma
Formulir koneksi Ozma memisahkan nama dan jenis dari alamat server dan kunci yang disimpan. Header HTTP tambahan disembunyikan jika kosong dan dibuka jika sudah diisi. Tombol pemeriksaan ada di dekat hasilnya, sedangkan kunci dipilih melalui tautan. Setelah pengaturan Ozma diubah, hasil pemeriksaan lama disembunyikan. Respons yang terlambat untuk pengaturan lama tidak membuktikan pengaturan baru benar.
Dalam tindakan, konektor dan mode terletak berdampingan. Nama hasil berada di awal formulir. Objek schema.view atau schema.entity yang dipilih terlihat di atas pengaturannya. Kolom manual tersedia dalam Skema dan nama manual, yang disembunyikan jika objek sudah valid dan dibuka jika namanya kosong, salah, atau katalog tidak dapat diakses. Argumen dan kolom penulisan ditampilkan per baris dengan nama, jenis, nilai, dan tombol hapus. Petunjuk kolom wajib tetap terlihat; bantuan lebih rinci ada di Jenis dan variabel.
Pilihan pembacaan menggabungkan ukuran halaman, ID utama, dan keterangan hubungan. Nilai bawaan disembunyikan; nilai khusus dan kesalahan halaman membuka kolom terkait. Pratinjau pembacaan menampilkan baris yang sudah disiapkan sebagai tabel, lalu Respons JSON jika diminta. Saat tidak ada baris, editor menunjukkan hal yang perlu diperiksa. Nilai angka yang tepat dipertahankan. JSON hasil dan Respons lengkap OzmaDB dapat dibuka terpisah.
Pada pembacaan respons Ozma, pilihan cepat, variabel hasil, pengaturan jalur, contoh data, pohon, dan hasil pemeriksaan dikelompokkan bersama. Tindakan HTTP lama mempertahankan tampilan dan perilaku pembacaan responsnya. Informasi tambahan langsung terbuka pada tingkat kolom yang relevan.
Langkah berikutnya
- Tindakan: Permintaan ke sumber dan Tulis ke sumber.
- Variabel dan rumus: memakai hasil dari
ctx. - Integrasi: koneksi siap pakai ke layanan populer.