استخدام "أوراق البيانات المرتبطة"

أوراق البيانات المرتبطة هي إحدى ميزات "جداول بيانات Google" التي تتيح لك تحليل بيانات BigQuery وLooker مباشرةً في "جداول بيانات Google". يمكنك الوصول إلى "أوراق البيانات المرتبطة" آليًا باستخدام خدمة "جداول بيانات Google".

الإجراءات الشائعة في "أوراق البيانات المرتبطة"

استخدِم فئات DataSource وعناصر للربط بخدمة BigQuery أو Looker وتحليل البيانات. يسرد الجدول التالي الإجراءات الأكثر شيوعًا وكيفية إنشائها في "برمجة تطبيقات Google":DataSource

الإجراء	فئة برمجة تطبيقات	طريقة الاستخدام
ربط ورقة بيانات بمصدر بيانات متوافق	`DataSourceSpec`	`SpreadsheetApp.newDataSourceSpec()`
يُرجى اختيار مصدر بيانات	`DataSource`	`Spreadsheet.insertDataSourceSheet().getDataSource()`
إضافة ورقة مصدر بيانات	`DataSourceSheet`	`Spreadsheet.insertDataSourceSheet()`
إضافة جدول محوري	`DataSourcePivotTable`	`Range.insertDataSourcePivotTable()`
سحب البيانات إلى استخراج	`DataSourceTable`	`Range.insertDataSourceTable()`
استخدام صيغة	`DataSourceFormula`	`Range.setFormula()`
إضافة رسم بياني	`DataSourceChart`	`Sheet.insertDataSourceChart()`

إضافة نطاقات الأذونات المطلوبة

للوصول إلى بيانات BigQuery، أدرِج طريقة enableBigQueryExecution() في رمز برمجة تطبيقات. تضيف هذه الطريقة نطاق OAuth bigquery.readonly المطلوب إلى مشروع "برمجة التطبيقات".

يعرض المثال التالي طريقة SpreadsheetApp.enableBigQueryExecution() التي يتم استدعاؤها ضمن دالة:

function addDataSource() {
  SpreadsheetApp.enableBigQueryExecution();
  var spreadsheet = SpreadsheetApp.getActive();
  }

للوصول إلى بيانات Looker، أدرِج طريقة enableLookerExecution() في رمز برمجة تطبيقات. عند الوصول إلى Looker في برمجة تطبيقات، تتم إعادة استخدام رابط حسابك الحالي على Google مع Looker.

يعرض المثال التالي طريقة SpreadsheetApp.enableLookerExecution() التي يتم استدعاؤها ضمن دالة:

function addDataSource() {
  SpreadsheetApp.enableLookerExecution();
  var spreadsheet = SpreadsheetApp.getActive();
  }

إضافة نطاقات OAuth إضافية إلى ملف البيان

عند الربط بـ BigQuery، تتم إضافة معظم نطاقات OAuth تلقائيًا إلى ملف البيان استنادًا إلى الدوال المستخدَمة في الرمز البرمجي. إذا كنت بحاجة إلى نطاقات إضافية للوصول إلى بيانات BigQuery معيّنة، يمكنك ضبط نطاقات صريحة.

على سبيل المثال، للاستعلام عن بيانات BigQuery المستضافة ضمن Google Drive، عليك إضافة نطاق OAuth في Drive إلى ملف البيان.

يعرض المثال التالي جزء oauthScopes من ملف البيان. يضيف نطاق OAuth في Drive بالإضافة إلى نطاقَي OAuth spreadsheet وbigquery.readonly المطلوبَين كحد أدنى:

{ ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/bigquery.readonly",
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/drive" ],
... }

مثال: إنشاء عنصر مصدر بيانات وإعادة تحميله

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

إضافة مصدر بيانات

تعرض الأمثلة التالية كيفية إضافة مصدر بيانات BigQuery ومصدر بيانات Looker على التوالي.

BigQuery

لإضافة مصدر بيانات BigQuery إلى جدول بيانات، أدرِج ورقة مصدر بيانات تتضمّن مواصفات مصدر بيانات. يتم تلقائيًا إعادة تحميل ورقة مصدر البيانات لجلب بيانات المعاينة.

استبدِل <YOUR_PROJECT_ID> أدناه برقم تعريف مشروع صالح في Google Cloud.

// For operations that fetch data from BigQuery, enableBigQueryExecution() must be called.
SpreadsheetApp.enableBigQueryExecution();
var spreadsheet = SpreadsheetApp.create('Test connected sheets');
Logger.log('New test spreadsheet: %s', spreadsheet.getUrl());

// Build data source spec by selecting a table.
var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
    .asBigQuery()
    .setProjectId('<YOUR_PROJECT_ID>')
    .setTableProjectId('bigquery-public-data')
    .setDatasetId('ncaa_basketball')
    .setTableId('mbb_historical_tournament_games')
    .build();
// Add data source and its associated data source sheet.
var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
var dataSource = dataSourceSheet.getDataSource();

Looker

