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

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

חומרי עזר

כדי לקבל מידע נוסף על השירות הזה, אפשר לעיין מסמכי תיעוד לממשק ה-API של Tables. כמו כל השירותים המתקדמים ב-Apps Script, הטבלאות השירות משתמש באותם אובייקטים, שיטות ופרמטרים כמו ה-API הציבורי. למידע נוסף, ראו איך נקבעות חתימות השיטות.

כדי לדווח על בעיות ולקבל תמיכה נוספת, אפשר להיכנס אל מדריך לתמיכה בטבלאות.

קוד לדוגמה

הצגת רשימת הטבלאות

בדוגמה הבאה אפשר לראות איך לקבל רשימה של כל הטבלאות שבבעלות המשתמש.

// 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": "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);

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

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

סוג עמודה סוג הנתונים (קריאה) סוגי קלט קבילים (כתיבה)
נתונים רגילים
טקסט String String
מספר Number Number
‫תאריך Date
Object {
"year": Number,
"month": Number,
"day": Number
} 		Date, String (ברוב הפורמטים של התאריכים)
נתונים עשירים
אדם 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
מקסימום בעמודה של סוג תאריך: String
ערכים ברשימה: Array		 אי אפשר לשנות את השדה הזה.
שדה מחושב
מזהה אוטומטי Number אי אפשר לשנות את השדה הזה.
מטא-נתונים
יוצר/ת String אי אפשר לשנות את השדה הזה.
שעת היצירה Object {
“seconds”: Number,
“nanos”: Number
} 		אי אפשר לשנות את השדה הזה.
מעדכן 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