סקירה כללית של החיבור שמוגדר כברירת מחדל

כדי לפשט את תהליך העבודה, אפשר להגדיר חיבור ברירת מחדל למשאבי Cloud ב-BigQuery ליצירת טבלאות חיצוניות ומודלים מרוחקים של BigQuery ML. האדמין מגדיר את חיבור ברירת המחדל, ואז המשתמשים יכולים להפנות אליו במהלך יצירת משאבים במקום לציין את פרטי החיבור.

‫BigQuery תומך בחיבורים שמוגדרים כברירת מחדל במשאבים הבאים:

• טבלאות Cloud Storage BigLake
• טבלאות של אובייקטים
• טבלאות BigLake ל-Apache Iceberg ב-BigQuery
• מודלים מרוחקים

כדי להשתמש בחיבור שמוגדר כברירת מחדל, מציינים את מילת המפתח DEFAULT בסעיפי ה-SQL הבאים:

• הסעיף WITH CONNECTION של CREATE EXTERNAL TABLE הצהרה
• הסעיף REMOTE WITH CONNECTION של הצהרת CREATE MODEL למודל מרוחק

לפני שמתחילים

Enable the BigQuery Connection API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

תפקידים והרשאות נדרשים

כדי לעבוד עם חיבורי ברירת מחדל, צריך להשתמש בתפקידים הבאים בממשק לניהול זהויות והרשאות גישה (IAM):

• שימוש בחיבור ברירת המחדל: BigQuery Connection User (roles/bigquery.connectionUser) בפרויקט
• הגדרת חיבור ברירת מחדל: BigQuery Admin‏ (roles/bigquery.admin) בפרויקט

• אם צריך להעניק הרשאות לחשבון השירות של חיבור ברירת מחדל:

  • אם משתמשים בחיבור ברירת המחדל כדי ליצור טבלאות חיצוניות: Storage Admin ‏ (roles/storage.admin) בכל קטגוריות Cloud Storage שבהן נעשה שימוש בטבלאות החיצוניות.

  • אם משתמשים בחיבור שמוגדר כברירת מחדל כדי ליצור מודלים מרוחקים: אדמין IAM של פרויקט (roles/resourcemanager.projectIamAdmin) בפרויקט שמכיל את נקודת הקצה של Vertex AI. לסוגים הבאים של מודלים מרוחקים, זהו הפרויקט הנוכחי:

    • מודלים מרוחקים דרך שירותי AI בענן.
    • מודלים מרוחקים של Google או מודלים של שותפים שיצרתם על ידי ציון שם המודל כנקודת קצה.

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

    אם אתם משתמשים במודל מרוחק כדי לנתח נתונים לא מובְנים מטבלת אובייקטים, וקטגוריית Cloud Storage שבה אתם משתמשים בטבלת האובייקטים נמצאת בפרויקט אחר מנקודת הקצה של Vertex AI, אתם צריכים גם הרשאת Storage Admin ‏ (roles/storage.admin) בקטגוריית Cloud Storage שבה נעשה שימוש בטבלת האובייקטים.

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

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

ההרשאות הנדרשות

• שימוש בחיבור שמוגדר כברירת מחדל: bigquery.connections.use
• יצירת חיבור: bigquery.connections.*
• הגדרת החיבור המוגדר כברירת מחדל: bigquery.config.*
• הגדרת הרשאות לחשבון שירות לחיבור ברירת מחדל שמשמש ליצירת טבלאות חיצוניות: storage.buckets.getIamPolicy ו-storage.buckets.setIamPolicy
• הגדרת הרשאות לחשבון שירות לחיבור ברירת מחדל שמשמש ליצירת מודלים מרוחקים:
  • resourcemanager.projects.getIamPolicy וגם resourcemanager.projects.setIamPolicy
  • אם משתמשים בחיבור ברירת המחדל עם מודל מרוחק שמבצע עיבוד של נתונים לא מובנים מטבלת אובייקטים, storage.buckets.getIamPolicy וגם storage.buckets.setIamPolicy

יכול להיות שתוכלו לקבל את ההרשאות האלה גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