لإضافة مصدر بيانات Looker إلى جدول بيانات، أدرِج ورقة مصدر بيانات تتضمّن مواصفات مصدر البيانات. يتم تلقائيًا إعادة تحميل ورقة مصدر البيانات لجلب بيانات المعاينة.

استبدِل <INSTANCE_URL> و<MODEL_NAME> و<EXPLORE_NAME> في المثال التالي بعنوان URL صالح لمثيل Looker واسم نموذج واسم استكشاف على التوالي.

// For operations that fetch data from Looker, enableLookerExecution() must be called.
SpreadsheetApp.enableLookerExecution();
var spreadsheet = SpreadsheetApp.create('Test connected sheets');
Logger.log('New test spreadsheet: %s', spreadsheet.getUrl());

// Build data source spec by selecting a table.
var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
    .asLooker()
    .setInstanceUrl('<INSTANCE_URL>')
    .setModelName('<MODEL_NAME>')
    .setExploreName('<EXPLORE_NAME>')
    .build();
// Add data source and its associated data source sheet.
var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
var dataSource = dataSourceSheet.getDataSource();

إضافة عنصر مصدر بيانات

بعد إضافة مصدر البيانات إلى جدول البيانات، يمكن إنشاء عناصر مصدر البيانات من مصدر البيانات. في هذا المثال، يتم إنشاء جدول محوري باستخدام DataSourcePivotTable في dataSource BigQuery الذي تم إنشاؤه في عينة التعليمات البرمجية التي تضيف مصدر بيانات BigQuery.

على عكس البيانات العادية في جداول الشبكة التي تتم الإشارة إليها من خلال فهرس الخلية أو رموز A1، تتم الإشارة إلى البيانات من مصادر البيانات عادةً من خلال أسماء الأعمدة. لذلك، تستخدم معظم أدوات ضبط المواقع الإلكترونية في عناصر مصدر البيانات اسم العمود كإدخال.

var rootCell = spreadsheet.insertSheet('pivotTableSheet').getRange('A1');

// Add data source pivot table and set data source specific configurations.
var dataSourcePivotTable = rootCell.createDataSourcePivotTable(dataSource);
var rowGroup = dataSourcePivotTable.addRowGroup('season');
rowGroup.sortDescending().setGroupLimit(5);
dataSourcePivotTable.addColumnGroup('win_school_ncaa');
dataSourcePivotTable.addPivotValue('win_pts',
SpreadsheetApp.PivotTableSummarizeFunction.AVERAGE);
dataSourcePivotTable.addPivotValue('game_date',
SpreadsheetApp.PivotTableSummarizeFunction.COUNTA);
var filterCriteria = SpreadsheetApp.newFilterCriteria()
    .whenTextEqualToAny(['Duke', 'North Carolina'])
    .build();
dataSourcePivotTable.addFilter('win_school_ncaa', filterCriteria);

// Get a regular pivot table instance and set shared configurations.
var pivotTable = dataSourcePivotTable.asPivotTable();
pivotTable.setValuesDisplayOrientation(SpreadsheetApp.Dimension.ROWS);

إعادة تحميل عنصر مصدر بيانات

أعِد تحميل عناصر مصدر البيانات لجلب أحدث البيانات من BigQuery استنادًا إلى مواصفات مصدر البيانات وإعدادات العناصر.

عملية إعادة تحميل البيانات غير متزامنة. لإعادة تحميل عنصر مصدر بيانات، استخدِم الطرق التالية:

يبدأ refreshData() عملية تنفيذ إعادة تحميل البيانات.
تعرض waitForCompletion() الحالة النهائية بعد اكتمال تنفيذ البيانات. يغنيك ذلك عن الحاجة إلى مواصلة طلب حالة التنفيذ.
يحصل DataExecutionStatus.getErrorCode() على رمز الخطأ في حال تعذّر تنفيذ البيانات.

يوضّح المثال التالي عملية إعادة تحميل بيانات الجدول المحوري:

var status = dataSourcePivotTable.getStatus();
Logger.log('Initial state: %s', status.getExecutionState());

dataSourcePivotTable.refreshData();

status = dataSourcePivotTable.waitForCompletion(/* timeoutInSeconds= */ 60);
Logger.log('Ending state: %s', status.getExecutionState());
if (status.getExecutionState() == SpreadsheetApp.DataExecutionState.ERROR) {
  Logger.log('Error: %s (%s)', status.getErrorCode(),
  status.getErrorMessage());
}

استخدام المشغّلات مع "أوراق البيانات المرتبطة"

يمكنك تشغيل وظائف مصدر بيانات "جداول البيانات المرتبطة" تلقائيًا باستخدام المشغّلات والأحداث. على سبيل المثال، استخدِم المشغّلات المستندة إلى الوقت لإعادة تحميل عناصر مصدر البيانات بشكل متكرّر في وقت محدّد، واستخدِم مشغّلات الأحداث في جدول البيانات لتشغيل تنفيذ البيانات عند وقوع حدث محدّد مسبقًا.

