أوراق البيانات المرتبطة

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

إدارة مصدر بيانات BigQuery

يستخدم هذا القسم مجموعة البيانات العامة Shakespeare في BigQuery لتوضيح كيفية استخدام "أوراق البيانات المرتبطة". تتضمّن مجموعة البيانات المعلومات التالية:

الحقل النوع الوصف
الكلمة STRING كلمة فريدة واحدة (حيث تكون المسافة البيضاء هي الفاصل) مستخرَجة من مجموعة نصوص
word_count INTEGER عدد المرّات التي تظهر فيها هذه الكلمة في هذه المجموعة من النصوص
مجموعة نصوص STRING العمل الذي تم استخراج هذه الكلمة منه
corpus_date INTEGER تمثّل هذه السمة السنة التي تم فيها نشر هذه المجموعة من النصوص.

إذا كان تطبيقك يطلب أي بيانات من "أوراق البيانات المرتبطة في BigQuery"، يجب أن يقدّم رمز OAuth 2.0 يمنح النطاق bigquery.readonly، بالإضافة إلى النطاقات الأخرى المطلوبة لطلب عادي من Google Sheets API. لمزيد من المعلومات، يُرجى الاطّلاع على اختيار نطاقات Google Sheets API.

يحدّد مصدر البيانات موقعًا خارجيًا يتم فيه العثور على البيانات. بعد ذلك، يتم ربط مصدر البيانات بجدول البيانات.

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

لإضافة مصدر بيانات، يجب توفير AddDataSourceRequest باستخدام الطريقة spreadsheets.batchUpdate. يجب أن يحدّد نص الطلب الحقل dataSource من النوع DataSource object.

"addDataSource":{    "dataSource":{       "spec":{          "bigQuery":{             "projectId":"PROJECT_ID",             "tableSpec":{                "tableProjectId":"bigquery-public-data",                "datasetId":"samples",                "tableId":"shakespeare"             }          }       }    } }

استبدِل PROJECT_ID بمعرّف مشروع صالح في Google Cloud.

بعد إنشاء مصدر بيانات، يتم إنشاء ورقة DATA_SOURCE مرتبطة به لتقديم معاينة لما يصل إلى 500 صف. المعاينة غير متاحة على الفور. يتم تشغيل عملية التنفيذ بشكل غير متزامن لاستيراد بيانات BigQuery.

يتضمّن AddDataSourceResponse الحقول التالية:

  • ‫dataSource: عنصر DataSource الذي تم إنشاؤه dataSourceId هو معرّف فريد على مستوى جدول البيانات. ويتم ملء هذا الحقل والإشارة إليه لإنشاء كل عنصر DataSource من مصدر البيانات.

  • dataExecutionStatus: حالة عملية تنفيذ تستورد بيانات BigQuery إلى ورقة المعاينة. لمزيد من المعلومات، راجِع قسم حالة تنفيذ البيانات.

تعديل مصدر بيانات BigQuery أو حذفه

استخدِم طريقة spreadsheets.batchUpdate وقدِّم طلب UpdateDataSourceRequest أو DeleteDataSourceRequest وفقًا لذلك.

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

بعد إضافة مصدر بيانات إلى جدول البيانات، يمكن إنشاء عنصر مصدر بيانات منه. عنصر مصدر البيانات هو أداة عادية في "جداول بيانات Google"، مثل الجداول المحورية والرسومات البيانية والصيغ، وهي مدمجة مع "أوراق البيانات المرتبطة" لتعزيز تحليل البيانات.

هناك أربعة أنواع من العناصر:

  • جدول DataSource
  • DataSource pivotTable
  • رسم DataSource البياني
  • صيغة DataSource

إضافة جدول مصدر بيانات BigQuery

يُعرف عنصر الجدول باسم "مقتطف" في محرّر "جداول بيانات Google"، وهو يستورد نسخة ثابتة من البيانات من مصدر البيانات إلى "جداول بيانات Google". على غرار الجدول المحوري، يتم تحديد الجدول وتثبيته في الخلية العلوية اليمنى.

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام طريقة spreadsheets.batchUpdate وUpdateCellsRequest لإنشاء جدول مصدر بيانات يتضمّن ما يصل إلى 1000 صف من عمودَين (word وword_count).

