BigQuery
אפשר להשתמש במחבר BigQuery כדי לבצע פעולות של הוספה, מחיקה, עדכון וקריאה של נתונים ב-Google BigQuery. אפשר גם להריץ שאילתות SQL מותאמות אישית על נתונים ב-BigQuery. אתם יכולים להשתמש במחבר BigQuery כדי לשלב נתונים מכמה שירותים של Google Cloud או משירותים אחרים של צד שלישי, כמו Cloud Storage או Amazon S3.
לפני שמתחילים
בפרויקט Google Cloud, מבצעים את המשימות הבאות:
- מוודאים שהגדרתם חיבור לרשת. מידע על תבניות רשת זמין במאמר קישוריות לרשת.
- נותנים למשתמש שמגדיר את המחבר את תפקיד ה-IAM roles/connectors.admin.
- מקצים את התפקיד
roles/bigquery.dataEditorב-IAM לחשבון השירות שבו רוצים להשתמש עבור המחבר. אם אין לכם חשבון שירות, אתם צריכים ליצור חשבון שירות. המחבר וחשבון השירות צריכים להיות שייכים לאותו פרויקט. - מפעילים את השירותים הבאים:
-
secretmanager.googleapis.com(Secret Manager API) -
connectors.googleapis.com(Connectors API)
במאמר הפעלת שירותים מוסבר איך להפעיל שירותים. אם השירותים או ההרשאות האלה לא הופעלו בפרויקט שלכם בעבר, תוצג לכם בקשה להפעיל אותם כשאתם מגדירים את המחבר.
-
יצירת חיבור ל-BigQuery
החיבור הוא ספציפי למקור נתונים. אם יש לכם הרבה מקורות נתונים, תצטרכו ליצור חיבור נפרד לכל אחד מהם. כדי ליצור קישור:
- במסוף Cloud, עוברים לדף Integration Connectors > Connections ובוחרים או יוצרים פרויקט בענן.
- לוחצים על + יצירת חיבור חדש כדי לפתוח את הדף יצירת חיבור.
- בקטע מיקום, בוחרים מיקום מהרשימה אזור ולוחצים על הבא.
רשימה של כל האזורים הנתמכים מופיעה במאמר מיקומים.
- בקטע פרטי החיבור, מבצעים את הפעולות הבאות:
- בוחרים באפשרות BigQuery מתוך רשימת מחברים.
- בוחרים גרסה של מחבר מהרשימה Connector version (גרסת המחבר).
- בשדה Connection Name, מזינים שם למופע החיבור. שם החיבור יכול להכיל אותיות קטנות, מספרים או מקפים. השם צריך להתחיל באות ולהסתיים באות או במספר, והוא לא יכול להכיל יותר מ-49 תווים.
- אופציונלי: מפעילים את Cloud Logging ואז בוחרים רמת יומן. כברירת מחדל, רמת היומן מוגדרת כ-
Error. - חשבון שירות: בוחרים חשבון שירות שיש לו את התפקידים הנדרשים.
- (אופציונלי) מגדירים את ההגדרות של צומת החיבור.
- מספר מינימלי של צמתים: מזינים את המספר המינימלי של צמתי חיבור.
- מספר הצמתים המקסימלי: מזינים את מספר צמתי החיבור המקסימלי.
- מזהה הפרויקט: המזהה של הפרויקט ב-Google Cloud שבו נמצאים הנתונים.
- מזהה מערך הנתונים: המזהה של מערך הנתונים ב-BigQuery.
- כדי לתמוך בסוג הנתונים Array ב-BigQuery, בוחרים באפשרות תמיכה בסוגי נתונים מקוריים. סוגי המערכים הבאים נתמכים: Varchar, Int64, Float64, Long, Double, Bool ו-Timestamp. אין תמיכה במערכים בתוך מערכים.
- (אופציונלי) כדי להגדיר שרת proxy לחיבור, בוחרים באפשרות שימוש ב-proxy ומזינים את פרטי ה-proxy.
-
סכימת אימות של שרת proxy: בוחרים את סוג האימות לאימות מול שרת ה-proxy. אלה סוגי האימות שנתמכים:
- בסיסי: אימות HTTP בסיסי.
- Digest: אימות HTTP מסוג Digest.
- משתמש proxy: שם משתמש שישמש לאימות בשרת ה-proxy.
- סיסמת ה-Proxy: הסוד במנהל הסודות של סיסמת המשתמש.
-
סוג ה-SSL של ה-Proxy: סוג ה-SSL שבו יש להשתמש כשמתחברים לשרת ה-Proxy. סוגי האימות הבאים נתמכים:
- אוטומטי: הגדרת ברירת המחדל. אם כתובת ה-URL היא כתובת HTTPS, נעשה שימוש באפשרות Tunnel. אם כתובת ה-URL היא כתובת HTTP, נעשה שימוש באפשרות NEVER.
- תמיד: החיבור תמיד מופעל באמצעות SSL.
- לעולם לא: החיבור לא מופעל באמצעות SSL.
- מנהור: החיבור הוא דרך שרת proxy למנהור. שרת ה-proxy פותח חיבור למארח המרוחק, והתנועה זורמת הלוך ושוב דרך ה-proxy.
- בקטע שרת Proxy, מזינים את פרטי שרת ה-Proxy.
- לוחצים על + הוספת יעד.
- בוחרים סוג יעד.
- כתובת המארח: מציינים את שם המארח או את כתובת ה-IP של היעד.
כדי ליצור חיבור פרטי למערכת העורפית, פועלים לפי השלבים הבאים:
- יוצרים קובץ מצורף לשירות PSC.
- יוצרים endpoint attachment ואז מזינים את הפרטים שלו בשדה Host address.
- כתובת המארח: מציינים את שם המארח או את כתובת ה-IP של היעד.
- לוחצים על הבא.
צומת הוא יחידה (או עותק) של חיבור שמבצעת עיבוד של עסקאות. כדי לעבד יותר עסקאות עבור חיבור מסוים, צריך יותר צמתים, ולהפך: כדי לעבד פחות עסקאות, צריך פחות צמתים. כדי להבין איך הצמתים משפיעים על התמחור של המחבר, אפשר לעיין במאמר בנושא תמחור של צמתים לחיבור. אם לא מזינים ערכים, כברירת מחדל, מספר הצמתים המינימלי מוגדר כ-2 (לזמינות טובה יותר) ומספר הצמתים המקסימלי מוגדר כ-50.
-
בקטע אימות, מזינים את פרטי האימות.
- בוחרים אם לבצע אימות באמצעות קוד הרשאה של OAuth 2.0 או להמשיך ללא אימות.
כדי להבין איך להגדיר אימות, אפשר לעיין במאמר הגדרת אימות.
- לוחצים על הבא.
- בוחרים אם לבצע אימות באמצעות קוד הרשאה של OAuth 2.0 או להמשיך ללא אימות.
- בודקים את פרטי החיבור והאימות ולוחצים על יצירה.
הגדרת אימות
מזינים את הפרטים בהתאם לאימות שבו רוצים להשתמש.
- ללא אימות: בוחרים באפשרות הזו אם לא נדרש אימות.
- OAuth 2.0 – קוד הרשאה: בוחרים באפשרות הזו כדי לבצע אימות באמצעות תהליך כניסה מבוסס-אינטרנט של משתמש. מציינים את הפרטים הבאים:
- Client ID: מזהה הלקוח שנדרש כדי להתחבר לשירות ה-backend של Google.
- היקפים: רשימה מופרדת בפסיקים של ההיקפים הרצויים. כדי לראות את כל היקפי ההרשאות של OAuth 2.0 שנתמכים בשירות Google שאתם צריכים, אפשר לעיין בקטע הרלוונטי בדף היקפי ההרשאות של OAuth 2.0 ל-Google APIs.
- סוד לקוח: בוחרים באפשרות סוד ב-Secret Manager. כדי להגדיר את ההרשאה הזו, צריך ליצור קוד סודי ב-Secret Manager.
- גרסת סוד: גרסת סוד ב-Secret Manager של סוד הלקוח.
בסוג האימות Authorization code, אחרי שיוצרים את החיבור, צריך לתת הרשאה לחיבור.
אישור החיבור
אם משתמשים ב-OAuth 2.0 – קוד הרשאה כדי לאמת את החיבור, צריך לבצע את המשימות הבאות אחרי שיוצרים את החיבור.
- בדף החיבורים, מאתרים את החיבור החדש.
שימו לב שהסטטוס של המחבר החדש יהיה נדרשת הרשאה.
- לוחצים על דרושה הרשאה.
יוצג לוח עריכת הרשאה.
- מעתיקים את הערך של Redirect URI (ה-URI של ההפניה האוטומטית) לאפליקציה החיצונית.
- מאמתים את פרטי ההרשאה.
- לוחצים על Authorize.
אם ההרשאה מתבצעת בהצלחה, סטטוס החיבור יהיה פעיל בדף החיבורים.
אישור מחדש של קוד הרשאה
אם אתם משתמשים בסוג האימות Authorization code וביצעתם שינויים בהגדרות ב-BigQuery, אתם צריכים לאשר מחדש את החיבור ל-BigQuery. כדי לאשר מחדש חיבור, מבצעים את השלבים הבאים:
- לוחצים על החיבור הרצוי בדף החיבורים.
ייפתח הדף עם פרטי החיבור.
- לוחצים על עריכה כדי לערוך את פרטי החיבור.
- בודקים את הפרטים של OAuth 2.0 – קוד הרשאה בקטע אימות.
אם צריך, מבצעים את השינויים הנדרשים.
- לוחצים על Save. הלחיצה תעביר אתכם לדף פרטי החיבור.
- בקטע אימות, לוחצים על עריכת הרשאה. מוצגת החלונית Authorize (אישור).
- לוחצים על Authorize.
אם ההרשאה מתבצעת בהצלחה, סטטוס החיבור יהיה פעיל בדף החיבורים.
שימוש בחיבור ל-BigQuery בשילוב
אחרי שיוצרים את החיבור, הוא זמין גם ב-Apigee Integration וגם ב-Application Integration. אפשר להשתמש בחיבור בשילוב באמצעות המשימה Connectors.
- כדי להבין איך ליצור ולהשתמש במשימה Connectors ב-Apigee Integration, אפשר לעיין במאמר משימת Connectors.
- מידע על יצירה ושימוש במשימת מחברים ב-Application Integration זמין במאמר משימת מחברים.
פעולות
בקטע הזה מפורטות הפעולות שאפשר לבצע באמצעות המחבר של BigQuery.
התוצאות של כל הפעולות והפעולות על הישויות יהיו זמינות כתגובת JSON בפרמטר התגובה של משימת Connectors connectorOutputPayload אחרי שמריצים את השילוב.
פעולת CancelJob
הפעולה הזו מאפשרת לבטל עבודה שרצה ב-BigQuery.
בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה CancelJob.
| שם הפרמטר | סוג נתונים | תיאור |
|---|---|---|
| JobId | String | המזהה של המשרה שרוצים לבטל. זהו שדה חובה. |
| אזור | String | האזור שבו העבודה מופעלת כרגע. הדרישה הזו לא חלה אם המשרה היא בארה"ב או באזור האיחוד האירופי. |
פעולת GetJob
הפעולה הזו מאפשרת לאחזר את פרטי ההגדרה ואת מצב ההפעלה של משימה קיימת.
בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה GetJob.
| שם הפרמטר | סוג נתונים | תיאור |
|---|---|---|
| JobId | String | המזהה של המשימה שרוצים לאחזר את ההגדרה שלה. זהו שדה חובה. |
| אזור | String | האזור שבו העבודה מופעלת כרגע. הדרישה הזו לא חלה אם המשרה היא בארה"ב או באזור האיחוד האירופי. |
פעולת InsertJob
הפעולה הזו מאפשרת להוסיף משימה ב-BigQuery, שאפשר לבחור בה בהמשך כדי לאחזר את תוצאות השאילתה.
בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה InsertJob.
| שם הפרמטר | סוג נתונים | תיאור |
|---|---|---|
| שאילתה | String | השאילתה לשליחה אל BigQuery. זהו שדה חובה. |
| IsDML | String | צריך להגדיר את הערך true אם השאילתה היא פקודת DML, או false אחרת. ערך ברירת המחדל הוא false. |
| DestinationTable | String | טבלת היעד של השאילתה, בפורמט DestProjectId:DestDatasetId.DestTable. |
| WriteDisposition | String | מציינת איך לכתוב נתונים לטבלת היעד, למשל: חיתוך של תוצאות קיימות, הוספה של תוצאות קיימות או כתיבה רק כשהטבלה ריקה. אלה הערכים הנתמכים:
|
| DryRun | String | מציין אם ההרצה של העבודה היא הרצה יבשה. |
| MaximumBytesBilled | String | מציין את מספר הבייטים המקסימלי שאפשר לעבד בעזרת העבודה. המערכת של BigQuery מבטלת את המשימה אם המשימה מנסה לעבד יותר בייטים מהערך שצוין. |
| אזור | String | מציין את האזור שבו העבודה תתבצע. |
פעולת InsertLoadJob
הפעולה הזו מאפשרת להוסיף משימת טעינה של BigQuery, שמוסיפה נתונים מ-Google Cloud Storage לטבלה קיימת.
בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה InsertLoadJob.
| שם הפרמטר | סוג נתונים | תיאור |
|---|---|---|
| SourceURIs | String | רשימה של מזהי URI של Google Cloud Storage, מופרדים ברווחים. |
| SourceFormat | String | פורמט המקור של הקבצים. אלה הערכים הנתמכים:
|
| DestinationTable | String | טבלת היעד של השאילתה, בפורמט DestProjectId.DestDatasetId.DestTable. |
| DestinationTableProperties | String | אובייקט JSON שמציין את השם הידידותי של הטבלה, התיאור ורשימת התוויות. |
| DestinationTableSchema | String | רשימת JSON שמציינת את סכימת הטבלה, בפורמט "DestinationTableSchema": "\"fields\":[{\"name\":\"id\",\"type\":\"INTEGER\"},{\"name\":\"name\",\"type\":\"STRING\"}]". |
| DestinationEncryptionConfiguration | String | אובייקט JSON שמציין את הגדרות ההצפנה של KMS לטבלה. |
| SchemaUpdateOptions | String | רשימת JSON שמציינת את האפשרויות להחלה כשמעדכנים את סכימת טבלת היעד. |
| TimePartitioning | String | אובייקט JSON שמציין את סוג החלוקה לפי זמן ואת השדה. |
| RangePartitioning | String | אובייקט JSON שמציין את שדה חלוקת הטווח ואת הקטגוריות. |
| סידור באשכולות | String | אובייקט JSON שמציין את השדות שישמשו לאשכול. |
| זיהוי אוטומטי | String | מציינים אם האפשרויות והסכימה צריכות להיקבע באופן אוטומטי עבור קובצי JSON ו-CSV. |
| CreateDisposition | String | מציינים אם צריך ליצור את טבלת היעד אם היא עדיין לא קיימת. אלה הערכים הנתמכים:
|
| WriteDisposition | String | מציינת איך לכתוב נתונים לטבלת היעד, למשל: חיתוך של תוצאות קיימות, הוספה של תוצאות קיימות או כתיבה רק כשהטבלה ריקה. אלה הערכים הנתמכים:
|
| אזור | String | מציין את האזור שבו העבודה תתבצע. משאבי Google Cloud Storage ומערך הנתונים ב-BigQuery צריכים להיות באותו אזור. |
| DryRun | String | מציין אם ההרצה של העבודה היא הרצה יבשה. ערך ברירת המחדל הוא false. |
| MaximumBadRecords | String | מציינים את מספר הרשומות שיכולות להיות לא תקינות לפני שכל העבודה תבוטל. כברירת מחדל, כל הרשומות צריכות להיות תקינות. ערך ברירת המחדל הוא 0. |
| IgnoreUnknownValues | String | מציין אם המערכת צריכה להתעלם מהשדות הלא מוכרים בקובץ הקלט או להתייחס אליהם כשגיאות. כברירת מחדל, הן נחשבות לשגיאות. ערך ברירת המחדל הוא false. |
| AvroUseLogicalTypes | String | מציין אם צריך להשתמש בסוגים לוגיים של AVRO כדי להמיר נתוני AVRO לסוגים של BigQuery. ערך ברירת המחדל הוא true. |
| CSVSkipLeadingRows | String | מציינת כמה שורות לדלג עליהן בתחילת קובצי ה-CSV. האפשרות הזו משמשת בדרך כלל כדי לדלג על שורות כותרת. |
| CSVEncoding | String | סוג הקידוד של קובצי ה-CSV. אלה הערכים הנתמכים:
|
| CSVNullMarker | String | אם מציינים מחרוזת, היא משמשת לערכי NULL בקובצי CSV. כברירת מחדל, אי אפשר להשתמש ב-NULL בקובצי CSV. |
| CSVFieldDelimiter | String | התו שמשמש להפרדה בין עמודות בקובצי CSV. ערך ברירת המחדל הוא פסיק (,). |
| CSVQuote | String | התו שמשמש לשדות עם מרכאות בקובצי CSV. אפשר להגדיר את הערך כריק כדי להשבית את הוספת המירכאות. ערך ברירת המחדל הוא מירכאות כפולות ("). |
| CSVAllowQuotedNewlines | String | ההגדרה קובעת אם קובצי ה-CSV יכולים להכיל מעברי שורה בשדות שמוקפים במירכאות. ערך ברירת המחדל הוא false. |
| CSVAllowJaggedRows | String | ההגדרה קובעת אם קובצי ה-CSV יכולים להכיל שדות חסרים. ערך ברירת המחדל הוא false. |
| DSBackupProjectionFields | String | רשימת JSON של שדות לטעינה מגיבוי של מאגר נתונים בענן. |
| ParquetOptions | String | אובייקט JSON שמציין את אפשרויות הייבוא הספציפיות ל-Parquet. |
| DecimalTargetTypes | String | רשימת JSON שבה מפורט סדר העדיפות שחל על סוגים מספריים. |
| HivePartitioningOptions | String | אובייקט JSON שמציין את אפשרויות החלוקה למחיצות בצד המקור. |
הפעלת שאילתת SQL בהתאמה אישית
כדי ליצור שאילתה בהתאמה אישית, פועלים לפי השלבים הבאים:
- פועלים לפי ההוראות המפורטות ל הוספת משימה של מחברים.
- כשמגדירים את משימת המחבר, בוחרים באפשרות פעולות בסוג הפעולה שרוצים לבצע.
- ברשימה Action, בוחרים באפשרות Execute custom query ולוחצים על Done.
- מרחיבים את הקטע Task input (קלט למשימה) ומבצעים את הפעולות הבאות:
- בשדה Timeout after, מזינים את מספר השניות להמתנה עד להפעלת השאילתה.
ערך ברירת המחדל:
180שניות. - בשדה Maximum number of rows (מספר השורות המקסימלי), מזינים את מספר השורות המקסימלי שיוחזר ממסד הנתונים.
ערך ברירת המחדל:
25. - כדי לעדכן את השאילתה המותאמת אישית, לוחצים על עריכת סקריפט בהתאמה אישית. תיפתח תיבת הדו-שיח עורך הסקריפטים.
- בתיבת הדו-שיח הכלי לעריכת סקריפטים, מזינים את שאילתת ה-SQL ולוחצים על שמירה.
אפשר להשתמש בסימן שאלה (?) בהצהרת SQL כדי לייצג פרמטר יחיד שצריך לציין ברשימת פרמטרים של שאילתה. לדוגמה, שאילתת ה-SQL הבאה בוחרת את כל השורות מהטבלה
Employeesשתואמות לערכים שצוינו בעמודהLastName:SELECT * FROM Employees where LastName=?
- אם השתמשתם בסימני שאלה בשאילתת ה-SQL, צריך להוסיף את הפרמטר על ידי לחיצה על + הוספת שם פרמטר לכל סימן שאלה. במהלך ההפעלה של השילוב, הפרמטרים האלה מחליפים את סימני השאלה (?) בשאילתת ה-SQL באופן עקבי. לדוגמה, אם הוספתם שלושה סימני שאלה (?), אתם צריכים להוסיף שלושה פרמטרים לפי הסדר.
כדי להוסיף פרמטרים של שאילתה:
- מהרשימה סוג בוחרים את סוג הנתונים של הפרמטר.
- בשדה ערך, מזינים את הערך של הפרמטר.
- כדי להוסיף כמה פרמטרים, לוחצים על + הוספת פרמטר של שאילתה.
הפעולה Execute custom query לא תומכת במשתני מערך.
- בשדה Timeout after, מזינים את מספר השניות להמתנה עד להפעלת השאילתה.
שימוש ב-Terraform ליצירת חיבורים
אתם יכולים להשתמש במשאב של Terraform כדי ליצור חיבור חדש.
כדי ללמוד איך להחיל הגדרות ב-Terraform או להסיר אותן, ראו פקודות בסיסיות ב-Terraform.
כדי לראות תבנית לדוגמה של Terraform ליצירת חיבור, אפשר לעיין בתבנית לדוגמה.
כשיוצרים את החיבור הזה באמצעות Terraform, צריך להגדיר את המשתנים הבאים בקובץ ההגדרות של Terraform:
| שם הפרמטר | סוג נתונים | חובה | תיאור |
|---|---|---|---|
| project_id | מחרוזת | נכון | המזהה של הפרויקט שמכיל את מערך הנתונים ב-BigQuery, למשל myproject. |
| dataset_id | מחרוזת | לא נכון | מזהה מערך הנתונים ב-BigQuery בלי שם הפרויקט. למשל, mydataset. |
| proxy_enabled | בוליאני | לא נכון | מסמנים את תיבת הסימון הזו כדי להגדיר שרת Proxy לחיבור. |
| proxy_auth_scheme | ENUM | לא נכון | סוג האימות שבו יש להשתמש כדי לבצע אימות לשרת ה-proxy ProxyServer. הערכים הנתמכים הם: BASIC, DIGEST, NONE |
| proxy_user | מחרוזת | לא נכון | שם משתמש שישמש לאימות בשרת ה-proxy ProxyServer. |
| proxy_password | SECRET | לא נכון | סיסמה שתשמש לאימות בשרת ה-proxy ProxyServer. |
| proxy_ssltype | ENUM | לא נכון | סוג ה-SSL שבו צריך להשתמש כשמתחברים לשרת ה-proxy של ProxyServer. הערכים הנתמכים הם: AUTO, ALWAYS, NEVER, TUNNEL |
מגבלות המערכת
מחבר BigQuery יכול לעבד עד 8 טרנזקציות בשנייה, לכל צומת, ומגביל את מספר הטרנזקציות מעבר למגבלה הזו. כברירת מחדל, Integration Connectors מקצה 2 צמתים (לזמינות טובה יותר) לחיבור.
מידע על המגבלות שחלות על Integration Connectors זמין במאמר מגבלות.
סוגי נתונים נתמכים
אלה סוגי הנתונים הנתמכים במחבר הזה:
- ARRAY
- BIGINT
- BINARY
- BIT
- בוליאני
- CHAR
- תאריך
- DECIMAL
- DOUBLE
- FLOAT
- מספר שלם
- LONGN VARCHAR
- LONG VARCHAR
- NCHAR
- NUMERIC
- NVARCHAR
- REAL
- SMALL INT
- שעות
- TIMESTAMP
- TINY INT
- VARBINARY
- VARCHAR
מגבלות ידועות
-
המחבר של BigQuery לא תומך במפתח הראשי בטבלת BigQuery. כלומר, אי אפשר לבצע את פעולות הישות Get, Update ו-Delete באמצעות
entityId. לחלופין, אפשר להשתמש בפסוקית המסנן כדי לסנן רשומות על סמך מזהה. -
כשמאחזרים נתונים בפעם הראשונה, יכול להיות שיהיה עיכוב ראשוני של כ-6 שניות. בגלל שמירה במטמון, אין השהיה בבקשות הבאות. ההשהיה הזו יכולה לחזור על עצמה כשתוקף המטמון יפוג.
קבלת עזרה מקהילת Google Cloud
אתם יכולים לפרסם את השאלות שלכם ולדון במחבר הזה בקהילת Google Cloud בפורומים של Cloud.