این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

سرویس میز

سرویس جداول به اسکریپت‌ها اجازه می‌دهد تا ردیف‌ها را در Google 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 باز کنید. در 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 1000 است.

یک ردیف از یک جدول بگیرید

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

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 }`	این فیلد قابل تغییر نیست.

سرویس جداول بهترین تلاش را برای تبدیل مقادیر داده شده برای مطابقت با نوع ستون انجام می دهد. اگر داده ها مطابقت نداشته باشند، مقدار را تنظیم نمی کند و آن را برای ردیف های جدید خالی می گذارد.

چند ردیف به یک جدول اضافه کنید

نمونه زیر نشان می دهد که چگونه می توان چندین ردیف را به طور همزمان به یک جدول اضافه کرد.

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 باز کنید.
روی ردیف کلیک راست کنید.
روی دریافت پیوند به این ردیف کلیک کنید.
URL را در جایی قرار دهید تا بتوانید شناسه را کپی کنید.
در 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 را باز کنید.
جدولی را که می خواهید ردیف ها را در آن بازیابی کنید باز کنید.
در بالا، روی نمایش ردیف‌ها و ستون‌های حذف شده کلیک کنید.
روی Deleted rows کلیک کنید.
در سمت راست ردیفی که می‌خواهید بازیابی کنید، روی Restore from trash کلیک کنید.

لیستی از فضاهای کاری را دریافت کنید

نمونه زیر نشان می دهد که چگونه می توان لیستی از تمام فضاهای کاری که کاربر دارد به دست آورد.

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