עבודה עם ערכי 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 מקבלת אמצעי אימות שאפשר להגדיר כ-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 Agent Platform model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")),
  endpoint => 'gemini-2.5-pro');

גישה שהוענקה

בגישה מואצלת, המשתמש שמריץ את השאילתה מעניק גישה לאובייקט לקישור למשאבים ב-Cloud של BigQuery, שמוגדר בשדה 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");

בתוך גבולות גזרה של VPC Service Controls, פונקציות AI לא יכולות לעבד ערכים של ObjectRef שמשתמשים בגישה מוקצית. גישה בהרשאת משנה יוצרת כתובת URL חתומה בפרוטוקול HTTPS לאובייקט, ופלטפורמת הנציגים של Gemini Enterprise חוסמת אחזור של HTTP ו-HTTPS לפרויקטים בתוך היקף. הפונקציה כותבת את השגיאה הבאה בעמודה status בתוצאה:

INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC.

מכיוון שהעמודה ref של טבלת אובייקטים תמיד משתמשת בחיבור של טבלת האובייקטים כמאשר, העברת ref לפונקציית AI בתוך גבולות גזרה תמיד מחזירה את השגיאה הזו. כדי לנתח את האובייקט, מעבירים במקום זאת ערך של OBJ.MAKE_REF(uri) עם ארגומנט יחיד, שמשתמש בגישה ישירה ושולח את ה-URI של Cloud Storage למודל בלי ליצור כתובת URL חתומה.

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

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

  • מומלץ להשתמש בגישה ישירה לצוות קטן שעובד בפרויקט יחיד לאחסון ולניתוח נתונים. אדמין הנתונים משתמש בניהול זהויות והרשאות גישה (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;

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