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

החיבור הוא ספציפי למקור נתונים. אם יש לכם הרבה מקורות נתונים, תצטרכו ליצור חיבור נפרד לכל אחד מהם. כדי ליצור קישור:

  1. במסוף Cloud, עוברים לדף Integration Connectors > Connections ובוחרים או יוצרים פרויקט בענן.

    כניסה לדף Connections

  2. לוחצים על + יצירת חיבור חדש כדי לפתוח את הדף יצירת חיבור.
  3. בקטע מיקום, בוחרים מיקום מהרשימה אזור ולוחצים על הבא.

    רשימה של כל האזורים הנתמכים מופיעה במאמר מיקומים.

  4. בקטע פרטי החיבור, מבצעים את הפעולות הבאות:
    1. בוחרים באפשרות BigQuery מתוך רשימת מחברים.
    2. בוחרים גרסה של מחבר מהרשימה Connector version (גרסת המחבר).
    3. בשדה Connection Name, מזינים שם למופע החיבור. שם החיבור יכול להכיל אותיות קטנות, מספרים או מקפים. השם צריך להתחיל באות ולהסתיים באות או במספר, והוא לא יכול להכיל יותר מ-49 תווים.
    4. אופציונלי: מפעילים את Cloud Logging ואז בוחרים רמת יומן. כברירת מחדל, רמת היומן מוגדרת כ-Error.
    5. חשבון שירות: בוחרים חשבון שירות שיש לו את התפקידים הנדרשים.
    6. (אופציונלי) מגדירים את ההגדרות של צומת החיבור.
      • מספר מינימלי של צמתים: מזינים את המספר המינימלי של צמתי חיבור.
      • מספר הצמתים המקסימלי: מזינים את מספר צמתי החיבור המקסימלי.

      צומת הוא יחידה (או עותק) של חיבור שמבצעת עיבוד של עסקאות. כדי לעבד יותר עסקאות עבור חיבור מסוים, צריך יותר צמתים, ולהפך: כדי לעבד פחות עסקאות, צריך פחות צמתים. כדי להבין איך הצמתים משפיעים על התמחור של המחבר, אפשר לעיין במאמר בנושא תמחור של צמתים לחיבור. אם לא מזינים ערכים, כברירת מחדל, מספר הצמתים המינימלי מוגדר כ-2 (לזמינות טובה יותר) ומספר הצמתים המקסימלי מוגדר כ-50.

    7. מזהה הפרויקט: המזהה של הפרויקט ב-Google Cloud שבו נמצאים הנתונים.
    8. מזהה מערך הנתונים: המזהה של מערך הנתונים ב-BigQuery.
    9. כדי לתמוך בסוג הנתונים Array ב-BigQuery, בוחרים באפשרות תמיכה בסוגי נתונים מקוריים. סוגי המערכים הבאים נתמכים: Varchar,‏ Int64,‏ Float64,‏ Long,‏ Double,‏ Bool ו-Timestamp. אין תמיכה במערכים בתוך מערכים.
    10. (אופציונלי) כדי להגדיר שרת 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.
        1. לוחצים על + הוספת יעד.
        2. בוחרים סוג יעד.
          • כתובת המארח: מציינים את שם המארח או את כתובת ה-IP של היעד.

            כדי ליצור חיבור פרטי למערכת העורפית, פועלים לפי השלבים הבאים:

    11. לוחצים על הבא.
  5. בקטע אימות, מזינים את פרטי האימות.
    1. בוחרים אם לבצע אימות באמצעות קוד הרשאה של OAuth 2.0 או להמשיך ללא אימות.

      כדי להבין איך להגדיר אימות, אפשר לעיין במאמר הגדרת אימות.

    2. לוחצים על הבא.
  6. בודקים את פרטי החיבור והאימות ולוחצים על יצירה.

הגדרת אימות

מזינים את הפרטים בהתאם לאימות שבו רוצים להשתמש.

  • ללא אימות: בוחרים באפשרות הזו אם לא נדרש אימות.
  • 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 – קוד הרשאה כדי לאמת את החיבור, צריך לבצע את המשימות הבאות אחרי שיוצרים את החיבור.

  1. בדף החיבורים, מאתרים את החיבור החדש.

    שימו לב שהסטטוס של המחבר החדש יהיה נדרשת הרשאה.

  2. לוחצים על דרושה הרשאה.

    יוצג לוח עריכת הרשאה.

  3. מעתיקים את הערך של Redirect URI (ה-URI של ההפניה האוטומטית) לאפליקציה החיצונית.
  4. מאמתים את פרטי ההרשאה.
  5. לוחצים על Authorize.

    אם ההרשאה מתבצעת בהצלחה, סטטוס החיבור יהיה פעיל בדף החיבורים.

אישור מחדש של קוד הרשאה

