سرویس Tables به اسکریپتها اجازه میدهد تا به صورت برنامهنویسی شده سطرهای درون Google Tables را خوانده و ویرایش کنند.
مرجع
برای اطلاعات بیشتر در مورد این سرویس، به مستندات مربوط به API جداول مراجعه کنید. مانند تمام سرویسهای پیشرفته در Apps Script، سرویس جداول از همان اشیاء، متدها و پارامترهای API عمومی استفاده میکند. برای اطلاعات بیشتر، به بخش «نحوه تعیین امضاهای متد» مراجعه کنید.
برای گزارش مشکلات و یافتن پشتیبانیهای دیگر، به راهنمای پشتیبانی Tables مراجعه کنید.
کد نمونه
دریافت لیست جداول
مثال زیر نحوه دریافت لیستی از تمام جداول متعلق به کاربر را نشان میدهد.
// Get list of tables the user owns var response = Area120Tables.Tables.list(); if (response) { var tables = response.tables; Logger.log(JSON.stringify(tables[0])); }
در زیر نمونهای از پاسخ آمده است که شامل اطلاعاتی در مورد جدول و تعاریف ستونهای جدول است:
{
“tables”: [
{
"name": "tables/b6prMlkWyekbsCFeX6IOdu",
"displayName": "Applicants"
"columns": [
{"id": "9qVCMvgh", "name": "Name", "dataType": "text"},
{"id": "aD8dDXAS", "name": "Email", "dataType": "text"},
{"id": "9pc0kdNX", "name": "Experience", "dataType": "tags_list",
"labels": [
{"id": "aAqi235Q", "name": "Android"},
{"id": "bULZ4OK3", "name": "iOS"},
],
},
{"id": "8abYfCyo", "name": "Home Address", "dataType": "location"},
{"id": "8ccERJ2v", "name": "Doc", "dataType": "file_attachment_list"},
{"id": "aFb-tXf1", "name": "Stage", "dataType": "dropdown",
"labels": [
{"id": "8Hcb-Pxe", "name": "Applied"},
{"id": "aM3EDGFf", "name": "Phone Screen"},
{"id": "abyFLVKU", "name": "Onsite Interview"},
],
},
{"id": "9yKUThTi", "name": "Recruiter", "dataType": "person_list"},
{"id": "a5c9WPVA", "name": "Interview Date", "dataType": "date"},
{"id": "bqtbYPtH", "name": "Created", "dataType": "create_timestamp"},
{"id": "bWR08pBv", "name": "Updated", "dataType": "update_timestamp"}
]
},
... // more tables
]
} پاسخ به طور پیشفرض شامل حداکثر ۲۰ جدول است. برای بازیابی جداول بیشتر، پاسخها را با استفاده از پارامترهای page_token و page_size ، همانطور که در زیر نشان داده شده است، صفحهبندی کنید:
// Paginate through a list of tables var pageSize = 1000; var pageToken; var response = Area120Tables.Tables.list({page_size: pageSize}); while (response) { var tables = response.tables; // get next page of tables pageToken = response.nextPageToken; if (!pageToken) { response = undefined; } else { response = Area120Tables.Tables.list(tableRequest, {page_size: pageSize, page_token: pageToken}); } }
حداکثر مقدار پارامتر page_size برای جداول فهرست، ۱۰۰ است.
دریافت اطلاعات جدول و تعاریف ستونها
مثال زیر نحوه دریافت اطلاعات یک جدول خاص و تعریف ستون را نشان میدهد.
var tableID = "TABLE_ID"; // ID for the table
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.get(tableName);
Logger.log(JSON.stringify(response));پیدا کردن شناسه جدول
برای یافتن شناسه یک جدول، جدول را در برنامه وب Tables باز کنید. در URL بالا، شناسه جدول درست بعد از /table/ قرار دارد.
نمونه زیر نشان میدهد که در URL های مختلف جداول، کجا میتوانید شناسه جدول را پیدا کنید:
https://tables.area120.google.com/u/0/workspace/abcdefghijklmnop/table/TABLE_IDhttps://tables.area120.google.com/u/0/table/TABLE_IDhttps://tables.area120.google.com/u/0/table/TABLE_ID/view/abcedfghijk
خواندن سطرهای یک جدول
مثال زیر نحوه دریافت لیستی از ردیفهای یک جدول و خواندن مقادیر فیلدها را نشان میدهد.
var tableID = "TABLE_ID"; // ID for the table
var pageToken;
var pageSize = 1000;
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.Rows.list(tableName)
if (response) {
for (var i = 0, rows = response.rows; i < rows.length; i++) {
if (!rows[i].values) { // If blank row, keep going
Logger.log("Empty row");
continue;
}
Logger.log(rows[i].values);
Logger.log(rows[i].values["Description"]);
}
}یک نمونه پاسخ در زیر نشان داده شده است. پاسخ شامل لیستی از ردیفهای جدول و مقادیر هر فیلد است.
{
“rows”: [
{
"name": "tables/TABLE_ID/rows/a6tvEPska7l8rAlHlSdOLb",
"values": {
"Thing to do": "First item", // Text
"Size": 100, // Number
"ETA":{"month":12,"day":3,"year":2021} // Date
"Stage": "Completed", // Dropdown
"Checklist": [ // Checklist
"Do this",
"then this"
],
"Labels": [ // Tags
"Green",
"Purple"
],
"Address": { // Location
"latitude": 40.740726470947266,
"longitude": -74.00206756591797,
"address": "3014 Watson Lane, Sattler, TX 78130, USA"
},
"Archive?": true, // Checkbox
"ID#": 1, // Auto ID
"Row creator": "liz@gmail.com", // Creator / Updater / Person
"Last updated": "October 7, 2020 6:30:38 PM EDT",
"Created on": "March 2, 2020 1:07:54 PM EST",
}
},
... // More rows
],
} پاسخ به طور پیشفرض شامل حداکثر ۵۰ ردیف است. برای بازیابی ردیفهای بیشتر، پاسخها را با استفاده از پارامترهای page_token و page_size ، همانطور که در زیر نشان داده شده است، صفحهبندی کنید:
var pageToken; var pageSize = 1000; var response = Area120Tables.Tables.Rows.list(tableName, {page_size: pageSize}); while (response) { var rows = response.rows; // read next page of rows pageToken = response.nextPageToken; if (!pageToken) { response = undefined; } else { response = Area120Tables.Tables.Rows.list(tableName, {page_size: pageSize, page_token: pageToken}); } }
اگر صفحات بیشتری موجود باشد، پاسخ یک nextPageToken ارائه میدهد. در غیر این صورت، پاسخ تعریف نشده است. برای بازیابی صفحه بعدی نتایج، nextPageToken را به فراخوانی لیست بعدی ارسال کنید.
حداکثر مقدار پارامتر page_size برابر با ۱۰۰۰ است.
دریافت یک ردیف از جدول
مثال زیر نحوه خواندن مقادیر فیلد یک ردیف از یک جدول را نشان میدهد.
var tableID = "TABLE_ID"; // ID for the table var tableName = "tables/" + tableID; var rowID = "ROW_ID"; // ID for the row to fetch var rowName = tableName + "/rows/" + rowID; // Construct row name var response = Area120Tables.Tables.Rows.get(rowName) if (response) { Logger.log(response.values); }
فیلتر کردن لیست ردیفها
برای فیلتر کردن لیست ردیفها به منظور دستیابی به نتایجی که فقط به آنها علاقهمند هستید، از پارامتر filter استفاده کنید. برای جزئیات بیشتر در مورد سینتکس و انواع ستونهای پشتیبانی شده توسط فیلتر، لطفاً به مستندات API فیلترینگ نگاهی بیندازید.
var tableID = "TABLE_ID"; // ID for the table
var pageToken;
var pageSize = 1000;
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.Rows.list(tableName, {filter:"values.\"Point of Contact\"=\"john.doe@gmail.com\""})
if (response) {
for (var i = 0, rows = response.rows; i < rows.length; i++) {
if (!rows[i].values) { // If blank row, keep going
Logger.log("Empty row");
continue;
}
Logger.log(rows[i].values);
Logger.log(rows[i].values["Description"]);
}
}پاسخ شامل ردیفهایی است که ستون «نقطه تماس» روی «john.doe@gmail.com» تنظیم شده است.
{
“rows”: [
{
"name": "tables/TABLE_ID/rows/a6tvEPska7l8rAlHlSdOLb",
"values": {
"Thing to do": "Second item", // Text
"Size": 110, // Number
"ETA":{"month":12,"day":3,"year":2021} // Date
"Stage": "Completed", // Dropdown
"Checklist": [ // Checklist
"Do this",
"then this",
"finally this"
],
"Labels": [ // Tags
"Green",
"Orange"
],
"Address": { // Location
"latitude": 45.740726470947266,
"longitude": -88.00206756591797,
"address": "6027 Holmes Lane, Sattler, TX 78130, USA"
},
"Archive?": false, // Checkbox
"ID#": 2, // Auto ID
"Point of Contact": "john.doe@gmail.com", // Person
"Last updated": "October 9, 2020 6:35:38 PM EDT",
"Created on": "March 10, 2020 1:07:54 PM EST",
}
},
... // More rows
],
}ایجاد یک ردیف در جدول
مثال زیر نحوه اضافه کردن یک ردیف به جدول را نشان میدهد.
var tableID = "TABLE_ID"; // ID for the table
var tableName = "tables/" + tableID;
var values = {
"Number Column": 100,
"Text Column 2": "hello world",
"Date Column 3": new Date(),
"Dropdown Col.": "Dropdown value",
};
Area120Tables.Tables.Rows.create({values: values}, tableName);وقتی مقادیری را برای تنظیم ردیف جدید مشخص میکنید، کلیدهای جفتهای کلید-مقدار شیء باید دقیقاً با عناوین حساس به حروف بزرگ و کوچک ستونهای جدول مطابقت داشته باشند، مگر اینکه نوع ستون قابل نوشتن، ستون جستجو یا خلاصه باشد. شما مقادیر ستونهای جستجو و خلاصه را با استفاده از مقدار رابطه تنظیم میکنید. شما باید مقدار رابطه را با استفاده از نام رابطه موجود در کادر محاورهای Relationships بهروزرسانی کنید.
مقادیر قابل قبول برای یک ستون به نوع داده ستون بستگی دارد:
| نوع ستون | نوع داده (خواندنی) | انواع ورودی قابل قبول (نوشتن) |
|---|---|---|
| دادههای استاندارد | ||
| متن | String | String |
| شماره | Number | Number |
| تاریخ | Date | Date ، String (در اکثر قالبهای تاریخ) |
| دادههای غنی | ||
| شخص | String (آدرس ایمیل) | String (باید با کاربر گوگل مطابقت داشته باشد) |
| پیوست فایل | Object[] { | این فیلد را نمیتوان با API تغییر داد. |
| مکان | Object { | Object { |
| ورودی غنی | ||
| منوی کشویی | String | String (باید با گزینههای منوی کشویی مطابقت داشته باشد) |
| برچسبها | String[] (آرایهای از گزینههای برچسب) | String[] (باید با گزینههای تگ مطابقت داشته باشد) |
| کادر انتخاب | Boolean | Boolean |
| چک لیست | String[] (آرایهای از اقلام لیست) | String[] (باید با آیتمهای لیست مطابقت داشته باشد) |
| دادههای پیوندی | ||
| رابطه | String | String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]" |
| جستجو | بستگی به نوع ستون منبع دارد. | این فیلد قابل تغییر نیست و با مقدار لینک شده بهروزرسانی میشود. |
| خلاصه | بستگی به نوع ستون منبع و تابع خلاصه دارد: تعداد : Numberحداکثر مقدار روی یک ستون از نوع تاریخ : Stringمقادیر لیست : Array | این فیلد قابل تغییر نیست. |
| میدان محاسبهشده | ||
| شناسه خودکار | Number | این فیلد قابل تغییر نیست. |
| فراداده | ||
| خالق | String | این فیلد قابل تغییر نیست. |
| زمان ایجاد کنید | Object { | این فیلد قابل تغییر نیست. |
| بهروزرسانیکننده | String | این فیلد قابل تغییر نیست. |
| زمان بهروزرسانی | Object { | این فیلد قابل تغییر نیست. |
سرویس Tables تمام تلاش خود را میکند تا مقادیر داده شده را به گونهای تبدیل کند که با نوع ستون مطابقت داشته باشند. اگر دادهها مطابقت نداشته باشند، مقدار را تنظیم نمیکند و آن را برای ردیفهای جدید خالی میگذارد.
اضافه کردن چندین ردیف به یک جدول
مثال زیر نحوه اضافه کردن چندین ردیف به یک جدول را به طور همزمان نشان میدهد.
var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
Area120Tables.Tables.Rows.batchCreate({requests: [
{row:{values:{"Col 1":"Sample", "Col 2":"One", "Col 3":"A"}}},
{row:{values:{"Col 1":"Example", "Col 2":"Two", "Col 3":"B"}}},
{row:{values:{"Col 1":"Test", "Col 2":"Three", "Col 3":"C"}}},
]}, tableName)بهروزرسانی یک ردیف در جدول
مثال زیر نحوه بهروزرسانی مقادیر یک ردیف موجود در یک جدول را نشان میدهد:
var rowName = "tables/TABLE_ID/rows/ROW_ID"; var values = {"Column": "HELLO"}; var response = Area120Tables.Tables.Rows.patch({values: values}, rowName); Logger.log("Update row:" + JSON.stringify(response));
شناسه ردیف را پیدا کنید
شما میتوانید شناسه یک ردیف را به دو روش پیدا کنید:
دریافت شناسه ردیف با API
وقتی ردیفهایی از یک جدول را میخوانید، میتوانید از ویژگی name برای هر ردیف استفاده کنید که شامل شناسههای جدول و ردیف است.
دریافت شناسه ردیف از رابط کاربری جداول
- جدول را در برنامه وب Tables باز کنید.
- روی ردیف مورد نظر کلیک راست کنید.
- روی دریافت پیوند به این ردیف کلیک کنید.
- آدرس اینترنتی (URL) را در جایی پیست کنید تا بتوانید شناسه (ID) را کپی کنید.
- در داخل URL، شناسه بعد از
/row/قرار دارد.
مثال زیر نشان میدهد که شناسه ردیف را در URL کجا میتوان پیدا کرد:
https://tables.area120.google.com/table/TABLE_ID/row/ROW_ID
بهروزرسانی چندین ردیف در یک جدول
مثال زیر نحوه بهروزرسانی مقادیر چندین ردیف در یک جدول را نشان میدهد:
var tableID = “TABLE_ID”; var tableName = "tables/" + tableID; var requests = [ {row: {name: "tables/TABLE_ID/rows/ROW_ID_1", values: {"Column": "WORLD"}}}, {row: {name: "tables/TABLE_ID/rows/ROW_ID_2", values: {"Column": "WORLD"}}}, {row: {name: "tables/TABLE_ID/rows/ROW_ID_3", values: {"Column": "WORLD"}}}, ]; var response = Area120Tables.Tables.Rows.batchUpdate({requests: requests}, tableName); Logger.log("Batch update rows:" + JSON.stringify(response));
حذف یک ردیف در جدول
مثال زیر نحوه حذف یک ردیف از جدول را نشان میدهد:
var rowName = "tables/TABLE_ID/rows/ROW_ID"; var response = Area120Tables.Tables.Rows.remove(rowName); Logger.log("Delete row:" + JSON.stringify(response));
حذف چندین ردیف در یک جدول
مثال زیر نحوه حذف چندین ردیف در یک جدول را نشان میدهد:
var tableID = “TABLE_ID”; var tableName = "tables/" + tableID; var rowNames = [ "tables/TABLE_ID/rows/ROW_ID_1", "tables/TABLE_ID/rows/ROW_ID_2", "tables/TABLE_ID/rows/ROW_ID_3", ]; Area120Tables.Tables.Rows.batchDelete({names: rowNames}, tableName);
بازگرداندن سطرهای حذف شده
میتوانید ردیفهای حذف شده را از رابط کاربری جداول بازیابی کنید. برای بازیابی یک ردیف حذف شده، مراحل زیر را دنبال کنید:
- در رایانه خود، برنامه وب Tables را باز کنید.
- جدولی را که میخواهید سطرهای آن را بازیابی کنید، باز کنید.
- در بالا، روی «نمایش سطرها و ستونهای حذفشده» کلیک کنید.
- روی ردیفهای حذفشده کلیک کنید.
- در سمت راست ردیفی که میخواهید بازیابی کنید، روی «بازیابی از سطل زباله» کلیک کنید.
دریافت لیست فضاهای کاری
مثال زیر نحوه دریافت لیستی از تمام فضاهای کاری متعلق به کاربر را نشان میدهد.
// Get list of workspaces the user owns and lists the tables in each one: var response = Area120Tables.Workspaces.list(); if (response) { var workspaces = response.workspaces; for (var workspace of workspaces){ Logger.log(workspace.displayName); for (var table of workspace.tables) { Logger.log('Table: ' + table); } } }
در زیر نمونهای از لاگهای خروجی را مشاهده میکنید:
My Workspace Table: Table 1 Table: Table 2 My TODOs Table: Tasks