خدمة الجداول

تسمح خدمة "جداول بيانات Google" للنصوص البرمجية بقراءة الصفوف وتعديلها آليًا ضمن جداول بيانات Google.

مراجع

لمزيد من المعلومات عن هذه الخدمة، يُرجى الاطّلاع على المستندات لـ Tables API. مثل جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة Tables العناصر والأساليب والمَعلمات نفسها المستخدَمة في واجهة برمجة التطبيقات العامة. لمزيد من المعلومات، اطّلِع على كيفية تحديد توقيعات الطرق.

للإبلاغ عن المشاكل والعثور على دعم آخر، يُرجى الاطّلاع على دليل دعم "جداول بيانات Google".

نموذج التعليمات البرمجية

الحصول على قائمة بالجداول

يوضّح العيّنة التالية كيفية الحصول على قائمة بجميع الجداول التي يملكها المستخدم.

// 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. لمزيد من التفاصيل حول البنية وأنواع الأعمدة المتوافقة مع الفلتر، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات لفلتر البيانات.

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

عند تحديد القيم المطلوب ضبطها للصف الجديد، يجب أن تتطابق مفاتيح ملف التعريف مع أزواج القيمة-المفتاح تمامًا مع العناوين الحساسة لحالة الأحرف في عمود الجدول ما لم يكن نوع العمود القابل للكتابة هو عمود بحث أو ملخّص. يمكنك ضبط قيم عمودَي lookup وsummary باستخدام قيمة العلاقة. عليك تعديل قيمة العلاقة باستخدام اسم العلاقة المتوفّر في مربّع الحوار العلاقات.

تعتمد القيم المقبولة للعمود على نوع بياناته:

نوع العمود نوع البيانات (قراءة) أنواع الإدخال المقبولة (الكتابة)
البيانات العادية
Text String String
Number Number Number
التاريخ Date
Object {
"year": Number,
"month": Number,
"day": Number
} 		Date وString (في معظم تنسيقات التاريخ)
البيانات الغنية
الشخص String (عنوان البريد الإلكتروني) String (يجب أن تتطابق مع حساب المستخدم على Google)
إرفاق ملف Object[] {
"id": String,
"name": String,
"mimeType": String,
"url": String
} 		لا يمكن تعديل هذا الحقل باستخدام واجهة برمجة التطبيقات.
الموقع الجغرافي 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
}		 لا يمكن تعديل هذا الحقل.

تبذل خدمة "جداول بيانات Google" قصارى جهدها لتحويل القيم المقدَّمة لمطابقة نوع العمود. في حال عدم تطابق البيانات، لن يتم ضبط القيمة وسيبقى الحقل فارغًا في الصفوف الجديدة.

إضافة صفوف متعددة إلى جدول

يوضّح العيّنة التالية كيفية إضافة عدة صفوف إلى جدول في الوقت نفسه. 

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));
 يعرض الردّ الصفّ المعدَّل.

العثور على رقم تعريف الصف

يمكنك العثور على معرّف الصفّ بطريقتَين:

الحصول على معرّف الصف باستخدام واجهة برمجة التطبيقات

عند قراءة الصفوف من جدول، يمكنك استخدام سمة name لكل صف، التي تتضمّن معرّفات الجدول والصف.

الحصول على معرّف الصف من واجهة مستخدم "جداول بيانات Google"
  1. افتح الجدول في تطبيق الويب Tables.
  2. انقر بزر الماوس الأيمن على الصف.
  3. انقر على الحصول على رابط لهذا الصف.
  4. الصِق عنوان URL في مكان ما حتى تتمكّن من نسخ رقم التعريف.
  5. يظهر رقم التعريف بعد /row/ في عنوان URL.

يوضّح المثال أدناه مكان العثور على معرّف الصف في عنوان 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);

استعادة الصفوف المحذوفة

يمكنك استعادة الصفوف المحذوفة من واجهة مستخدم "جداول بيانات Google". لاستعادة صف تم حذفه، اتّبِع الخطوات التالية:

  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