עבודה עם ערכי 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

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

שימוש בפונקציה 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 או לפונקציות Python UDF, הפונקציות האלה צריכות לגשת לאובייקט שמאוחסן ב-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. יוצרים קישור חדש למשאבים ב-Cloud ב-BigQuery או משתמשים מחדש בקישור קיים בפרויקט.
  2. מחפשים את חשבון השירות במטא-נתונים של החיבור.
  3. נותנים לחשבון השירות את ההרשאה storage.objects.get לקריאה, או את ההרשאה storage.objects.create לכתיבה, בפרויקט או בקטגוריות של Cloud Storage. אפשר לתת את ההרשאות האלה באמצעות התפקידים Storage Object Viewer או Storage Object User.
• הגדרה לכל משתמש. מנהל הנתונים צריך לתת למשתמשים את ההרשאה 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 יש את התפקיד "משתמש בפלטפורמת הסוכן".

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 חתומה לאובייקט, וכתובות URL חתומות לא יכולות לחצות את גבולות ההיקף. הפונקציה כותבת את אחת מהשגיאות הבאות בעמודה status בתוצאה:

• INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC. השגיאה הזו מתרחשת אם ההיקף מגביל את Agent Platform.
• Cannot fetch content from the provided URL השגיאה הזו מתרחשת אם ההיקף מגביל את Cloud Storage.

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

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

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

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

שגיאות

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

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

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

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

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

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

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

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

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