کاربرگنگار متصل به شما امکان میدهد تا پتابایت داده را مستقیماً در Google Sheets تجزیه و تحلیل کنید. میتوانید صفحات گسترده خود را به یک انبار داده BigQuery متصل کنید و با استفاده از ابزار Sheets آشنا مانند جداول محوری، نمودارها و فرمولها تجزیه و تحلیل را انجام دهید.
این راهنما از مجموعه داده عمومی Shakespeare
برای نشان دادن نحوه استفاده از صفحات متصل استفاده می کند. مجموعه داده حاوی اطلاعات زیر است:
رشته | تایپ کنید | شرح |
---|---|---|
کلمه | STRING | یک کلمه منحصر به فرد (که در آن فضای سفید جداکننده است) که از یک پیکره استخراج شده است. |
تعداد کلمه | INTEGER | تعداد دفعاتی که این کلمه در این مجموعه ظاهر می شود. |
مجموعه نوشته ها | STRING | اثری که این کلمه از آن استخراج شده است. |
corpus_date | INTEGER | سالی که این مجموعه در آن منتشر شد. |
اگر برنامه شما هر گونه داده کاربرگنگار متصل را درخواست میکند، باید یک نشانه OAuth 2.0 ارائه کند که به bigquery.readonly
دامنه میدهد، علاوه بر سایر حوزههای مورد نیاز برای یک درخواست API معمولی 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
ارائه دهید.
مدیریت اشیاء منبع داده
هنگامی که یک منبع داده به صفحه گسترده اضافه می شود، می توان یک شی منبع داده از آن ایجاد کرد. یک شی منبع داده یک ابزار Sheets معمولی مانند جداول محوری، نمودارها و فرمولها است که برای تجزیه و تحلیل دادههای شما با صفحات متصل ادغام شده است.
چهار نوع اشیاء وجود دارد:
- جدول
DataSource
- جدول محوری
DataSource
- نمودار
DataSource
- فرمول
DataSource
یک جدول منبع داده اضافه کنید
شی جدول که به عنوان "عصاره" در ویرایشگر Sheets شناخته می شود، تخلیه ایستا از داده ها را از منبع داده به Sheets وارد می کند. مانند جدول محوری، جدول مشخص شده و به سلول بالا سمت چپ متصل می شود.
نمونه کد زیر نحوه استفاده از روش 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 با یک شناسه منحصر به فرد با محدوده صفحه گسترده که منبع داده را شناسایی می کند، جایگزین کنید.
پس از ایجاد جدول منبع داده، داده ها فوراً در دسترس نیستند. در ویرایشگر Sheets، به صورت پیشنمایش نشان داده میشود. برای واکشی داده های BigQuery باید جدول منبع داده را بازخوانی کنید. می توانید یک RefreshDataSourceRequest
در همان batchUpdate
تعیین کنید. توجه داشته باشید که تمام اشیاء منبع داده به طور مشابه کار می کنند. برای اطلاعات بیشتر، به تازه کردن یک شی منبع داده مراجعه کنید.
پس از تکمیل بهروزرسانی و واکشی دادههای BigQuery، جدول منبع داده مطابق شکل پر میشود:
یک PivotTable منبع داده اضافه کنید
برخلاف جدول محوری معمولی، جدول محوری منبع داده توسط یک منبع داده پشتیبانی می شود و داده ها را با نام ستون ارجاع می دهد. نمونه کد زیر نحوه استفاده از روش 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
of 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 دقیقه نیست.
مطالب مرتبط
- دامنههای API کاربرگنگار Google را انتخاب کنید
- با داده های BigQuery در Google Sheets شروع کنید
- مستندات BigQuery
- BigQuery: استفاده از صفحات متصل
- فیلم آموزشی Connected Sheets