Class DataSourceTable

جدولمصدرالبيانات

الوصول إلى جدول مصدر البيانات الحالي وتعديله لإنشاء جدول مصدر بيانات جديد في ورقة بيانات جديدة، استخدِم Spreadsheet.insertSheetWithDataSourceTable(spec).

لا تستخدِم هذه الفئة إلا مع مصادر بيانات BigQuery.

يوضِّح هذا المثال كيفية إنشاء جدول مصدر بيانات جديد. 

SpreadsheetApp.enableBigQueryExecution();
const spreadsheet = SpreadsheetApp.getActive();
const spec = SpreadsheetApp.newDataSourceSpec()
                 .asBigQuery()
                 .setProjectId('big_query_project')
                 .setRawQuery('select @FIELD from table limit @LIMIT')
                 .setParameterFromCell('FIELD', 'Sheet1!A1')
                 .setParameterFromCell('LIMIT', 'namedRangeCell')
                 .build();
// Starts data execution asynchronously.
const dataSheet = spreadsheet.insertSheetWithDataSourceTable(spec);
const dataSourceTable = dataSheet.getDataSourceTables()[0];
// waitForCompletion() blocks script execution until data execution completes.
dataSourceTable.waitForCompletion(60);
// Check status after execution.
Logger.log(
    'Data execution state: %s.',
    dataSourceTable.getStatus().getExecutionState(),
);

يوضّح هذا المثال كيفية تعديل مصدر بيانات. 

SpreadsheetApp.enableBigQueryExecution();
const dataSheet = SpreadsheetApp.getActive().getSheetByName('Data Sheet 1');
const dataSourceTable = dataSheet.getDataSourceTables()[0];
const dataSource = dataSourceTable.getDataSource();
const newSpec = dataSource.getSpec()
                    .copy()
                    .asBigQuery()
                    .setRawQuery('select name from table limit 2')
                    .removeAllParameters()
                    .build();
// Updates data source specification and starts data execution asynchronously.
dataSource.updateSpec(newSpec);
// Check status during execution.
Logger.log(
    'Data execution state: %s.',
    dataSourceTable.getStatus().getExecutionState(),
);
// waitForCompletion() blocks script execution until data execution completes.
dataSourceTable.waitForCompletion(60);
// Check status after execution.
Logger.log(
    'Data execution state: %s.',
    dataSourceTable.getStatus().getExecutionState(),
);

الطُرق

الطريقةنوع القيمة التي يتم عرضهاوصف قصير
addColumns(columnNames)DataSourceTableتُضيف أعمدة إلى جدول مصدر البيانات.
addFilter(columnName, filterCriteria)DataSourceTableتُضيف فلترًا يتم تطبيقه على جدول مصدر البيانات.
addSortSpec(columnName, ascending)DataSourceTableتُضيف مواصفات فرز إلى عمود في جدول مصدر البيانات.
addSortSpec(columnName, sortOrder)DataSourceTableتُضيف مواصفات فرز على عمود في جدول مصدر البيانات.
cancelDataRefresh()DataSourceTableتلغي إعادة تحميل البيانات المرتبطة بهذا العنصر إذا كانت قيد التنفيذ حاليًا.
forceRefreshData()DataSourceTableتؤدي هذه الطريقة إلى إعادة تحميل بيانات هذا العنصر بصرف النظر عن حالته الحالية.
getColumns()DataSourceTableColumn[]تحصل على جميع أعمدة مصدر البيانات التي تمت إضافتها إلى جدول مصدر البيانات.
getDataSource()DataSourceتحصل على مصدر البيانات المرتبط بالعنصر.
getFilters()DataSourceTableFilter[]تعرِض جميع الفلاتر المطبَّقة على جدول مصدر البيانات.
getRange()Rangeتحصل على Range التي يمتد إليها جدول مصدر البيانات هذا.
getRowLimit()Integerتعرِض هذه الدالة الحد الأقصى لعدد الصفوف في جدول مصدر البيانات.
getSortSpecs()SortSpec[]تحصل على جميع مواصفات الفرز في جدول مصدر البيانات.
getStatus()DataExecutionStatusتحصل على حالة تنفيذ البيانات للكائن.
isSyncingAllColumns()Booleanتعرِض هذه الدالة ما إذا كان جدول مصدر البيانات يُزامن جميع الأعمدة في مصدر البيانات المرتبط.
refreshData()DataSourceTableتؤدي هذه الطريقة إلى إعادة تحميل بيانات الكائن.
removeAllColumns()DataSourceTableتزيل جميع الأعمدة في جدول مصدر البيانات.
removeAllSortSpecs()DataSourceTableتزيل جميع مواصفات الفرز في جدول مصدر البيانات.
setRowLimit(rowLimit)DataSourceTableتعديل الحد الأقصى للصفوف في جدول مصدر البيانات
syncAllColumns()DataSourceTableمزامنة جميع الأعمدة الحالية والمستقبلية في مصدر البيانات المرتبط بجدول مصدر البيانات
waitForCompletion(timeoutInSeconds)DataExecutionStatusتنتظر هذه الدالة حتى اكتمال التنفيذ الحالي، وتنتهي مهلة الانتظار بعد عدد الثواني المقدَّم.

