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

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

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

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

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

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

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

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

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

استخدِم الـ spreadsheets.batchUpdate method وقدِّم طلب 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

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

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

إضافة رسم بياني لمصدر بيانات 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 عنصر.

"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 method وقدِّم طلب 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 دقائق.