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

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

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

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

الحقل النوع الوصف
الكلمة 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.

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

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

بعد إنشاء مصدر بيانات، يتم إنشاء جدول مرتبط DATA_SOURCE لتوفير معاينة لما يصل إلى 500 صف. لا تتوفّر المعاينة على الفور. يتم بدء التنفيذ بشكل غير متزامن لاستيراد data 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، تتم تعبئة جدول مصدر البيانات كما هو موضّح:

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

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

على عكس الجدول المحوري التقليدي، يستند الجدول المحوري لمصدر البيانات إلى مصدر data ويشير إلى البيانات حسب اسم العمود. يوضّح نموذج الرمز التالي كيفية استخدام طريقة 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 من العمود، ويعرض إجمالي عدد الكلمات حسب النصوص.

"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.

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

استبدِل INSTANCE_URI وMODEL و EXPLORE بمعرّف موارد منتظم صالح لمثيل 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 دقائق.