سرویس میز

سرویس Tables به اسکریپت‌ها اجازه می‌دهد تا به صورت برنامه‌نویسی شده سطرهای درون Google Tables را خوانده و ویرایش کنند.

مرجع

برای اطلاعات بیشتر در مورد این سرویس، به مستندات مربوط به API جداول مراجعه کنید. مانند تمام سرویس‌های پیشرفته در Apps Script، سرویس جداول از همان اشیاء، متدها و پارامترهای 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
  ]
}

پاسخ به طور پیش‌فرض شامل حداکثر ۲۰ جدول است. برای بازیابی جداول بیشتر، پاسخ‌ها را با استفاده از پارامترهای 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 برای جداول فهرست، ۱۰۰ است.

دریافت اطلاعات جدول و تعاریف ستون‌ها

مثال زیر نحوه دریافت اطلاعات یک جدول خاص و تعریف ستون را نشان می‌دهد.

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

پاسخ به طور پیش‌فرض شامل حداکثر ۵۰ ردیف است. برای بازیابی ردیف‌های بیشتر، پاسخ‌ها را با استفاده از پارامترهای 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 برابر با ۱۰۰۰ است.

دریافت یک ردیف از جدول

مثال زیر نحوه خواندن مقادیر فیلد یک ردیف از یک جدول را نشان می‌دهد.

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);

وقتی مقادیری را برای تنظیم ردیف جدید مشخص می‌کنید، کلیدهای جفت‌های کلید-مقدار شیء باید دقیقاً با عناوین حساس به حروف بزرگ و کوچک ستون‌های جدول مطابقت داشته باشند، مگر اینکه نوع ستون قابل نوشتن، ستون جستجو یا خلاصه باشد. شما مقادیر ستون‌های جستجو و خلاصه را با استفاده از مقدار رابطه تنظیم می‌کنید. شما باید مقدار رابطه را با استفاده از نام رابطه موجود در کادر محاوره‌ای Relationships به‌روزرسانی کنید.

مقادیر قابل قبول برای یک ستون به نوع داده ستون بستگی دارد:

نوع ستون نوع داده (خواندنی) انواع ورودی قابل قبول (نوشتن)
داده‌های استاندارد
متن String String
شماره Number Number
تاریخ Date
Object {
"year": Number,
"month": Number,
"day": Number
}
Date ، String (در اکثر قالب‌های تاریخ)
داده‌های غنی
شخص String (آدرس ایمیل) String (باید با کاربر گوگل مطابقت داشته باشد)
پیوست فایل 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 برای هر ردیف استفاده کنید که شامل شناسه‌های جدول و ردیف است.

دریافت شناسه ردیف از رابط کاربری جداول
  1. جدول را در برنامه وب Tables باز کنید.
  2. روی ردیف مورد نظر کلیک راست کنید.
  3. روی دریافت پیوند به این ردیف کلیک کنید.
  4. آدرس اینترنتی (URL) را در جایی پیست کنید تا بتوانید شناسه (ID) را کپی کنید.
  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