Untuk pengendalian data yang lebih baik, muat naik data anda ke Mavibot Tables. Ini akan membolehkan bot anda berjalan dengan lebih pantas dan mengelakkan ralat berkaitan permintaan ke Google Sheets.
- Cara menyediakan Google Sheet
- Di mana untuk mencari ID hamparan
- Cara bekerja dengan huruf lajur
- Cara menggunakan pemboleh ubah dalam nama lajur
- Ralat yang mungkin
- Fungsi untuk bekerja dengan Google Sheets
MAKLUMAT AM
Cara menyediakan Google Sheet
Di mana untuk mencari ID hamparan
ID hamparan terletak dalam URL (diserlahkan dengan warna, antara d/ dan /edit):
Cara bekerja dengan huruf lajur
Jika anda perlu menukar huruf lajur kepada nombor, anda boleh menggunakan fungsi kalkulator c2n. Untuk menukar nombor kepada huruf lajur, gunakan n2c.
Anda juga boleh mengalihkan huruf lajur menggunakan fungsi addCols. Parameter pertama ialah rentetan yang mengandungi huruf lajur, dan parameter kedua ialah ofset. Gunakan ofset negatif untuk bergerak ke kiri.
Contoh:
Hasil:
Cara menggunakan pemboleh ubah dalam nama lajur
Anda boleh menggunakan pemboleh ubah untuk menentukan alamat sel untuk dibaca, dan kemudian menggunakan pemboleh ubah yang sama untuk mendapatkan nilai yang sepadan daripada respons dan menyimpannya dalam pemboleh ubah.
Ralat yang mungkin
Jika hamparan dalam format .XLSX, integrasi tidak akan berfungsi. Anda perlu menukar fail kepada format Google Sheets.
Fungsi untuk Bekerja dengan Google Sheets
Fungsi Google Sheets
Untuk maklumat terperinci tentang menyambung dan menggunakan Google Sheets, lihat DI SINI.
Setiap fungsi menerima pengecam hamparan sheet_id sebagai parameter pertamanya. Anda boleh mencarinya dalam URL Google Sheets anda (bahagian yang diserlahkan dalam huruf tebal dalam contoh di bawah).
https://docs.google.com/spreadsheets/d/1aUbbUaw2SRnJFAavv06Noa1EzumhyShKDm7ie6lYlc4/edit#gid=0
Untuk kemudahan, kami mengesyorkan menyimpan ID hamparan dalam pemboleh ubah dan menghantar pemboleh ubah itu kepada fungsi.
Semua fungsi yang diterangkan di bawah mengembalikan kamus yang mengandungi hasil operasi. Kamus ini sentiasa merangkumi parameter status, yang benar jika operasi berjaya dan palsu jika ralat berlaku.
Jika status adalah benar, respons mungkin mengandungi parameter tambahan yang boleh diambil menggunakan fungsi get().
Jika status adalah palsu, respons mengandungi parameter err dengan penerangan ralat.
Jika anda perlu bekerja dengan lembaran kerja selain daripada yang pertama, anda boleh menghantar parameter tambahan: worksheet_name_or_id_or_index.
Setiap fungsi menerima parameter ini, yang mengenal pasti lembaran kerja dengan nama, ID, atau indeksnya.
Kamus — sesetengah fungsi menerima kamus yang mengandungi set data tertentu. Terdapat beberapa peraturan yang mesti anda patuhi:
- Seluruh kamus mesti disertakan dalam tanda petik tunggal:
'{}'. - Kunci dan nilai kamus (teks atau pemboleh ubah) mesti disertakan dalam tanda petik ganda:
'{"key": "value", "key2": "#{email}"}'.
Cara Menggunakan Akaun Google Anda Sendiri
Secara lalai, pembina MaviBot menggunakan akaun perkhidmatannya sendiri untuk mengakses hamparan anda. Oleh itu, anda perlu memberikan akses penyuntingan kepada hamparan anda melalui pautan.
Untuk keselamatan yang lebih baik, anda boleh menggunakan kelayakan pengesahan dan kunci akaun perkhidmatan anda sendiri.
Google Sheets mempunyai had pada bilangan permintaan yang boleh dibuat dalam tempoh tertentu. Untuk mengelakkan bergantung pada had akaun perkhidmatan kongsi, anda boleh menggunakan akaun anda sendiri.
Untuk melakukan ini, pergi ke tetapan projek anda, buka Pemalar Projek, dan tambah pemboleh ubah bernama sheet_json_keys yang mengandungi tatasusunan kunci anda.
Tatasusunan boleh mengandungi sama ada kunci JSON yang disalin daripada fail atau URL yang menunjuk ke fail kunci.
Kunci JSON daripada fail: Dapatkan fail kunci (arahan disediakan di bawah), buka dalam mana-mana editor teks, salin kandungannya, dan tambahkannya ke tatasusunan.
URL fail kunci: Cara paling mudah untuk mendapatkan URL sedemikian ialah memuat naik fail ke pembina MaviBot.
Untuk melakukan ini:
- Buat blok yang bukan blok keadaan.
- Muat naik fail yang mengandungi kelayakan akaun perkhidmatan ke lampiran blok.
- Klik kanan pada nama fail yang dimuat naik.
- Pilih Salin Alamat Pautan.
Empat contoh pemboleh ubah sheet_json_keys:
1. Tatasusunan yang mengandungi dua URL fail kunci:
["URL fail kunci", "URL fail kunci kedua"]
2. Tatasusunan yang mengandungi dua URL dan dua kunci JSON:
["URL fail kunci", "URL fail kunci kedua", {Kunci JSON daripada fail}, {Kunci JSON daripada fail}]
3. Tatasusunan yang mengandungi satu kunci JSON:
[{Kunci JSON daripada fail}]
(Kunci yang ditunjukkan dalam tangkapan skrin dipendekkan. Kunci sebenar jauh lebih panjang.)
4. Tatasusunan yang mengandungi satu URL fail kunci:
["URL fail kunci"]
Tambah kunci ke Pemalar Projek.
Anda tidak perlu menghantar parameter tambahan apabila memanggil fungsi kalkulator. Kunci akan dimuatkan secara automatik.
Jika pemboleh ubah
sheet_json_keysmengandungi berbilang akaun perkhidmatan, anda mesti mengkonfigurasi kebenaran akses Google Sheets untuk SEMUA AKAUN PERKHIDMATAN yang dinyatakan dalam pemboleh ubah.
Untuk maklumat lanjut tentang menggunakan akaun Google anda sendiri dengan Google Sheets dan mendapatkan kunci akaun perkhidmatan, lihat artikel dokumentasi yang berkaitan.
Cara Membuat Hamparan Baharu daripada MaviBot
MaviBot menyokong penciptaan hamparan Google Sheets baharu.
Untuk menggunakan ciri ini, anda mesti mengkonfigurasi pemboleh ubah sheet_json_keys. Arahan untuk membuat pemboleh ubah ini tersedia di sini.
Fungsi untuk membuat hamparan:
sheet_create_spreadsheet(new_worksheet_title, google_email)
Parameter:
- new_worksheet_title — nama hamparan Google Sheets baharu.
- google_email — alamat e-mel akaun Google anda.
Parameter google_email diperlukan untuk memberikan kebenaran editor untuk hamparan yang baru dibuat kepada alamat e-mel yang dinyatakan.
Google secara automatik memberikan pemilikan hamparan kepada projek Google yang anda daftarkan sebelum ini.
Malangnya, ini kini satu-satunya kaedah yang tersedia untuk membuat hamparan Google Sheets melalui API.
Contoh:
new = sheet_create_spreadsheet('ЧЕМОДАНчик', '[email protected]')
Selepas menyegarkan halaman Google Sheets dalam akaun anda, anda akan menemui hamparan yang baru dibuat:
Pemboleh ubah bernama google_spreadsheet_id akan muncul dalam senarai pemboleh ubah pelanggan. Ia akan mengandungi ID hamparan yang baru dibuat.
Jika permintaan diselesaikan dengan jayanya, fungsi mengembalikan kamus yang mengandungi status dan pemberitahuan:
{'status': True, 'message': "Google worksheet 'ЧЕМОДАНчик' is created"}
- status — hasil operasi.
- result — mesej operasi.
Jika ralat berlaku, fungsi mengembalikan palsu sebagai status bersama dengan penerangan ralat.
Cara Menambah Lembaran Kerja Baharu ke Hamparan Google Sheets
Gunakan fungsi berikut:
sheet_create_worksheet(sheet_id, list_name, cols=None, rows=None)
Fungsi mengembalikan kamus yang mengandungi ID lembaran kerja yang baru dibuat dan status benar:
{"status":true,"list_id":1063146761}
Jika ralat berlaku, fungsi mengembalikan status palsu dan penerangan ralat:
{"status":false,"err":"Ralat atau penerangan"}
Contoh:
result = sheet_create_worksheet('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzTl', "Senarai baharu")
status = get(result, 'status')
Cara Memadam Lembaran Kerja dalam Google Sheets
Untuk memadam lembaran kerja, gunakan fungsi berikut:
sheet_delete_worksheet(sheet_id, worksheet_name_or_index)
Parameter:
- sheet_id — ID hamparan Google Sheets anda.
- worksheet_name_or_id_or_index — nama atau ID lembaran kerja yang anda mahu padam.
Contoh:
dihapus_sfh = sheet_delete_worksheet('1oP8Ax4A7FKUY7Mv9eAYAM8q0J0ddlKaD8dOa076AtvQ', 'Лист14')
Fungsi mengembalikan respons seperti:
{"status":true,"result":"worksheet Лист14 is deleted"}
Jika ralat berlaku, fungsi mengembalikan penerangan ralat.
Cara Mendapatkan Bilangan Lembaran Kerja dalam Google Sheets
Untuk mendapatkan jumlah bilangan lembaran kerja dan senarai pasangan indeks–nama lembaran kerja, gunakan fungsi berikut:
sheet_worksheet_indexes(sheet_id)
- sheet_id — ID hamparan Google Sheets anda.
Contoh:
indeks_lembaran = sheet_worksheet_indexes('1oP8Ax4A7FKUY7Mv9eAYAM8q0J0ddlKaD8dOa076AtvQ')
Fungsi mengembalikan respons seperti:
{
"status": true,
"worksheets_count": 10,
"worksheet_titles": {
"1": "Лист1",
"2": "Лист2",
"3": "cvtyf",
"4": "Лист4",
"5": "о да",
"6": "Это новый лист",
"7": "вль и я",
"8": "таракан",
"9": "чемодан",
"10": "БАЗА ДАННЫХ"
}
}
Jika ralat berlaku, fungsi mengembalikan penerangan ralat.
Cara Menamakan Semula Lembaran Kerja dalam Google Sheets
Untuk menamakan semula lembaran kerja, gunakan fungsi berikut:
sheet_rename_worksheet(sheet_id, worksheet_name_or_index, new_tile)
Parameter:
- sheet_id — ID hamparan Google Sheets anda.
- worksheet_name_or_id_or_index — nama atau ID lembaran kerja yang anda mahu namakan semula.
- new_tile — nama lembaran kerja baharu.
Contoh:
worksheet_title_change = sheet_rename_worksheet('1oP8Ax4A7FKUY7Mv9eAYAM8q0J0ddlKaD8dOa076AtvQ', 'Лист5', 'о да')
Cara Menulis Data Baris demi Baris ke Lajur Tertentu
Anda boleh mengumpul pelbagai data daripada pengguna dan menulisnya ke baris pertama yang tersedia dalam hamparan.
Hamparan mesti mempunyai baris pengepala. Sekurang-kurangnya satu sel dalam baris pertama mesti mengandungi nilai.
Gunakan fungsi berikut:
sheet_mapping_cells(sheet_id, cell_data, worksheet_name_or_id_or_index=None)
Parameter:
- sheet_id — ID hamparan Google Sheets anda.
-
cell_data — kamus yang mengandungi data untuk ditulis, contohnya:
'{"A": "value", "D": "#{email}"}', di mana setiap kunci mewakili huruf lajur. - worksheet_name_or_id_or_index — parameter pilihan yang menentukan nama lembaran kerja, indeks, atau ID.
Jika permintaan berjaya, fungsi mengembalikan kamus seperti:
{"status":true,"number_row":14}
Anda boleh menyimpan nilai number_row dan menggunakannya dalam operasi seterusnya.
Contoh:
result = sheet_mapping_cells('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzT', '{"a":"aaaaa", "B": "#{email}"}')
status = get(result, 'status')
number_row = get(result, 'number_row')
Contoh dengan pengecam lembaran kerja:
list_name = 'Рейтинг'
result = sheet_mapping_cells('#{gsheet_id}', '{"a":"#{client_id}", "B": "#{ball}"}', '#{list_name}')
Cara Menulis Data ke Baris Kosong Pertama
Anda boleh mengumpul pelbagai data daripada pengguna dan menulisnya ke baris kosong pertama dalam hamparan.
Fungsi ini berfungsi sama seperti sheet_mapping_cells, tetapi menambah baris baharu apabila hujung hamparan dicapai.
Perhatikan bahawa kaedah ini tidak semestinya menulis data ke bahagian bawah hamparan. Ia menulis ke baris kosong pertama.
Ia paling sesuai untuk menambah data secara berterusan ke lajur yang sama.
Gunakan fungsi berikut:
sheet_append_row(sheet_id, cell_data, worksheet_name_or_id_or_index=None)
Parameter:
- sheet_id — ID hamparan Google Sheets anda.
-
cell_data — kamus yang mengandungi data untuk ditulis, contohnya:
'{"A": "value", "D": "#{email}"}', di mana setiap kunci mewakili huruf lajur. - worksheet_name_or_id_or_index — parameter pilihan yang menentukan nama lembaran kerja, indeks, atau ID.
Jika permintaan berjaya, fungsi mengembalikan kamus seperti:
{"status":true,"number_row":14}
Anda boleh menyimpan nilai number_row untuk kegunaan masa hadapan.
Contoh:
result = sheet_append_row('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzT', '{"a":"aaaaa", "B": "#{email}"}')
status = result["status"]
number_row = result["number_row"]
Contoh dengan pengecam lembaran kerja:
list_name = 'результаты викторины'
gs_id = '12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzT'
result = sheet_append_row(gs_id, '{"a":"#{client_id}", "B": "#{ball}"}', list_name)
Cara Menulis Data ke Sel Tertentu
Gunakan fungsi berikut:
sheet_write_cells(sheet_id, cell_data, worksheet_name_or_id_or_index=None)
Parameter:
- sheet_id — ID hamparan Google Sheets anda.
-
cell_data — kamus yang mengandungi alamat sel dan nilai, contohnya:
'{"A1": "value", "D4": "#{email}"}'. Setiap kunci terdiri daripada huruf lajur dan nombor baris. - worksheet_name_or_id_or_index — parameter pilihan yang menentukan nama lembaran kerja, indeks (bermula dari 1), atau ID.
Contoh cell_data:
'{"a1":"#{переменная}", "b3":"#{переменная}", "c1":"12545", "d20":"просто текст"}'
Data ditulis ke sel tepat yang anda tentukan. Dalam contoh ini, sel tersebut ialah a1, b3, c1, dan d20.
Jika permintaan berjaya, fungsi mengembalikan:
{"status":true}
Jika ralat berlaku, fungsi mengembalikan penerangan ralat:
{"status":false,"err":"Error or description"}
Contoh sheet_write_cells:
Dengan ID lembaran kerja 123456789:
result = sheet_write_cells('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzTl', '{"a1":"a3", "b3": "#{email}"}', '123456789')
Tanpa menentukan lembaran kerja:
result = sheet_write_cells('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzTl', '{"a1":"a3", "b3": "#{email}"}')
status = get(result, 'status')
Cara Membersihkan Sel Tertentu
Gunakan fungsi berikut:
sheet_remove_cells(sheet_id, cell_list, worksheet_name_or_id_or_index=None)
Parameter:
- sheet_id — ID hamparan Google Sheets anda.
-
cell_list — tatasusunan alamat sel, contohnya:
'["A1", "D4"]', di mana setiap alamat mengandungi huruf lajur dan nombor baris. - worksheet_name_or_id_or_index — parameter pilihan yang menentukan nama lembaran kerja, indeks (bermula dari 1), atau ID.
Jika permintaan berjaya, fungsi mengembalikan:
{"status":true}
Jika ralat berlaku, fungsi mengembalikan:
{"status":false,"err":"Error or description"}
Contoh:
Dengan ID lembaran kerja 123456789:
result = sheet_remove_cells('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzT', '["a1", "b3", "c2"]', '123456789')
Tanpa menentukan lembaran kerja:
result = sheet_remove_cells('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzT', '["a1", "b3", "c2"]')
status = get(result, 'status')
Fungsi ini membersihkan nilai dalam sel yang ditentukan: a1, b3, dan c2.
Penomboran lajur bermula dari 1.
Cara Menulis Data ke Sel Kosong Pertama dalam Baris
Anda boleh menulis data ke baris yang ditentukan. Nilai akan diletakkan dalam sel kosong pertama di sebelah kanan sel terakhir yang diisi.
Gunakan fungsi berikut:
sheet_append_cell_in_row(sheet_id, row, value, worksheet_name_or_index=None)
Parameter:
- sheet_id — ID hamparan Google Sheets anda.
- row — nombor baris di mana nilai akan ditulis.
- value — nilai untuk ditulis ke sel.
- worksheet_name_or_id_or_index — parameter pilihan yang menentukan nama lembaran kerja, indeks (bermula dari 1), atau ID.
Jika permintaan berjaya, fungsi mengembalikan respons seperti:
{"status":true,"number_col":10,"col_name":"J3"}
Anda boleh menyimpan nilai ini untuk kegunaan masa hadapan.
Jika ralat berlaku, fungsi mengembalikan kamus dengan status false dan penerangan ralat:
{"status":false,"err":"Error value"}
Contoh:
Menulis nilai ke sel kosong dalam baris pertama:
result = sheet_append_cell_in_row('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzT', 1, "Значение")
Cara Membaca Data daripada Hamparan
Gunakan fungsi berikut:
sheet_read_cells(sheet_id, cell_data, worksheet_name_or_id_or_index=None)
Parameter:
- sheet_id — ID hamparan Google Sheets anda.
- cell_data — kamus yang menentukan julat sel untuk dibaca.
- worksheet_name_or_id_or_index — parameter pilihan yang menentukan nama lembaran kerja, indeks (bermula dari 1), atau ID.
Contoh cell_data:
'{"a1":"a1", "a3":"b4", "c1":"c3"}'
Dalam contoh ini:
-
"a1":"a1"mengembalikan nilai sel tunggal. -
"c1":"c3"mengembalikan tiga nilai dari lajur C.
Jika permintaan berjaya, fungsi mengembalikan kamus yang mengandungi status dan semua nilai sel yang diminta:
{
"status": true,
"A1": "значение",
"A3": "значение",
"B3": "значение",
"A4": "значение",
"B4": "значение",
"C1": "",
"C2": "значение",
"C3": "ddddddd"
}
Jika ralat berlaku, fungsi mengembalikan:
{"status":false,"err":"Error or description"}
Contoh:
Dengan ID lembaran kerja 123456789:
result = sheet_read_cells('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzTl', '{"a1":"a1", "a3": "b4", "c1": "c3"}', '123456789')
Tanpa menentukan lembaran kerja:
result = sheet_read_cells('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzTl', '{"a1":"a1", "a3": "b4", "c1": "c3"}')
status = get(result, 'status')
Cara Membersihkan Julat Sel
Gunakan fungsi berikut:
sheet_remove_range(sheet_id, del_range, worksheet_name_or_id_or_index=None)
Parameter:
- sheet_id — ID hamparan Google Sheets anda.
-
del_range — julat sel untuk dibersihkan, ditentukan dalam format
"A1:B2". - worksheet_name_or_id_or_index — parameter pilihan yang menentukan nama lembaran kerja, indeks (bermula dari 1), atau ID.
Jika permintaan berjaya, fungsi mengembalikan:
{"status":true}
Jika ralat berlaku, fungsi mengembalikan:
{"status":false,"err":"Error or description"}
Contoh:
Bersihkan sel A1, B1, A2, dan B2 pada lembaran kerja pertama:
result = sheet_remove_range('12sSVR3Wk-1kNb9CsjyJ2gjLb_PiRl5DhbF4YcD1VzT', 'A1:B2')