مستندات تفصيلية

addColumns(columnNames)

تُضيف أعمدة إلى جدول مصدر البيانات.

المعلَمات

الاسمالنوعالوصف
columnNamesString[]قائمة بأسماء الأعمدة المطلوب إضافتها

الإرجاع

DataSourceTable: جدول مصدر البيانات، للتسلسل

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

addFilter(columnName, filterCriteria)

تُضيف فلترًا يتم تطبيقه على جدول مصدر البيانات.

المعلَمات

الاسمالنوعالوصف
columnNameStringاسم العمود الذي سيتم تطبيق هذا الفلتر عليه.
filterCriteriaFilterCriteriaمعايير الفلتر المطلوب تطبيقها

الإرجاع

DataSourceTable: جدول مصدر البيانات، للتسلسل.

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

addSortSpec(columnName, ascending)

تُضيف مواصفات ترتيب على عمود في جدول مصدر البيانات.

المعلَمات

الاسمالنوعالوصف
columnNameStringاسم العمود المطلوب ترتيبه.
ascendingBooleanإذا كان الخيار true، ترتيب العمود تصاعديًا، وإذا كان الخيار false، ترتيب العمود تنازليًا.

الإرجاع

DataSourceTable: ورقة بيانات المصدر، لإنشاء سلاسل.

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

addSortSpec(columnName, sortOrder)

تُضيف مواصفات ترتيب على عمود في جدول مصدر البيانات.

المعلَمات

الاسمالنوعالوصف
columnNameStringاسم العمود المطلوب ترتيبه.
sortOrderSortOrderنظام الترتيب

الإرجاع

DataSourceTable: ورقة بيانات المصدر، لإنشاء سلاسل.

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

cancelDataRefresh()

تلغي إعادة تحميل البيانات المرتبطة بهذا العنصر إذا كانت قيد التنفيذ حاليًا.

يوضِّح هذا المثال كيفية إلغاء إعادة تحميل صيغة. 

const spreadsheet = SpreadsheetApp.getActive();
const formula = spreadsheet.getDataSourceFormulas()[0];
// Cancel the ongoing refresh on the formula.
formula.cancelDataRefresh();

يُعرِض استثناءً إذا لم يكن نوع مصدر البيانات مفعّلاً. استخدِم طرق SpreadsheetApp#enable...Execution() لتفعيل تنفيذ البيانات لنوع محدّد من مصادر البيانات.

الإرجاع

DataSourceTable: عنصر البيانات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

forceRefreshData()

تؤدي هذه الطريقة إلى إعادة تحميل بيانات هذا العنصر بصرف النظر عن حالته الحالية. يُرجى الاطّلاع على refreshData() للحصول على مزيد من التفاصيل. إذا أردت إلغاء عملية إعادة تحميل هذا العنصر التي يتم تنفيذها حاليًا، اطّلِع على cancelDataRefresh().

يُعرِض استثناءً إذا لم يكن نوع مصدر البيانات مفعّلاً. استخدِم طرق SpreadsheetApp#enable...Execution() لتفعيل تنفيذ البيانات لنوع محدّد من مصادر البيانات.

الإرجاع

DataSourceTable: عنصر البيانات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getColumns()

تحصل على جميع أعمدة مصدر البيانات التي تمت إضافتها إلى جدول مصدر البيانات.

الإرجاع

DataSourceTableColumn[]: قائمة بأعمدة جدول مصدر البيانات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getDataSource()