"updateCells":{    "rows":{       "values":[          {             "dataSourceTable":{                "dataSourceId":"DATA_SOURCE_ID",                "columns":[                   {                      "name":"word"                   },                   {                      "name":"word_count"                   }                ],                "rowLimit":{                   "value":1000                },                "columnSelectionType":"SELECTED"             }          }       ]    },    "fields":"dataSourceTable" }

استبدِل DATA_SOURCE_ID بمعرّف فريد على مستوى جدول البيانات يحدّد مصدر البيانات.

بعد إنشاء جدول مصدر البيانات، لا تتوفّر البيانات على الفور. في محرّر "جداول بيانات Google"، يظهر كمعاينة. عليك إعادة تحميل جدول مصدر البيانات لجلب بيانات BigQuery. يمكنك تحديد RefreshDataSourceRequest ضمن batchUpdate نفسه. يُرجى العلم أنّ جميع عناصر مصدر البيانات تعمل بطريقة مماثلة. لمزيد من المعلومات، يُرجى الاطّلاع على إعادة تحميل عنصر مصدر بيانات.

بعد اكتمال عملية إعادة التحميل واسترجاع بيانات BigQuery، تتم تعبئة جدول مصدر البيانات كما هو موضّح أدناه:

جدول مصدر البيانات الذي يعرض بيانات من مجموعة البيانات العامة الخاصة بشكسبير

إضافة جدول محوري لمصدر بيانات BigQuery

على عكس الجدول المحوري التقليدي، يستند الجدول المحوري لمصدر البيانات إلى مصدر بيانات ويشير إلى البيانات حسب اسم العمود. يوضّح نموذج الرمز التالي كيفية استخدام الطريقة spreadsheets.batchUpdate وUpdateCellsRequest لإنشاء جدول محوري يعرض إجمالي عدد الكلمات حسب مجموعة النصوص.

"updateCells":{    "rows":{       "values":[          {             "pivotTable":{                "dataSourceId":"DATA_SOURCE_ID",                "rows":{                   "dataSourceColumnReference":{                      "name":"corpus"                   },                   "sortOrder":"ASCENDING"                },                "values":{                   "summarizeFunction":"SUM",                   "dataSourceColumnReference":{                      "name":"word_count"                   }                }             }          }       ]    },    "fields":"pivotTable"     }

استبدِل DATA_SOURCE_ID بمعرّف فريد على مستوى جدول البيانات يحدّد مصدر البيانات.

بعد جلب بيانات BigQuery، تتم تعبئة الجدول المحوري لمصدر البيانات كما هو موضّح أدناه:

جدول محوري لمصدر البيانات يعرض بيانات من مجموعة بيانات Shakespeare العامة

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

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام طريقة spreadsheets.batchUpdate وAddChartRequest لإنشاء رسم بياني لمصدر بيانات مع chartType من COLUMN، يعرض إجمالي عدد الكلمات حسب مجموعة النصوص.

"addChart":{    "chart":{       "spec":{          "title":"Corpus by word count",          "basicChart":{             "chartType":"COLUMN",             "domains":[                {                   "domain":{                      "columnReference":{                         "name":"corpus"                      }                   }                }             ],             "series":[                {                   "series":{                      "columnReference":{                         "name":"word_count"                      },                      "aggregateType":"SUM"                   }                }             ]          }       },       "dataSourceChartProperties":{          "dataSourceId":"DATA_SOURCE_ID"       }    } }

استبدِل DATA_SOURCE_ID بمعرّف فريد على مستوى جدول البيانات يحدّد مصدر البيانات.

بعد جلب بيانات BigQuery، يتم عرض الرسم البياني لمصدر البيانات كما هو موضّح أدناه:

رسم بياني لمصدر البيانات يعرض بيانات من مجموعة بيانات Shakespeare العامة

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

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام طريقة spreadsheets.batchUpdate وUpdateCellsRequest لإنشاء صيغة مصدر بيانات من أجل حساب متوسط عدد الكلمات.

"updateCells":{    "rows":[       {          "values":[             {                "userEnteredValue":{                   "formulaValue":"=AVERAGE(shakespeare!word_count)"                }             }          ]       }    ],    "fields":"userEnteredValue" }

بعد جلب بيانات BigQuery، يتم ملء صيغة مصدر البيانات كما هو موضّح:

صيغة مصدر البيانات التي تعرض بيانات من مجموعة بيانات Shakespeare العامة

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

