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

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

חומר עזר

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

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

קוד לדוגמה

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

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

// 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 שונות של טבלאות:

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"]);
  }
}

התשובה כוללת את השורות שבהן העמודה 'Point of Contact' מוגדרת כ-'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 באמצעות הערך של קשר הקשר. צריך לעדכן את הערך של קשר הגומלין באמצעות שם הקשר שנמצא בתיבת הדו-שיח CRM.

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

סוג עמודה סוג הנתונים (קריאה) סוגי קלט מקובלים (כתיבה)
נתונים רגילים
טקסט String String
מספר Number Number
Date (תאריך) 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 לא ניתן לשנות את השדה הזה.
Metadata
יוצר/ת 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