تحصل على مصدر البيانات المرتبط بالعنصر.

الإرجاع

DataSource: مصدر البيانات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getFilters()

تعرِض جميع الفلاتر المطبَّقة على جدول مصدر البيانات.

الإرجاع

DataSourceTableFilter[]: صفيف لجميع الفلاتر المطبّقة على جدول مصدر البيانات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getRange()

تحصل على Range التي يمتد إليها جدول مصدر البيانات هذا.

الإرجاع

Range: النطاق

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getRowLimit()

تعرِض الحد الأقصى لعدد الصفوف في جدول مصدر البيانات.

الإرجاع

Integer: الحد الأقصى للصفوف في جدول مصدر البيانات، أو null في حال عدم ضبط أي حدّ واستخدام الجدول للحدّ الأقصى التلقائي كما هو الحال في واجهة مستخدم "جداول بيانات Google"

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getSortSpecs()

تحصل على جميع مواصفات الفرز في جدول مصدر البيانات.

الإرجاع

‫SortSpec[]: قائمة بمواصفات الترتيب

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getStatus()

تحصل على حالة تنفيذ البيانات للكائن.

الإرجاع

DataExecutionStatus: حالة تنفيذ البيانات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

isSyncingAllColumns()

تعرِض هذه الدالة ما إذا كان جدول مصدر البيانات يُزامن جميع الأعمدة في مصدر البيانات المرتبط.

الإرجاع

Boolean — True إذا كان جدول مصدر البيانات يُزامن جميع الأعمدة في مصدر البيانات المرتبط، أو false في غير ذلك.

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

refreshData()

تؤدي هذه الطريقة إلى إعادة تحميل بيانات الكائن.

يُعرِض استثناءً إذا كان حاليًا في الحالة error. استخدِم DataSource#updateSpec() لتعديل المواصفة. ويُفضَّل استخدام هذه الطريقة بدلاً من forceRefreshData() لمنع إجراء تعديلات غير متوقّعة على مصدر البيانات.

يُعرِض استثناءً إذا لم يكن نوع مصدر البيانات مفعّلاً. استخدِم طرق SpreadsheetApp#enable...Execution() لتفعيل تنفيذ البيانات لنوع محدّد من مصادر البيانات.

الإرجاع

DataSourceTable: عنصر البيانات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeAllColumns()

تزيل جميع الأعمدة في جدول مصدر البيانات.

الإرجاع

DataSourceTable: جدول مصدر البيانات، للتسلسل

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeAllSortSpecs()

تزيل جميع مواصفات الفرز في جدول مصدر البيانات.

الإرجاع

DataSourceTable: ورقة بيانات المصدر، لإنشاء سلاسل.

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setRowLimit(rowLimit)

تعديل الحد الأقصى للصفوف في جدول مصدر البيانات إذا كان الحد الأقصى للصفوف المقدَّم هو null، يتم تعديل جدول مصدر البيانات لاستخدام الحد الأقصى التلقائي للصفوف كما هو الحال في واجهة مستخدم "جداول بيانات Google".

المعلَمات

الاسمالنوعالوصف
rowLimitIntegerالحدّ الأقصى الجديد للصفوف في جدول البيانات إذا كان null، يتم تعديل الجدول لاستخدام العدد التلقائي للصفوف.

الإرجاع

DataSourceTable: جدول مصدر البيانات، للتسلسل

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

syncAllColumns()

مزامنة جميع الأعمدة الحالية والمستقبلية في مصدر البيانات المرتبط بجدول مصدر البيانات

الإرجاع

DataSourceTable: جدول مصدر البيانات، للتسلسل

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

waitForCompletion(timeoutInSeconds)

تنتظر هذه الدالة حتى اكتمال التنفيذ الحالي، وتنتهي مهلة الانتظار بعد عدد الثواني المقدَّم. يُعرِض استثناءً إذا لم يكتمل التنفيذ عند انتهاء المهلة، ولكنّه لا يلغي تنفيذ البيانات.

المعلَمات

الاسمالنوعالوصف
timeoutInSecondsIntegerوقت الانتظار لتشغيل البيانات، بالثواني ويبلغ الحد الأقصى 300 ثانية.

الإرجاع

DataExecutionStatus: حالة تنفيذ البيانات

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets