עבודה עם ערכי ObjectRef

במסמך הזה מתואר מהם ערכי ObjectRef ואיך יוצרים אותם ומשתמשים בהם ב-BigQuery.

ערך ObjectRef הוא STRUCT מסוג עם סכימה מוגדרת מראש שמפנה לאובייקטים ב-Cloud Storage לצורך ניתוח מולטימודאלי. אפשר לעבד אותו באמצעות פונקציות OBJ, פונקציות AI או פונקציות מוגדרות על ידי משתמש ב-Python.

סכימה

ערך ObjectRef כולל את השדות הבאים:

שם סוג מצב תיאור דוגמה
uri STRING REQUIRED ה-URI של האובייקט ב-Cloud Storage. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE הגנרציה של האובייקט. "1560286006357632"
authorizer STRING NULLABLE מזהה חיבור ל-BigQuery לגישה עם הרשאת גישה או NULL לגישה ישירה. המזהה יכול להיות בפורמטים הבאים:
"region.connection"
או
"project.region.connection"		 "myproject.us.myconnection"
details JSON NULLABLE המטא-נתונים של האובייקט או שגיאות שנובעות מעיבוד האובייקט. הוא יכול לכלול את השדות content_type, md5_hash, size ו-updated של האובייקט. {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

השדה content_type בשדה gcs_metadata מהעמודה details מאוחזר מ-Cloud Storage. אפשר להגדיר את סוג התוכן של אובייקט ב-Cloud Storage. אם לא מגדירים אותו ב-Cloud Storage, ‏ BigQuery מסיק את סוג התוכן מהסיומת של ה-URI.

יצירת ObjectRef ערכים

אפשר ליצור ערכי ObjectRef באמצעות טבלאות אובייקטים, הפונקציה OBJ.MAKE_REF או מערכי נתונים של Cloud Storage Insights.

שימוש בטבלאות אובייקטים

משתמשים בטבלת אובייקטים אם אין לכם כתובות URI שמאוחסנות בטבלה ואתם רוצים להציג רשימה של כל האובייקטים מתחילית של Cloud Storage. בטבלת אובייקטים מאוחסנת ההפניה לאובייקט בכל שורה, ויש בה עמודה ref שמכילה ערכים מסוג ObjectRef. השאילתה הבאה משתמשת בהצהרה CREATE EXTERNAL TABLE כדי ליצור טבלת אובייקטים:

CREATE EXTERNAL TABLE mydataset.images
WITH CONNECTION `us.myconnection`
OPTIONS (uris=["gs://mybucket/images/*"], object_metadata="SIMPLE");

SELECT ref AS image_ref FROM mydataset.images;

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

שימוש בפונקציה OBJ.MAKE_REF

אפשר להשתמש בפונקציה OBJ.MAKE_REF אם כבר יש לכם כתובות URI שמאוחסנות בטבלה ואתם רוצים ליצור ערכים של ObjectRef מכתובות ה-URI האלה. השאילתות הבאות מראות איך ליצור ערכים של ObjectRef בעמודה image_ref מתוך העמודה uri שמכילה כתובות URI של Cloud Storage:

-- Specify only the URI
SELECT *, OBJ.MAKE_REF(uri) AS image_ref FROM mydataset.images;
-- Specify the URI and the connection
SELECT *, OBJ.MAKE_REF(uri, "us.myconnection") AS image_ref FROM mydataset.images;

כדי לשנות את אמצעי ההרשאה של ערך ObjectRef קיים, אפשר להשתמש בפונקציה OBJ.MAKE_REF:

-- Remove the authorizer
SELECT *, OBJ.MAKE_REF(ref, authorizer=>NULL) AS image_ref FROM mydataset.images;
-- Change the authorizer
SELECT *, OBJ.MAKE_REF(ref, authorizer=>"us.myconnection2") AS image_ref FROM mydataset.images;

הפונקציה OBJ.MAKE_REF מקבלת authorizer שניתן להגדיר כ-nullable כדי לתמוך בגישה ישירה ובגישה בהרשאת גישה.

שימוש במערכי נתונים של Cloud Storage Insights

אם הגדרתם קבוצת נתונים של Storage Insights, קבוצת הנתונים כבר כוללת עמודה של ref שמכילה ערכים של ObjectRef. לערכים של ObjectRef שנוצרו בקבוצות נתונים של Storage Insights אין הרשאה. כדי לשלוח שאילתות לאובייקטים האלה, צריך גישה ישירה לאובייקט או להוסיף הרשאה ל-ObjectRef כדי להשתמש בגישה מוקצית.

נותן ההרשאה וההרשאות

כשמעבירים ערך ObjectRef לפונקציות ObjectRef, לפונקציות AI או לפונקציות מוגדרות על ידי המשתמש (UDF) ב-Python, הפונקציות האלה צריכות לגשת לאובייקט שמאוחסן ב-Cloud Storage. אתם יכולים לאשר את הגישה הזו על סמך הערך של השדה authorizer בשתי דרכים: גישה ישירה וגישה בהרשאת נציג.

גישה ישירה

בגישה ישירה, המשתמש שמריץ את השאילתה ניגש לאובייקט ישירות באמצעות פרטי הכניסה שלו. גישה ישירה משמשת כשאין מאשר לערך ObjectRef.

הגישה הישירה כפופה להגבלות הבאות:

  • למשתמש צריכה להיות הרשאה לגשת לאובייקטים.
  • כדי להריץ שאילתה באמצעות הפונקציות AI.GENERATE,‏ AI.IF,‏ AI.SCORE או AI.CLASSIFY ללא חיבור, המשתמש צריך הרשאות נוספות. השאילתה יכולה לגשת רק לקטגוריות ולאובייקטים של Cloud Storage מאותו פרויקט שבו מורצת העבודה.

לדוגמה, אם קוראים לפונקציה AI.GENERATE על ערך ObjectRef שלא מוגדר לו מאשר הרשאה, הפונקציה קוראת את האובייקט כאילו אתם קוראים אותו. אם אין לכם הרשאה לקרוא את האובייקט, הפונקציה כותבת שגיאה "permission denied" בעמודה status בתוצאה.

בדוגמה הבאה מוצגת שאילתה שמשתמשת בגישה ישירה:

-- Requires that the end user can read the object "gs://cloud-samples-data/vision/demo-img.jpg" and use the Vertex AI model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")),
  endpoint => 'gemini-2.5-pro');

