صفحات متصل

کاربرگ‌نگار متصل به شما امکان می‌دهد تا پتابایت داده را مستقیماً در 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 دقیقه نیست.