אם אתם משתמשים בסוג האימות Authorization code וביצעתם שינויים בהגדרות ב-BigQuery, אתם צריכים לאשר מחדש את החיבור ל-BigQuery. כדי לאשר מחדש חיבור, מבצעים את השלבים הבאים:

  1. לוחצים על החיבור הרצוי בדף החיבורים.

    ייפתח הדף עם פרטי החיבור.

  2. לוחצים על עריכה כדי לערוך את פרטי החיבור.
  3. בודקים את הפרטים של OAuth 2.0 – קוד הרשאה בקטע אימות.

    אם צריך, מבצעים את השינויים הנדרשים.

  4. לוחצים על Save. הלחיצה תעביר אתכם לדף פרטי החיבור.
  5. בקטע אימות, לוחצים על עריכת הרשאה. מוצגת החלונית Authorize (אישור).
  6. לוחצים על 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 מציינת איך לכתוב נתונים לטבלת היעד, למשל: חיתוך של תוצאות קיימות, הוספה של תוצאות קיימות או כתיבה רק כשהטבלה ריקה. אלה הערכים הנתמכים:
  • WRITE_TRUNCATE
  • WRITE_APPEND
  • WRITE_EMPTY
ערך ברירת המחדל הוא WRITE_TRUNCATE.
DryRun String מציין אם ההרצה של העבודה היא הרצה יבשה.
MaximumBytesBilled String מציין את מספר הבייטים המקסימלי שאפשר לעבד בעזרת העבודה. המערכת של BigQuery מבטלת את המשימה אם המשימה מנסה לעבד יותר בייטים מהערך שצוין.
אזור String מציין את האזור שבו העבודה תתבצע.

פעולת InsertLoadJob

הפעולה הזו מאפשרת להוסיף משימת טעינה של BigQuery, שמוסיפה נתונים מ-Google Cloud Storage לטבלה קיימת.

בטבלה הבאה מתוארים פרמטרי הקלט של הפעולה InsertLoadJob.

שם הפרמטר סוג נתונים תיאור
SourceURIs String רשימה של מזהי URI של Google Cloud Storage, מופרדים ברווחים.
SourceFormat String פורמט המקור של הקבצים. אלה הערכים הנתמכים:
  • AVRO
  • NEWLINE_DELIMITED_JSON
  • DATASTORE_BACKUP
  • PARQUET
  • ORC
  • CSV
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 מציינים אם צריך ליצור את טבלת היעד אם היא עדיין לא קיימת. אלה הערכים הנתמכים:
  • CREATE_IF_NEEDED
  • CREATE_NEVER
ערך ברירת המחדל הוא CREATE_IF_NEEDED.
WriteDisposition String מציינת איך לכתוב נתונים לטבלת היעד, למשל: חיתוך של תוצאות קיימות, הוספה של תוצאות קיימות או כתיבה רק כשהטבלה ריקה. אלה הערכים הנתמכים:
  • WRITE_TRUNCATE
  • WRITE_APPEND
  • WRITE_EMPTY
ערך ברירת המחדל הוא WRITE_APPEND.
אזור 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. אלה הערכים הנתמכים:
  • ISO-8859-1
  • UTF-8
ערך ברירת המחדל הוא UTF-8.
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 בהתאמה אישית

כדי ליצור שאילתה בהתאמה אישית, פועלים לפי השלבים הבאים:

  1. פועלים לפי ההוראות המפורטות ל הוספת משימה של מחברים.
  2. כשמגדירים את משימת המחבר, בוחרים באפשרות פעולות בסוג הפעולה שרוצים לבצע.
  3. ברשימה Action, בוחרים באפשרות Execute custom query ולוחצים על Done.

    תמונה שמציגה את הפעולה execute-custom-query-action תמונה שמציגה את הפעולה execute-custom-query-action

  4. מרחיבים את הקטע Task input (קלט למשימה) ומבצעים את הפעולות הבאות:
    1. בשדה Timeout after, מזינים את מספר השניות להמתנה עד להפעלת השאילתה.

      ערך ברירת המחדל: 180 שניות.

    2. בשדה Maximum number of rows (מספר השורות המקסימלי), מזינים את מספר השורות המקסימלי שיוחזר ממסד הנתונים.

      ערך ברירת המחדל: 25.

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

      תמונה שבה מוצגת שאילתת SQL בהתאמה אישית תמונה שבה מוצגת שאילתת SQL בהתאמה אישית

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

      אפשר להשתמש בסימן שאלה (?) בהצהרת SQL כדי לייצג פרמטר יחיד שצריך לציין ברשימת פרמטרים של שאילתה. לדוגמה, שאילתת ה-SQL הבאה בוחרת את כל השורות מהטבלה Employees שתואמות לערכים שצוינו בעמודה LastName:

      SELECT * FROM Employees where LastName=?

    5. אם השתמשתם בסימני שאלה בשאילתת ה-SQL, צריך להוסיף את הפרמטר על ידי לחיצה על + הוספת שם פרמטר לכל סימן שאלה. במהלך ההפעלה של השילוב, הפרמטרים האלה מחליפים את סימני השאלה (?) בשאילתת ה-SQL באופן עקבי. לדוגמה, אם הוספתם שלושה סימני שאלה (?), אתם צריכים להוסיף שלושה פרמטרים לפי הסדר.

      תמונה שמראה את האפשרות add-query-param תמונה שמראה את האפשרות add-query-param

      כדי להוסיף פרמטרים של שאילתה:

      1. מהרשימה סוג בוחרים את סוג הנתונים של הפרמטר.
      2. בשדה ערך, מזינים את הערך של הפרמטר.
      3. כדי להוסיף כמה פרמטרים, לוחצים על + הוספת פרמטר של שאילתה.
    6. הפעולה Execute custom query לא תומכת במשתני מערך.

שימוש ב-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.

המאמרים הבאים