גישה שהוענקה

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

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

לדוגמה, אם משתמש מעביר ערכים של ObjectRef שיש להם הרשאת גישה לפונקציה AI.GENERATE, הפונקציה מאמתת שלמשתמש יש את ההרשאה bigquery.objectRefs.read, ואז קוראת את האובייקטים באמצעות חשבון השירות של החיבור. אם למשתמש או לחשבון השירות אין הרשאות מספיקות, הפונקציה כותבת שגיאת "permission denied" בעמודה status בתוצאה.

בדוגמה הבאה מוצגת שאילתה שמשתמשת בגישה מוקצית. כדי להשתמש בו, צריך:

  • למשתמש יש הרשאה bigquery.objectRefs.read ב-connection1.
  • לחשבון השירות של connection1 יש את ההרשאה storage.objects.get באובייקט.
  • לחשבון השירות של connection2 יש את התפקיד Agent Platform User.
SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1")),
  endpoint => 'gemini-2.5-pro',
  connection_id => "us.connection2");

שיטות מומלצות

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

  • אפשר להשתמש בגישה ישירה לצוות קטן שעובד בפרויקט יחיד לאחסון ולניתוח נתונים. אדמין הנתונים משתמש בניהול זהויות והרשאות גישה (IAM) כדי להעניק למשתמשים גישה לנתונים ב-BigQuery ולנתונים ב-Cloud Storage. המשתמשים יכולים ליצור ObjectRef ערכים על פי דרישה ללא הרשאה כדי לנתח אובייקטים באמצעות פרטי הכניסה שלהם.
  • מומלץ להשתמש בהענקת גישה לצוות גדול שעובד על כמה פרויקטים, במיוחד כשאחסון הנתונים והניתוח שלהם מופרדים. מנהל הנתונים יכול להגדיר חיבורים וליצור ערכי ObjectRef לניתוח מראש באמצעות חיבור כמאשר. הגישה הזו מתאימה לטבלאות אובייקטים או לשימוש ב-OBJ.MAKE_REF ברשימת URI. לאחר מכן, מנהל הנתונים יכול לשתף עם אנליסטים את הטבלה שבה מאוחסנים ערכי ObjectRef. האנליסטים לא צריכים לגשת לקטגוריה המקורית כדי לנתח את האובייקטים.

שגיאות

פונקציות שמשתמשות בערכים מסוג ObjectRef מדווחות על שגיאות בשתי דרכים:

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

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

שם סוג מצב תיאור דוגמה
code INT64 REQUIRED קוד שגיאת HTTP רגיל. 400
message STRING REQUIRED הודעת שגיאה תיאורית וידידותית למשתמש. "Connection credential for myproject.us.nonexistent_connection cannot be used. Either the connection does not exist, or the user does not have sufficient permissions (bigquery.objectRefs.read)"
source STRING REQUIRED שם הפונקציה שהפעילה את השגיאה. "OBJ.MAKE_REF"

אלה שני סוגים נפוצים של שגיאות:

  • שגיאת אובייקט: ה-URI או הגרסה של האובייקט שצוינו לא קיימים.
  • שגיאת הרשאה: החיבור לא קיים או שלמשתמש אין הרשאה להשתמש בו לגישה מוקצית.

השאילתה הבאה מראה איך בוחרים ערכי ObjectRef שמכילים שגיאות מעמודה Objectref:

SELECT ref
FROM mydataset.images
WHERE ref.details.errors IS NOT NULL;

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