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|nullتعرض هذه السمة الحد الأقصى لعدد الصفوف في جدول مصدر البيانات.
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: الحد الأقصى لعدد الصفوف في جدول مصدر البيانات، أو 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