Class DataSourceTable

DataSourceTable

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

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

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

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