صفحات متصل

کاربرگ‌نگار متصل به شما امکان می‌دهد تا پتابایت داده را مستقیماً در Google Sheets تجزیه و تحلیل کنید. می توانید صفحات گسترده خود را با یک انبار داده BigQuery یا Looker متصل کنید و با استفاده از ابزار Sheets آشنا مانند جداول محوری، نمودارها و فرمول ها تجزیه و تحلیل را انجام دهید.

یک منبع داده BigQuery را مدیریت کنید

این بخش از مجموعه داده عمومی Shakespeare BigQuery استفاده می کند تا نحوه استفاده از صفحات متصل را نشان دهد. مجموعه داده حاوی اطلاعات زیر است:

میدان تایپ کنید توضیحات
کلمه STRING یک کلمه منحصر به فرد (که در آن فضای سفید جداکننده است) که از یک پیکره استخراج شده است.
word_count INTEGER تعداد دفعاتی که این کلمه در این مجموعه ظاهر می شود.
بدنه STRING اثری که این کلمه از آن استخراج شده است.
corpus_date INTEGER سالی که این مجموعه در آن منتشر شد.

اگر برنامه شما هر گونه داده BigQuery Connected Sheets را درخواست می کند، باید یک نشانه OAuth 2.0 ارائه دهد که به bigquery.readonly دامنه می دهد، علاوه بر سایر حوزه های مورد نیاز برای یک درخواست معمولی Google Sheets API. برای اطلاعات بیشتر، به انتخاب حوزه‌های 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 را به صفحه پیش نمایش وارد می کند. برای اطلاعات بیشتر به بخش وضعیت اجرای داده ها مراجعه کنید.

منبع داده BigQuery را به‌روزرسانی یا حذف کنید

از روش spreadsheets.batchUpdate استفاده کنید و بر این اساس یک درخواست UpdateDataSourceRequest یا DeleteDataSourceRequest ارائه دهید.

اشیاء منبع داده BigQuery را مدیریت کنید

هنگامی که یک منبع داده به صفحه گسترده اضافه می شود، می توان یک شی منبع داده از آن ایجاد کرد. یک شی منبع داده یک ابزار Sheets معمولی مانند جداول محوری، نمودارها و فرمول‌ها است که برای تجزیه و تحلیل داده‌های شما با صفحات متصل ادغام شده است.

چهار نوع اشیاء وجود دارد:

  • جدول DataSource
  • جدول محوری DataSource
  • نمودار DataSource
  • فرمول DataSource

یک جدول منبع داده BigQuery اضافه کنید

شی جدول که به عنوان "عصاره" در ویرایشگر 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 منبع داده 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 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، نمودار منبع داده مطابق شکل ارائه می‌شود:

نمودار منبع داده که داده های عمومی شکسپیر را نشان می دهد مجموعه داده

یک فرمول منبع داده BigQuery اضافه کنید

نمونه کد زیر نحوه استفاده از روش spreadsheets.batchUpdate و UpdateCellsRequest برای ایجاد فرمول منبع داده برای محاسبه میانگین تعداد کلمات نشان می دهد.

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

پس از واکشی داده‌های BigQuery، فرمول منبع داده مطابق شکل پر می‌شود:

فرمول منبع داده که داده‌های عمومی شکسپیر را نشان می‌دهد مجموعه داده

یک شی منبع داده BigQuery را بازخوانی کنید

می‌توانید یک شی منبع داده را بازخوانی کنید تا آخرین داده‌ها را از BigQuery بر اساس مشخصات منبع داده فعلی و پیکربندی‌های شی دریافت کنید. می توانید از روش spreadsheets.batchUpdate برای فراخوانی RefreshDataSourceRequest استفاده کنید. سپس یک یا چند مرجع شی را با استفاده از شی DataSourceObjectReferences برای بازخوانی مشخص کنید.

توجه داشته باشید که هم می‌توانید اشیاء منبع داده را در یک درخواست batchUpdate ایجاد کنید و هم آن‌ها را بازخوانی کنید.

یک منبع داده Looker را مدیریت کنید

این راهنما نحوه افزودن منبع داده Looker، به روز رسانی یا حذف آن، ایجاد جدول محوری روی آن و بازخوانی آن را نشان می دهد.

برنامه شما که هر گونه داده Looker Connected Sheets را درخواست می کند، از پیوند حساب 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 استفاده کنید و بر این اساس یک درخواست UpdateDataSourceRequest یا DeleteDataSourceRequest ارائه دهید.

اشیاء منبع داده Looker را مدیریت کنید

هنگامی که یک منبع داده به صفحه گسترده اضافه می شود، می توان یک شی منبع داده از آن ایجاد کرد. برای منابع داده Looker، فقط می توانید یک شیء PivotTable DataSource از آن ایجاد کنید.

ایجاد فرمول ها، استخراج ها و نمودارهای DataSource از منابع داده Looker امکان پذیر نیست.

یک شی منبع داده Looker را بازخوانی کنید

می‌توانید یک شی منبع داده را بازخوانی کنید تا آخرین داده‌ها را از Looker بر اساس مشخصات منبع داده فعلی و پیکربندی‌های شی دریافت کنید. می توانید از روش spreadsheets.batchUpdate برای فراخوانی RefreshDataSourceRequest استفاده کنید. سپس یک یا چند مرجع شی را با استفاده از شی DataSourceObjectReferences برای بازخوانی مشخص کنید.

توجه داشته باشید که هم می‌توانید اشیاء منبع داده را در یک درخواست batchUpdate ایجاد کنید و هم آن‌ها را بازخوانی کنید.

وضعیت اجرای داده ها

هنگامی که منابع داده را ایجاد می کنید یا اشیاء منبع داده را بازخوانی می کنید، یک اجرای پس زمینه برای واکشی داده ها از BigQuery یا Looker ایجاد می شود و پاسخی حاوی DataExecutionStatus را برمی گرداند. اگر اجرا با موفقیت شروع شود، DataExecutionState معمولا در حالت RUNNING است.

از آنجایی که فرآیند ناهمزمان است، برنامه شما باید یک مدل نظرسنجی را برای بازیابی دوره ای وضعیت اشیاء منبع داده پیاده سازی کند. از روش spreadsheets.get استفاده کنید تا وضعیت به حالت SUCCEEDED یا FAILED برگردد. در اکثر موارد اجرا به سرعت کامل می شود، اما این به پیچیدگی منبع داده شما بستگی دارد. معمولاً اجرا بیش از 10 دقیقه نیست.