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

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

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

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

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

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

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

إضافة مصدر بيانات 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 صف. لا تتوفر المعاينة على الفور. يتم تشغيل التنفيذ بشكلٍ غير متزامن لاستيراد بيانات BigQuery.

تحتوي AddDataSourceResponse على الحقول التالية:

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

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

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

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

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

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

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

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

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

يُعرف باسم "الاستخراج" في محرر جداول البيانات، ويستورد كائن الجدول تفريغًا ثابتًا للبيانات من مصدر البيانات إلى "جداول البيانات". على غرار الجدول المحوري، يتم تحديد الجدول وتثبيته في الخلية العلوية اليسرى.

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

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

بعد اكتمال إعادة التحميل واسترجاع بيانات 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، تتم تعبئة الجدول المحوري لمصدر البيانات كما هو موضّح:

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

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

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

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

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

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

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

بعد استرجاع بيانات BigQuery، تتم تعبئة صيغة مصدر البيانات على النحو التالي:

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

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

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

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

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

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

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