הגדרת החיבור המוגדר כברירת מחדל

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

• יוצרים חיבור, מעניקים תפקידים מתאימים לחשבון השירות של החיבור, ואז מגדירים את החיבור כחיבור ברירת המחדל.

  למשתמש שיוצר ומגדיר את חיבור ברירת המחדל צריך להיות תפקיד BigQuery Admin, וגם תפקיד Storage Admin או Project IAM Admin, בהתאם לצורך. למשתמש שמוגדר כברירת מחדל לחיבור צריך להיות התפקיד 'משתמש בחיבור BigQuery'.

• יוצרים חיבור ואז מגדירים אותו כחיבור ברירת המחדל. כשמשתמשים בחיבור שמוגדר כברירת מחדל, השירות מקצה תפקידים מתאימים לחשבון השירות של החיבור שמוגדר כברירת מחדל.

  המשתמש שיוצר את חיבור ברירת המחדל ומגדיר אותו צריך להיות בעל תפקיד אדמין ב-BigQuery. למשתמש החיבור שמוגדר כברירת מחדל צריך להיות התפקיד BigQuery Connection User, וגם התפקיד Storage Admin או Project IAM Admin, בהתאם לצורך.

• מציינים את מילת המפתח DEFAULT בהצהרה נתמכת. השירות יוצר חיבור, מקצה תפקידים מתאימים לחשבון השירות של החיבור, ואז מגדיר את החיבור כחיבור ברירת המחדל.

  למשתמש החיבור שמוגדר כברירת מחדל צריך להיות תפקיד BigQuery Admin, וגם תפקיד Storage Admin או Project IAM Admin, בהתאם לצורך.

• אם החיבור שמוגדר כברירת מחדל חסר, BigQuery יוצר חיבור חדש עם המאפיינים הבאים:

  • אזור: אותו אזור כמו מערך הנתונים.
  • שם: __default_cloudresource_connection__
  • סוג: CLOUD_RESOURCE

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

הגדרת חיבור ברירת מחדל לפרויקט

מגדירים את חיבור ברירת המחדל למשאבי Cloud בפרויקט באמצעות הצהרת DDL‏ ALTER PROJECT SET OPTIONS.

בדוגמה הבאה מוגדר חיבור ברירת המחדל לפרויקט:

  ALTER PROJECT PROJECT_ID
  SET OPTIONS (
    `region-REGION.default_cloud_resource_connection_id` = CONNECTION_ID);
  

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: המזהה של הפרויקט שבו מגדירים את חיבור ברירת המחדל.
• ‫REGION: האזור של החיבור.
• ‫CONNECTION_ID: המזהה או השם של החיבור שרוצים להשתמש בו כברירת מחדל לטבלאות ולמודלים. מציינים רק את המזהה או השם של החיבור, ולא כוללים את הקידומות של מזהה הפרויקט והאזור שמצורפות לשם או למזהה.

מידע נוסף על הגדרת חיבור ברירת מחדל לפרויקט זמין במאמר ניהול הגדרות ברירת מחדל.

הקצאת הרשאות לחיבור ברירת המחדל

כשמשתמשים בחיבור שמוגדר כברירת מחדל כדי ליצור טבלה חיצונית או מודל מרוחק,Google Cloud מעניק לחשבון השירות של החיבור שמוגדר כברירת מחדל את התפקידים המתאימים, אם לחשבון השירות עדיין אין אותם. הפעולה הזו תיכשל אם אין לכם הרשאות אדמין במשאב Cloud Storage או Vertex AI שמשמש את הטבלה החיצונית או המודל המרוחק.

התפקידים הבאים מוקצים לחשבון השירות של חיבור ברירת המחדל:

