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

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

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

סכימה

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

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

יצירת ObjectRef ערכים

אפשר ליצור ערכי ObjectRef באמצעות טבלאות אובייקטים, הפונקציה OBJ.MAKE_REF, הפונקציה OBJ.LIST או מערכי נתונים של 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 מהכתובות האלה. השאילתות הבאות מראות איך ליצור ערכים של 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 כדי לתמוך בגישה ישירה ובגישה מוענקת.

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

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

השימוש ב-OBJ.LIST מייתר את הצורך ליצור ערכים של ObjectRef באופן ידני בטבלה קבועה. אתם יכולים להוסיף במהירות אובייקטים של Cloud Storage לפונקציות AI כדי ליצור צינורות ETL ספונטניים שמטפלים בהמרת נתונים לא מובְנים לנתונים מובְנים. אם אתם צריכים טבלה קבועה שמתעדכנת באופן עצמאי ועוקבת באופן רציף אחרי אובייקטים חדשים שמגיעים לקטגוריה לאורך זמן, כדאי ליצור במקום זאת טבלת אובייקטים רגילה ב-BigQuery.

בשאילתה הבאה נעשה שימוש בתו הכללי (*) כדי לגלות סוגים ספציפיים של קבצים, ונעשה שימוש בפונקציה AI.IF כדי לסנן נתונים לא מובנים. השאילתה הזו מציגה רק את קובצי ה-PNG שמכילים תמונה של כלב.

SELECT
  uri,
  content_type,
  size
FROM
  OBJ.LIST('gs://mybucket/images/*.png')
WHERE
  AI.IF(('Does this image contain a dog?', ref))
ORDER BY
  uri;

שימוש במערכי נתונים של 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")));

גישה שהוענקה

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

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

• הגדרה חד-פעמית. אדמין הנתונים צריך להגדיר קישור למשאבים ב-Cloud כדי לנהל את קטגוריית Cloud Storage:
  1. יוצרים חיבור חדש למשאב BigQuery Cloud או משתמשים בחיבור קיים בפרויקט.
  2. מחפשים את חשבון השירות במטא-נתונים של החיבור.
  3. מעניקים לחשבון השירות את ההרשאה storage.objects.get לקריאה או את ההרשאה storage.objects.create לכתיבה בפרויקט או בקטגוריות של Cloud Storage. אפשר להעניק את ההרשאות האלה באמצעות התפקידים צפייה באובייקט אחסון או משתמש באובייקט אחסון.
• הגדרה לכל משתמש. אדמין הנתונים צריך להעניק למשתמשים את ההרשאה bigquery.objectRefs.read לקריאה או את ההרשאה bigquery.objectRefs.write לכתיבה בחיבור ל-BigQuery. אפשר להעניק את ההרשאות האלה באמצעות התפקידים BigQuery ObjectRef Reader או BigQuery ObjectRef Admin.

לדוגמה, אם משתמש מעביר ערכים של 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")),
  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. אם כן, הערך של השדה הזה הוא מערך של שגיאות. לכל שגיאה יש את הסכימה הבאה:

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

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

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

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

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

• מציינים עמודות ObjectRef בסכימות של טבלאות.
• ניתוח נתונים מרובי-אופנים.
• מידע נוסף על פונקציות ObjectRef