שירותי שולחנות

שירות הטבלאות מאפשר לסקריפטים לקרוא ולערוך שורות בטבלאות של Google באופן פרוגרמטי.

חומרי עזר

מידע נוסף על השירות הזה זמין במאמרי העזרה של Tables API. בדומה לכל השירותים המתקדמים ב-Apps Script, שירות Tables משתמש באותם אובייקטים, שיטות ופרמטרים כמו ממשק ה-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
  ]
}

התשובה כוללת עד 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));

איך מוצאים את מזהה הטבלה

כדי למצוא את המזהה של טבלה, פותחים את הטבלה באפליקציית האינטרנט של Tables. בכתובת ה-URL בחלק העליון, מזהה הטבלה מופיע מיד אחרי /table/.

בדוגמה שלמטה אפשר לראות איפה מופיע מזהה הטבלה בכתובות URL שונות של Tables:

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": "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
  ],
}

התשובה כוללת עד 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. לפרטים נוספים על התחביר ועל סוגי העמודות שנתמכים במסנן, אפשר לעיין במסמכי ה-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);

כשמציינים את הערכים להגדרה בשורה החדשה, המפתחות של זוגות המפתח-ערך באובייקט חייבים להיות זהים בדיוק לכותרות של עמודות הטבלה, כולל אותיות רישיות, אלא אם הסוג של העמודה שאפשר לכתוב בה הוא lookup או summary. מגדירים ערכים לעמודות lookup ו-summary באמצעות הערך של הקשר. צריך לעדכן את הערך של קשר הגומלין באמצעות שם קשר הגומלין שמופיע בתיבת הדו-שיח Relationships (קשרי גומלין).

הערכים הקבילים בעמודה תלויים בסוג הנתונים של העמודה:

סוג עמודה סוג הנתונים (קריאה) סוגי קלט קבילים (כתיבה)
נתונים רגילים
טקסט String String
מספר Number Number
‫תאריך Date
Object {
"year": Number,
"month": Number,
"day": Number
} 		‫Date, ‏ String (ברוב פורמטי התאריכים)
נתונים עשירים
Person String (כתובת אימייל) String (חייב להיות זהה למשתמש Google)
קובץ מצורף Object[] {
"id": String,
"name": String,
"mimeType": String,
"url": String
} 		אי אפשר לשנות את השדה הזה באמצעות ה-API.
מיקום Object {
"latitude": Number,
"longitude": Number,
"address": String
} 		Object {
"latitude": Number (required),
"longitude": Number (required),
"address": String
}
רשומה עשירה
תפריט נפתח String ‫String (חייב להתאים לאפשרויות בתפריט הנפתח)
תגים ‫String[] (מערך של אפשרויות תגים) ‫String[] (חייב להיות זהה לאפשרויות התג)
תיבת סימון Boolean Boolean
רשימת משימות String[] (מערך של פריטים ברשימה) ‫String[] (חייב להיות זהה לפריטים ברשימה)
נתונים מקושרים
קשר String String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
חיפוש תלוי בסוג העמודה של המקור. אי אפשר לשנות את השדה הזה, והוא יתעדכן לפי הערך המקושר.
סיכום תלוי בסוג עמודת המקור ובפונקציית הסיכום:
ספירה: Number
מקסימום בעמודה מסוג Date: String
רשימת ערכים: Array		 אי אפשר לשנות את השדה הזה.
שדה מחושב
מזהה אוטומטי Number אי אפשר לשנות את השדה הזה.
מטא-נתונים
יוצרים String אי אפשר לשנות את השדה הזה.
זמן יצירה Object {
“seconds”: Number,
“nanos”: Number
} 		אי אפשר לשנות את השדה הזה.
Updater String אי אפשר לשנות את השדה הזה.
זמן העדכון Object {
“seconds”: Number,
“nanos”: Number
}		 אי אפשר לשנות את השדה הזה.

שירות 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
  1. פותחים את הטבלה באפליקציית האינטרנט Tables.
  2. לוחצים לחיצה ימנית על השורה.
  3. לוחצים על קבלת קישור לשורה הזו.
  4. מדביקים את כתובת ה-URL במקום כלשהו כדי שיהיה אפשר להעתיק את המזהה.
  5. בכתובת ה-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. כדי לשחזר שורה שנמחקה, פועלים לפי השלבים הבאים:

  1. במחשב, פותחים את אפליקציית האינטרנט של Tables.
  2. פותחים את הטבלה שרוצים לשחזר בה שורות.
  3. למעלה, לוחצים על 'הצגת שורות ועמודות שנמחקו' .
  4. לוחצים על שורות שנמחקו.
  5. משמאל לשורה שרוצים לשחזר, לוחצים על סמל השחזור מהאשפה .

קבלת רשימה של סביבות עבודה

בדוגמה הבאה מוצג איך מקבלים רשימה של כל סביבות העבודה שהמשתמש הוא הבעלים שלהן.

// 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