تتيح خدمة "الجداول" للبرامج النصية قراءة الصفوف وتعديلها آليًا ضمن جداول Google.
مراجع
لمزيد من المعلومات حول هذه الخدمة، يُرجى الاطّلاع على المستندات الخاصة بـ Tables API. مثل جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة 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 ] }
تتضمّن الاستجابة ما يصل إلى 20 جدولاً تلقائيًا. لاسترداد المزيد من الجداول، قسِّم الردود إلى صفحات باستخدام المَعلمتَين 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
لجداول البيانات هو 100.
الحصول على معلومات الجدول وتعريفات الأعمدة
يوضّح المثال التالي كيفية الحصول على معلومات جدول معيّن وتعريف العمود.
var tableID = "TABLE_ID
"; // ID for the table var tableName = "tables/" + tableID; var response = Area120Tables.Tables.get(tableName); Logger.log(JSON.stringify(response));
العثور على رقم تعريف الجدول
للعثور على معرّف جدول، افتح الجدول في تطبيق "الجداول" على الويب. في عنوان URL في أعلى الصفحة، يظهر معرّف الجدول مباشرةً بعد /table/
.
يعرض المثال أدناه مكان العثور على رقم تعريف الجدول في عناوين URL المختلفة لجداول البيانات:
https://tables.area120.google.com/u/0/workspace/abcdefghijklmnop/table/TABLE_ID
https://tables.area120.google.com/u/0/table/TABLE_ID
https://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": "[email protected]", // 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 ], }
تتضمّن الاستجابة ما يصل إلى 50 صفًا تلقائيًا. لاسترداد المزيد من الصفوف، قسِّم الردود إلى صفحات باستخدام المَعلمتَين 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
هو 1,000.
الحصول على صف واحد من جدول
يوضّح المثال التالي كيفية قراءة قيم الحقول لصف واحد من جدول.
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
. لمزيد من التفاصيل حول بنية الفلتر وأنواع الأعمدة المتوافقة معه، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات الخاصة بالفلترة.
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"]); } }
يتضمّن الرد الصفوف التي تم ضبط عمود "جهة الاتصال" فيها على [email protected]
{ “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": "[email protected]", // 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);
عند تحديد القيم التي سيتم ضبطها للصف الجديد، يجب أن تتطابق مفاتيح أزواج المفتاح والقيمة تمامًا مع العناوين الحساسة لحالة الأحرف في أعمدة الجدول، ما لم يكن نوع العمود القابل للكتابة هو عمود بحث أو ملخّص. يمكنك ضبط قيم لعمودَي البحث والملخّص باستخدام قيمة العلاقة. عليك تعديل قيمة العلاقة باستخدام اسم العلاقة الذي يظهر في مربع الحوار العلاقات.
تعتمد القيم المقبولة لعمود على نوع بيانات العمود:
نوع العمود | نوع البيانات (قراءة) | أنواع الإدخال المقبولة (الكتابة) |
---|---|---|
البيانات العادية | ||
Text | String | String |
Number | Number | Number |
التاريخ | Date | Date ، String (في معظم تنسيقات التاريخ) |
بيانات وافية | ||
الشخص | String (عنوان البريد الإلكتروني) | String (يجب أن يتطابق مع مستخدم Google) |
مرفق الملف | Object[] { | لا يمكن تعديل هذا الحقل باستخدام واجهة برمجة التطبيقات. |
الموقع الجغرافي | 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 { | لا يمكن تعديل هذا الحقل. |
تبذل خدمة "جداول" قصارى جهدها لتحويل القيم المحدّدة لتتطابق مع نوع العمود. إذا لم تتطابق البيانات، لن يتم ضبط القيمة وسيتم تركها فارغة في الصفوف الجديدة.
إضافة صفوف متعددة إلى جدول
يوضّح المثال التالي كيفية إضافة صفوف متعددة إلى جدول في الوقت نفسه.
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));
العثور على رقم تعريف الصف
يمكنك العثور على معرّف صفّ بطريقتَين:
الحصول على رقم تعريف الصف باستخدام واجهة برمجة التطبيقات
عند قراءة الصفوف من جدول، يمكنك استخدام السمة name
لكل صف، والتي تتضمّن معرّفات الجدول والصف.
الحصول على معرّف الصف من واجهة مستخدم "جداول Google"
- افتح الجدول في تطبيق Tables على الويب.
- انقر بزر الماوس الأيمن على الصف.
- انقر على الحصول على رابط لهذا الصف.
- ألصِق عنوان URL في مكان ما لتتمكّن من نسخ رقم التعريف.
- ضمن عنوان 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