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

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

משאבים וסעיפי SQL נתמכים

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

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

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

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

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

מפעילים את BigQuery Connection API, אם הוא עדיין לא מופעל.

התפקידים שנדרשים כדי להפעיל ממשקי API

כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

להפעלת ה-API

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

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

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

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

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

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

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

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

    אם אתם משתמשים במודל המרוחק כדי לנתח נתונים לא מובְנים מטבלת אובייקטים, והקטגוריה של Cloud Storage שבה אתם משתמשים בטבלת האובייקטים נמצאת בפרויקט אחר מנקודת הקצה של Agent Platform, אתם צריכים גם את התפקיד "אדמין של Storage" (roles/storage.admin) בקטגוריה של Cloud Storage שבה משתמשת טבלת האובייקטים.

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

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

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

• שימוש בחיבור שמוגדר כברירת מחדל: 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 ואת התפקיד אדמין ב-Storage או אדמין ב-IAM של הפרויקט, בהתאם לצורך. למשתמש של החיבור שמוגדר כברירת מחדל צריך להיות התפקיד "משתמש של חיבור BigQuery".

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

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

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

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

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

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

חשוב: שימוש בחיבור ברירת מחדל יכול להעניק למשתמשים הרשאות נוספות. לדוגמה, אם אדמין משתמש בחיבור שמוגדר כברירת מחדל כדי ליצור טבלת אובייקטים, לחשבון השירות של החיבור שמוגדר כברירת מחדל מוקצים התפקידים Storage Legacy Bucket Reader ו-Storage Legacy Object Reader בקטגוריה המתאימה של 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 או של Agent Platform שמשמש את הטבלה החיצונית או את המודל המרוחק.

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

סוג הטבלה או המודל	משאב מרוחק	תפקידים שהוקצו לחשבון השירות של החיבור
טבלת BigLake ב-Cloud Storage	Cloud Storage	roles/storage.legacyBucketReader roles/storage.legacyObjectReader
טבלת אובייקטים	Cloud Storage	roles/storage.legacyBucketReader roles/storage.legacyObjectReader
טבלאות מנוהלות של Iceberg	Cloud Storage	roles/storage.legacyBucketWriter roles/storage.legacyObjectOwner
מודלים מרוחקים של BigQuery ML על מודלים של Gemini Enterprise Agent Platform	מודלים בבעלות Google	roles/aiplatform.user
	אפשר לפרוס אותם בנקודת קצה מ-Model Garden
	מודלים של משתמשים
	מודלים שעברו כוונון עדין	roles/aiplatform.serviceAgent
מודלים מרוחקים של BigQuery ML בשירותי AI ב-Cloud	מעבד מסמכים	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']);

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

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

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.

דוגמה: יצירת מודל מרוחק על סמך מודל של Agent Platform

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

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

דוגמה: יצירת מודל מרוחק בשירות AI ב-Cloud

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

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

דוגמה: יצירת מודל מרוחק עם נקודת קצה (endpoint) מסוג HTTPS

ביטוי ה-SQL הבא יוצר מודל מרוחק עם נקודת קצה (endpoint) של 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