يمكنك إعادة تحميل عنصر مصدر البيانات لجلب أحدث البيانات من BigQuery استنادًا إلى مواصفات مصدر البيانات الحالية وإعدادات العنصر. يمكنك استخدام الطريقة spreadsheets.batchUpdate لطلب البيانات من RefreshDataSourceRequest. بعد ذلك، حدِّد مرجعًا واحدًا أو أكثر للكائنات التي تريد إعادة تحميلها باستخدام الكائن DataSourceObjectReferences.

يُرجى العِلم أنّه يمكنك إنشاء عناصر مصدر البيانات وإعادة تحميلها ضمن طلب batchUpdate واحد.

إدارة مصدر بيانات Looker

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

سيعيد تطبيقك الذي يطلب أي بيانات من "جداول بيانات Looker المرتبطة" استخدام رابط حسابك الحالي على Google مع Looker.

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

لإضافة مصدر بيانات، يجب توفير AddDataSourceRequest باستخدام الطريقة spreadsheets.batchUpdate. يجب أن يحدّد نص الطلب الحقل dataSource من النوع DataSource object.

"addDataSource":{    "dataSource":{       "spec":{          "looker":{             "instance_uri":"INSTANCE_URI",             "model":"MODEL",             "explore":"EXPLORE"          }       }    } }

استبدِل INSTANCE_URI وMODEL وEXPLORE بمعرّف موارد منتظم (URI) صالح لمثيل Looker واسم نموذج واسم استكشاف على التوالي.

بعد إنشاء مصدر بيانات، يتم إنشاء ورقة DATA_SOURCE مرتبطة به لتقديم معاينة لبنية الاستكشاف المحدّد، بما في ذلك طرق العرض والسمات والمقاييس وأي أوصاف للحقول.

يتضمّن AddDataSourceResponse الحقول التالية:

  • ‫dataSource: عنصر DataSource الذي تم إنشاؤه dataSourceId هو معرّف فريد على مستوى جدول البيانات. يتم ملء هذا الحقل والإشارة إليه لإنشاء كل عنصر DataSource من مصدر البيانات.

  • dataExecutionStatus: حالة عملية تنفيذ تستورد بيانات BigQuery إلى ورقة المعاينة. لمزيد من المعلومات، راجِع قسم حالة تنفيذ البيانات.

تعديل مصدر بيانات Looker أو حذفه

استخدِم طريقة spreadsheets.batchUpdate وقدِّم طلب UpdateDataSourceRequest أو DeleteDataSourceRequest وفقًا لذلك.

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

بعد إضافة مصدر بيانات إلى جدول البيانات، يمكن إنشاء عنصر مصدر بيانات منه. بالنسبة إلى مصادر بيانات Looker، يمكنك إنشاء عنصر DataSource pivotTable منها فقط.

لا يمكن إنشاء DataSource صيغ ومقتطفات ورسوم بيانية من مصادر بيانات Looker.

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

يمكنك إعادة تحميل عنصر مصدر البيانات لجلب أحدث البيانات من Looker استنادًا إلى مواصفات مصدر البيانات الحالية وإعدادات العنصر. يمكنك استخدام الطريقة spreadsheets.batchUpdate لطلب البيانات من RefreshDataSourceRequest. بعد ذلك، حدِّد مرجعًا واحدًا أو أكثر للكائنات التي تريد إعادة تحميلها باستخدام الكائن DataSourceObjectReferences.

يُرجى العِلم أنّه يمكنك إنشاء عناصر مصدر البيانات وإعادة تحميلها ضمن طلب batchUpdate واحد.

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

عند إنشاء مصادر بيانات أو إعادة تحميل عناصر مصدر البيانات، يتم إنشاء عملية تنفيذ في الخلفية لجلب البيانات من BigQuery أو Looker وعرض ردّ يتضمّن DataExecutionStatus. في حال بدء التنفيذ بنجاح، يكون DataExecutionState عادةً في الحالة RUNNING.

بما أنّ العملية غير متزامنة، يجب أن يطبّق تطبيقك نموذج استطلاع للاسترداد الدوري لحالة عناصر مصدر البيانات. استخدِم طريقة spreadsheets.get إلى أن تعرض الحالة إما SUCCEEDED أو FAILED. يكتمل التنفيذ بسرعة في معظم الحالات، ولكن يعتمد ذلك على مدى تعقيد مصدر البيانات. لا يستغرق التنفيذ عادةً أكثر من 10 دقائق.