גיליונות מקושרים

גיליונות מקושרים מאפשרים לכם לנתח כמויות נתונים אדירות (ברמת פטה-בייט) ישירות ב-Google Sheets. אתם יכולים לקשר את הגיליונות האלקטרוניים למחסן הנתונים של BigQuery או ל-Looker ולבצע את הניתוח באמצעות הכלים המוכרים של Sheets, כמו טבלאות צירים, תרשימים ונוסחאות.

ניהול מקור נתונים ב-BigQuery

בקטע הזה נסביר איך להשתמש בגיליונות מקושרים באמצעות מערך הנתונים הציבורי Shakespeare ב-BigQuery. מערך הנתונים מכיל את הפרטים הבאים:

שדה סוג תיאור
מילים STRING מילה ייחודית אחת (שבה רווחים לבנים הם התו המפריד) שחולצה ממאגר טקסטים.
word_count INTEGER מספר הפעמים שהמילה הזו מופיעה בקובץ הטקסט הזה.
קורפוס STRING היצירה שממנה המילה הזו הופקה.
corpus_date INTEGER השנה שבה פורסם הקורפוס הזה.

אם האפליקציה שלכם מבקשת נתונים של גיליונות מקושרים ב-BigQuery, היא צריכה לספק אסימון OAuth 2.0 שמעניק הרשאת גישה ברמת bigquery.readonly, בנוסף להרשאות הגישה האחרות שנדרשות לבקשת API רגילה של Google Sheets. למידע נוסף, ראו בחירת היקפי הרשאה ל-Google Sheets API.

מקור נתונים מציין מיקום חיצוני שבו נמצאים הנתונים. לאחר מכן, מקור הנתונים מחובר לגיליון האלקטרוני.

הוספת מקור נתונים של 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

משתמשים ב-method‏ spreadsheets.batchUpdate ומספקים בקשה מסוג UpdateDataSourceRequest או DeleteDataSourceRequest בהתאם.

ניהול אובייקטים של מקורות נתונים ב-BigQuery

אחרי שמוסיפים מקור נתונים לגיליון האלקטרוני, אפשר ליצור ממנו אובייקט של מקור נתונים. אובייקט של מקור נתונים הוא כלי רגיל ב-Sheets, כמו טבלאות צירים, תרשימים ונוסחאות, שמשולב עם גיליונות מקושרים כדי לשפר את ניתוח הנתונים.

יש ארבעה סוגים של אובייקטים:

  • טבלה של DataSource
  • DataSource pivotTable
  • תרשים של DataSource
  • נוסחה של DataSource

הוספת טבלה של מקור נתונים ב-BigQuery

אובייקט הטבלה, שנקרא 'חילוץ' בעורך של Sheets, מייבא גרסת dump סטטית של נתונים ממקור הנתונים אל Sheets. בדומה לטבלת צירים, הטבלה מצוינה ומקובעת לתא הימני העליון.

בדוגמת הקוד הבאה מוסבר איך להשתמש בשיטה spreadsheets.batchUpdate וב-UpdateCellsRequest כדי ליצור טבלה של מקור נתונים עם עד 1,000 שורות של שתי עמודות (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 מאוחסים, טבלת מקור הנתונים מאוכלסת באופן הבא:

טבלה של מקור נתונים שמציגה נתונים ממערך הנתונים הציבורי של שייקספיר.

הוספת טבלת צירים של מקור נתונים ב-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 מסתיים, התרשים של מקור הנתונים מוצג באופן הבא:

תרשים של מקור נתונים שמוצגים בו נתונים ממערך הנתונים הציבורי של שייקספיר.

הוספת נוסחה של מקור נתונים ב-BigQuery

בדוגמת הקוד הבאה מוסבר איך להשתמש בשיטה spreadsheets.batchUpdate וב-UpdateCellsRequest כדי ליצור נוסחה של מקור נתונים לחישוב מספר המילים הממוצע.

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

אחרי שאחזור הנתונים מ-BigQuery מסתיים, הנוסחה של מקור הנתונים מאוכלסת באופן הבא:

נוסחה של מקור נתונים שמציגה נתונים ממערך הנתונים הציבורי של שייקספיר.

רענון אובייקט של מקור נתונים ב-BigQuery

אפשר לרענן אובייקט של מקור נתונים כדי לאחזר את הנתונים האחרונים מ-BigQuery, על סמך המפרטים הנוכחיים של מקור הנתונים וההגדרות של האובייקט. אפשר להשתמש ב-method‏ 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

משתמשים ב-method‏ spreadsheets.batchUpdate ומספקים בקשה מסוג UpdateDataSourceRequest או DeleteDataSourceRequest בהתאם.

ניהול אובייקטים של מקורות נתונים ב-Looker

אחרי שמוסיפים מקור נתונים לגיליון האלקטרוני, אפשר ליצור ממנו אובייקט של מקור נתונים. במקורות נתונים של Looker, אפשר ליצור מהם רק אובייקט pivotTable‏ DataSource.

אי אפשר ליצור נוסחאות, חילוצים ותרשימים של DataSource ממקורות הנתונים של Looker.

רענון אובייקט של מקור נתונים ב-Looker

אפשר לרענן אובייקט של מקור נתונים כדי לאחזר את הנתונים העדכניים ביותר מ-Looker, על סמך המפרטים הנוכחיים של מקור הנתונים וההגדרות של האובייקט. אפשר להשתמש ב-method‏ spreadsheets.batchUpdate כדי להפעיל את RefreshDataSourceRequest. לאחר מכן מציינים הפניה לאובייקט אחד או יותר שרוצים לרענן באמצעות האובייקט DataSourceObjectReferences.

שימו לב שאפשר ליצור אובייקטים של מקורות נתונים ולרענן אותם בבקשה batchUpdate אחת.

סטטוס ביצוע הנתונים

כשיוצרים מקורות נתונים או מרעננים אובייקטים של מקורות נתונים, נוצרת פעולה ברקע כדי לאחזר את הנתונים מ-BigQuery או מ-Looker ולהחזיר תשובה שמכילה את הערך DataExecutionStatus. אם הביצוע מתחיל בהצלחה, הערך של DataExecutionState בדרך כלל הוא RUNNING.

מכיוון שהתהליך הוא אסינכרוני, צריך להטמיע באפליקציה מודל סקירה כדי לאחזר מדי פעם את הסטטוס של אובייקטי מקורות הנתונים. משתמשים ב-method‏ spreadsheets.get עד שהסטטוס מחזיר את המצב SUCCEEDED או FAILED. ברוב המקרים, הביצוע מסתיים במהירות, אבל זה תלוי במורכבות של מקור הנתונים. בדרך כלל, הביצוע לא נמשך יותר מ-10 דקות.