סוג הטבלה או המודל	מקור מרוחק	תפקידים שמוקצים לחשבון השירות של החיבור
טבלה של Cloud Storage BigLake	Cloud Storage	roles/storage.legacyBucketReader roles/storage.legacyObjectReader
טבלת אובייקטים	Cloud Storage	roles/storage.legacyBucketReader roles/storage.legacyObjectReader
טבלאות BigLake Iceberg ב-BigQuery	Cloud Storage	roles/storage.legacyBucketWriter roles/storage.legacyObjectOwner
מודלים מרוחקים של BigQuery ML על מודלים של Vertex AI	מודלים בבעלות Google	roles/aiplatform.user
	אפשר לפרוס אותם לנקודת קצה מ-Model Garden
	מודלים של משתמשים
	מודלים שעברו כוונון עדין	roles/aiplatform.serviceAgent
מודלים מרוחקים של BigQuery ML בשירותי Cloud AI	מעבד מסמכים	roles/documentai.apiUser
	מזהה דיבור	roles/speech.serviceAgent
	Cloud NLP	roles/serviceusage.serviceUsageConsumer
	Cloud Vision	roles/serviceusage.serviceUsageConsumer
	Cloud Translation	roles/cloudtranslate.user

יצירת טבלאות חיצוניות באמצעות CONNECTION DEFAULT

בדוגמאות הבאות מוסבר איך ליצור טבלאות חיצוניות על ידי ציון WITH CONNECTION DEFAULT ב-BigQuery.

דוגמה: יצירת טבלת BigLake ב-Cloud Storage

ביטוי ה-SQL הבא יוצר טבלת BigLake ב-Cloud Storage עם חיבור ברירת מחדל:

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  format = 'TABLE_FORMAT',
  uris = ['BUCKET_PATH']);

דוגמה: יצירת טבלת אובייקטים עם חיבור ברירת מחדל

הביטוי הבא ב-SQL יוצר טבלת אובייקטים עם חיבור שמוגדר כברירת מחדל:

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  object_metadata = 'SIMPLE'
  uris = ['BUCKET_PATH']);

דוגמה: יצירת טבלאות BigLake Iceberg ב-BigQuery עם חיבור ברירת מחדל

ביטוי ה-SQL הבא יוצר טבלאות BigLake Iceberg ב-BigQuery עם חיבור ברירת מחדל:

CREATE TABLE `myproject.tpch_clustered.nation` (
  n_nationkey integer,
  n_name string,
  n_regionkey integer,
  n_comment string)
CLUSTER BY n_nationkey
WITH CONNECTION DEFAULT
OPTIONS (
  file_format = 'PARQUET',
  table_format = 'ICEBERG',
  storage_uri = 'gs://mybucket/warehouse/nation');

יצירת מודלים מרוחקים באמצעות REMOTE WITH CONNECTION DEFAULT

בדוגמאות הבאות מוסבר איך ליצור מודלים מרוחקים על ידי הגדרת REMOTE WITH CONNECTION DEFAULT ב-BigQuery.

דוגמה: יצירת מודל מרוחק על בסיס מודל Vertex AI

ביטוי ה-SQL הבא יוצר מודל מרוחק עם חיבור שמוגדר כברירת מחדל:

CREATE OR REPLACE MODEL `mydataset.flash_model`
  REMOTE WITH CONNECTION DEFAULT
  OPTIONS(ENDPOINT = 'gemini-2.0-flash');

דוגמה: יצירת מודל מרוחק באמצעות שירות AI בענן

הביטוי הבא ב-SQL יוצר מודל מרוחק בשירות Cloud AI עם חיבור ברירת מחדל:

CREATE MODEL `project_id.mydataset.mymodel`
REMOTE WITH CONNECTION DEFAULT
 OPTIONS(REMOTE_SERVICE_TYPE = 'CLOUD_AI_VISION_V1')

דוגמה: יצירת מודל מרוחק עם נקודת קצה של HTTPS

ביטוי ה-SQL הבא יוצר מודל מרוחק עם נקודת קצה של HTTPS וחיבור ברירת מחדל:

CREATE MODEL `project_id.mydataset.mymodel`
 INPUT(f1 INT64, f2 FLOAT64, f3 STRING, f4 ARRAY)
 OUTPUT(out1 INT64, out2 INT64)
 REMOTE WITH CONNECTION DEFAULT
 OPTIONS(ENDPOINT = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234')

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

• מידע נוסף על הגדרות ברירת מחדל ב-BigQuery