تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

خدمة الجداول

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

مَراجع

للمزيد من المعلومات حول هذه الخدمة، يُرجى الاطّلاع على المستندات الخاصة بـ Tables 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
  ]
}

يتضمّن الرد ما يصل إلى 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);

عند تحديد القيم التي سيتم ضبطها للصف الجديد، يجب أن تتطابق مفاتيح أزواج المفتاح/القيمة للكائن تمامًا مع العناوين الحساسة لحالة الأحرف لأعمدة الجدول، إلا إذا كان نوع العمود القابل للكتابة هو عمود بحث أو عمود 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 }`	لا يمكن تعديل هذا الحقل.

تبذل خدمة 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));

يعرض الرد الصف المعدَّل.

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

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

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

عند قراءة صفوف من جدول، يمكنك استخدام السمة 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.
افتح الجدول الذي تريد استعادة الصفوف فيه.
في أعلى الصفحة، انقر على رمز إظهار الصفوف والأعمدة المحذوفة .
انقر على الصفوف المحذوفة.
على يسار الصف الذي تريد استعادته، انقر على الاستعادة من المهملات .

الحصول على قائمة بمساحات العمل

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

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