Class DataSourceTable

DataSourceTable

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

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

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

SpreadsheetApp.enableBigQueryExecution();
var spreadsheet = SpreadsheetApp.getActive();
var 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.
var dataSheet = spreadsheet.insertSheetWithDataSourceTable(spec);
var 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();
var dataSheet = SpreadsheetApp.getActive().getSheetByName("Data Sheet 1");
var dataSourceTable = dataSheet.getDataSourceTables()[0];
var dataSource = dataSourceTable.getDataSource();
var 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