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

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

חומרי עזר

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

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

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

בדוגמה הבאה מוצג המיקום שבו מופיע מזהה הטבלה בכתובות 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. מגדירים ערכים לעמודות lookup ו-summary באמצעות הערך של הקשר. צריך לעדכן את הערך של הקשר באמצעות שם הקשר שמופיע בתיבת הדו-שיח Relationships.

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

סוג עמודה סוג הנתונים (קריאה) סוגי קלט קבילים (כתיבה)
נתונים רגילים
טקסט 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[] (צריך להתאים לפריטים ברשימה)
נתונים מקושרים
Relationship String String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
Lookup תלוי בסוג העמודה של המקור. אי אפשר לשנות את השדה הזה, והוא יתעדכן בערך המקושר.
סיכום תלוי בסוג עמודת המקור ובפונקציית הסיכום:
Count: Number
Max בעמודה מסוג Date: String
List Values: 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);

שחזור שורות שנמחקו

אפשר לשחזר שורות שנמחקו דרך ממשק המשתמש של הטבלאות. כדי לשחזר שורה שנמחקה:

  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