يضيف المثال التالي مصدر بيانات BigQuery مع مَعلمة طلب بحث، ويعيد تحميل ورقة مصدر البيانات عند تعديل مَعلمة طلب البحث.

استبدِل <YOUR_PROJECT_ID> برقم تعريف مشروع صالح على Google Cloud.

// Add data source with query parameter.
function addDataSource() {
  SpreadsheetApp.enableBigQueryExecution();
  var spreadsheet = SpreadsheetApp.getActive();

  // Add a new sheet and use A1 cell as the parameter cell.
  var parameterCell = spreadsheet.insertSheet('parameterSheet').getRange('A1');
  parameterCell.setValue('Duke');

  // Add data source with query parameter.
  var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
      .asBigQuery()
      .setProjectId('<YOUR_PROJECT_ID>')
      .setRawQuery('select * from `bigquery-public-data`.`ncaa_basketball`.`mbb_historical_tournament_games` WHERE win_school_ncaa = @SCHOOL')
      .setParameterFromCell('SCHOOL', 'parameterSheet!A1')
      .build();
  var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
  dataSourceSheet.asSheet().setName('ncaa_data');
}

// Function used to configure event trigger to refresh data source sheet.
function refreshOnParameterEdit(e) {
  var editedRange = e.range;
  if (editedRange.getSheet().getName() != 'parameterSheet') {
    return;
  }
  // Check that the edited range includes A1.
  if (editedRange.getRow() > 1 || editedRange.getColumn() > 1) {
     return;
  }

  var spreadsheet = e.source;
  SpreadsheetApp.enableBigQueryExecution();
  spreadsheet.getSheetByName('ncaa_data').asDataSourceSheet().refreshData();
}

في المثال السابق، تضيف الدالة addDataSource() مصدر بيانات إلى جدول البيانات. بعد تنفيذ addDataSource()، أنشئ مشغّلاً للأحداث في أداة تعديل النصوص البرمجية. لمعرفة كيفية إنشاء مشغّل حدث، اطّلِع على مقالة المشغّلات القابلة للتثبيت.

حدِّد الخيارات التالية للمشغّل:

مصدر الحدث: من جدول بيانات
نوع الحدث: عند التعديل
الدالة المطلوب تنفيذها: refreshOnParameterEdit

بعد إنشاء المشغّل، يتم تلقائيًا إعادة تحميل ورقة مصدر البيانات في كل مرة يتم فيها تعديل خلية المَعلمة.

تحديد المشاكل وحلّها

رسالة الخطأ الدقة

استخدِم enableBigQuery() لتفعيل عمليات تنفيذ البيانات لمصادر البيانات من النوع BIGQUERY. يشير هذا الخطأ إلى أنّه لم يتم استدعاء SpreadsheetApp.enableBigQueryExecution() قبل جلب بيانات BigQuery.
استدعاء SpreadsheetApp.enableBigQueryExecution() في الدوال التي تستخدم طرقًا لتنفيذ BigQuery
مثل refreshData() في عناصر مصدر البيانات، Spreadsheet.insertDataSourceTable()، و DataSource.updateSpec().
تتطلّب هذه الطرق نطاق OAuth إضافيًا bigquery.readonly لتعمل.

لا يُسمح باتخاذ إجراءات بشأن مصادر البيانات.
يُرجى التواصل مع المشرف لتفعيل الميزة. يشير هذا الخطأ إلى أنّ ميزة "جداول بيانات مرتبطة" غير مفعّلة في الحساب.
لا تتوفّر ميزة "جداول بيانات مرتبطة" إلا لمستخدمي Google Workspace الذين لديهم اشتراكات معيّنة.
يُرجى التواصل مع المشرف لتفعيل الميزة.

رسالة الخطأ	الدقة
استخدِم `enableBigQuery()` لتفعيل عمليات تنفيذ البيانات لمصادر البيانات من النوع BIGQUERY.	يشير هذا الخطأ إلى أنّه لم يتم استدعاء `SpreadsheetApp.enableBigQueryExecution()` قبل جلب بيانات BigQuery. استدعاء `SpreadsheetApp.enableBigQueryExecution()` في الدوال التي تستخدم طرقًا لتنفيذ BigQuery مثل `refreshData()` في عناصر مصدر البيانات، `Spreadsheet.insertDataSourceTable()`، و `DataSource.updateSpec()`. تتطلّب هذه الطرق نطاق OAuth إضافيًا bigquery.readonly لتعمل.
لا يُسمح باتخاذ إجراءات بشأن مصادر البيانات. يُرجى التواصل مع المشرف لتفعيل الميزة.	يشير هذا الخطأ إلى أنّ ميزة "جداول بيانات مرتبطة" غير مفعّلة في الحساب. لا تتوفّر ميزة "جداول بيانات مرتبطة" إلا لمستخدمي Google Workspace الذين لديهم اشتراكات معيّنة. يُرجى التواصل مع المشرف لتفعيل الميزة.

استخدام "أوراق البيانات المرتبطة" تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.