שימוש בתבניות של שאילתות

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

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

מגבלות

לתבניות של שאילתות יש את המגבלות הבאות:

  • תבניות של שאילתות תומכות בשני קובצי עזר לכל היותר – כלומר, הנתונים שמשמשים להגדרת השאילתה של ה-TVF והקלט של פרמטר הנתונים שה-TVF מקבל. אפשר להפנות לכמה טבלאות או תצוגות בהגדרת השאילתה של ה-TVF, אבל כולן צריכות להיות שייכות לאותו בעלים או גורם של הנתונים.
  • פונקציות TVF של תבניות שאילתות תומכות רק בסוגים הקבועים TABLE ו-VIEW.
  • ההגדרות של תבניות השאילתות כפופות לאותן מגבלות כמו של פונקציות TVF.

תפקידים

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

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

כדי להפעיל את Analytics Hub API בפרויקט ב- Google Cloud , בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. נכנסים לדף Analytics Hub API במסוף Google Cloud .

    מעבר אל Analytics Hub API

  2. בסרגל הכלים של מסוף Google Cloud , בוחרים את הפרויקט.

  3. אם ה-API לא פועל, לוחצים על Enable.

gcloud

מריצים את הפקודה gcloud services enable:

gcloud services enable analyticshub.googleapis.com

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

כדי לקבל את ההרשאות שדרושות לביצוע המשימות שמפורטות במאמר הזה, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

כדי לבצע את המשימות שבמסמך הזה, נדרשות ההרשאות הבאות:

  • יצירה או מחיקה של TVF בחדר נקי לנתונים:
    • bigquery.routines.create בפרויקט
    • bigquery.routines.update בפרויקט
    • bigquery.routines.delete בפרויקט
  • נותנים הרשאה ל-TVF: bigquery.datasets.update במערכי הנתונים שאליהם השגרה ניגשת
  • יוצרים תבנית שאילתה:
    • analyticshub.listings.subscribe בפרויקט
    • analyticshub.queryTemplates.create בפרויקט
  • אישור תבנית של שאילתה:
    • bigquery.routines.create בפרויקט
    • bigquery.datasets.update במערכי הנתונים שהשגרה ניגשת אליהם
    • analyticshub.listings.create בפרויקט
    • analyticshub.queryTemplates.approve בפרויקט
  • עדכון של תבנית שאילתה קיימת: analyticshub.queryTemplates.update בתבנית השאילתה
  • אחזור פרטים של תבנית שאילתה: analyticshub.queryTemplates.get בתבנית השאילתה
  • הצגת רשימה של כל תבניות השאילתות בחילופי נתונים: analyticshub.queryTemplates.list בחילופי הנתונים
  • מחיקת תבנית שאילתה: analyticshub.queryTemplates.delete בתבנית השאילתה

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

מפתחות הצפנה בניהול הלקוח (CMEK)

אתם יכולים להגן על תבניות של שאילתות באמצעות מפתחות הצפנה בניהול הלקוח (CMEK) ב-Cloud Key Management Service ‏ (Cloud KMS).

אם אתם מספקים מפתח Cloud KMS משלכם, אתם צריכים להקצות את התפקיד Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) לסוכן השירות של שיתוף BigQuery בפרויקט שמכיל את החדר הנקי לנתונים, לדוגמה service-12345@gcp-sa-analyticshub.iam.gserviceaccount.com.

אם לפרויקט אין סוכן שירות לשיתוף ב-BigQuery, בעלי הפרויקט צריכים ליצור את סוכן השירות באמצעות הפעלת הפקודה gcloud beta services identity create:

gcloud beta services identity create --service=analyticshub.googleapis.com --project=my-dcr-project

מגבלות של CMEK

השימוש ב-CMEK עם תבניות של שאילתות כפוף למגבלות הבאות:

  • אי אפשר לערוך את המפתח: אחרי שיוצרים תבנית שאילתה עם מפתח Cloud KMS, אי אפשר לעדכן, לשנות או להסיר את המפתח בתבנית השאילתה הקיימת.
  • אין תמיכה בניהול גרסאות של מפתחות: אי אפשר להגדיר CMEK עם גרסה ספציפית של מפתח Cloud KMS. כשמציינים את מזהה המשאב של המפתח, צריך לציין את נתיב המפתח בלי מספר גרסה, לדוגמה: projects/my-kms-project/locations/us/keyRings/my-key-ring/cryptoKeys/my-key.

תהליכי עבודה של יוצרי תבניות

כיוצרים של תבניות שאילתות, אתם יכולים:

הוספת כרטיס מוצר לחדר נקי לנתונים

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

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

  2. לוחצים על השם המוצג של החדר הנקי לנתונים שבו רוצים ליצור את תבנית השאילתה.

  3. לוחצים על Add data ופועלים לפי השלבים ליצירת תצוגה עם כללי ניתוח מוגדרים. להוראות מפורטות, ראו יצירת כרטיס מוצר (הוספת נתונים).

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

  4. להגדיר אמצעי בקרה על יציאת נתונים למוצר.

  5. מגדירים את אמצעי הבקרה של המטא-נתונים של דף האפליקציה בחנות. אם רוצים לשתף רק את הסכימות והתיאורים של הנתונים שנוספו בשלב הקודם (ולא את הנתונים המשותפים עצמם), בוחרים באפשרות Exclude access to listing from linked dataset.

  6. בודקים את פרטי דף האפליקציה.

  7. לוחצים על הוספת נתונים. עכשיו ה-Clean Room כולל את המטא-נתונים של התצוגה שיצרתם לנתונים.

הוספת TVF קיים לחדר נקי לנתונים

אתם יכולים להוסיף TVF קיים לחדר נקי לנתונים באמצעות Analytics Hub API.

משתמשים בשיטה projects.locations.dataExchanges.listings.create.

בדוגמה הבאה מוסבר איך להפעיל את ה-method‏ projects.locations.dataExchanges.listings.create באמצעות הפקודה curl:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/listings?listingId=LISTING_ID -d \
    '{"bigqueryDataset":{"dataset":"projects/PROJECT_ID/datasets/DATASET_ID","selectedResources":[{"routine":"projects/PROJECT_ID/datasets/DATASET_ID/routines/ROUTINE_ID"}]},"displayName":"LISTING_NAME"}'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של החדר הנקי לנתונים.
  • ‫LISTING_ID: מזהה דף האפליקציה.
  • ‫PROJECT_ID: מזהה הפרויקט שמכיל את מערך הנתונים של המקור.
  • ‫DATASET_ID: מזהה מערך הנתונים של המקור.
  • ‫ROUTINE_ID: מזהה התרחיש.
  • ‫LISTING_NAME: השם המוצג של דף האפליקציה.

יצירת תבנית שאילתה

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

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

  2. לוחצים על השם המוצג של החדר הנקי לנתונים שבו רוצים ליצור את תבנית השאילתה.

  3. בחדר הנקי, עוברים לכרטיסייה Templates (תבניות).

  4. לוחצים על יצירת תבנית.

  5. מזינים שם תצוגה ותיאור לתבנית.

  6. לוחצים על הבא.

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

    • מגדירים את השאילתה באמצעות התחביר הנתמך של CREATE TABLE FUNCTION.

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

          query_template1(t1 TABLE<year INT64>) AS (SELECT * FROM `project_id.dataset_id.table_id` WHERE year = table_id.year)

    • אם החלתם על הנתונים כללים לניתוח פרטיות, ודאו שהפונקציה הזו כוללת תחביר SQL ספציפי לפרטיות, כמו SELECT WITH AGGREGATION_THRESHOLD.

  8. בודקים את פרטי התבנית.

  9. כדי לשמור את התבנית בלי לשלוח אותה לבדיקה, לוחצים על שמירה. הסטטוס של תבנית השאילתה הוא עכשיו DRAFT.

אתם יכולים לעדכן את תבנית השאילתה או לשלוח את תבנית השאילתה לבדיקה.

API

בדוגמה הבאה מוסבר איך ליצור תבנית שאילתה באמצעות הפקודה curl:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates?queryTemplateId=QUERY_TEMPLATE_ID -d \
'{
  "displayName": "DISPLAY_NAME",
  "routine": {
    "routineType": "TABLE_VALUED_FUNCTION",
    "definitionBody": "QUERY_TEMPLATE_ID(TVF arguments) AS (TVF_DEFINITION)"
  }
}'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של החדר הנקי לנתונים.
  • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.
  • ‫DISPLAY_NAME: השם המוצג של תבנית השאילתה. אי אפשר לעדכן את השם המוצג של תבנית השאילתה אחרי שיוצרים אותה.
  • ‫TVF_DEFINITION: הגדרת ה-TVF.

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

  query_template1(t1 TABLE<year INT64>) AS (SELECT * FROM `project_id.dataset_id.table_id` WHERE year = table_id.year)

ה-definition_body דומה להגדרה של שגרה. הקוד הקודם של definition_body מתורגם לשגרה הבאה:

  CREATE OR REPLACE TABLE FUNCTION APPROVERS_DATASET.query_template1(t1 TABLE, y INT64)
  AS (SELECT * FROM t1 WHERE year > y)

מחליפים את APPROVERS_DATASET במזהה של קבוצת הנתונים שבה מי שמאשר התבנית יוצר את התרחיש.

אתם יכולים לעדכן את תבנית השאילתה או לשלוח את תבנית השאילתה לבדיקה.

עדכון של תבנית שאילתה

אפשר לעדכן תבנית של שאילתה רק אם היא בסטטוס טיוטה. אחרי ששולחים תבנית שאילתה לבדיקה, אי אפשר לשנות אותה.

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

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

  2. לוחצים על השם המוצג של החדר הנקי לנתונים שמכיל את תבנית השאילתה.

  3. בחדר הנקי, עוברים לכרטיסייה תבניות.

  4. בשורה של התבנית שרוצים לעדכן, לוחצים על פעולות > עריכת התבנית.

  5. מעדכנים את התיאור ואת איש הקשר הראשי לפי הצורך.

  6. לוחצים על הבא.

  7. בודקים את פרטי התבנית.

  8. כדי לשמור את התבנית בלי לשלוח אותה לבדיקה, לוחצים על שמירה.

API

בדוגמה הבאה מוסבר איך לעדכן תבנית של שאילתה באמצעות הפקודה curl:

 curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H 'x-goog-user-project:DCR_PROJECT_ID' \
 -X PATCH "https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID?updateMask=description" \
 -d '{
   "description": "New query template"
 }'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של החדר הנקי לנתונים.
  • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.

שליחת תבנית שאילתה לבדיקה

כדי לשלוח תבנית של שאילתה לבדיקה, בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

  2. לוחצים על השם המוצג של החדר הנקי לנתונים שמכיל את תבנית השאילתה.

  3. בחדר הנקי, עוברים לכרטיסייה תבניות.

  4. בשורה של התבנית שרוצים לשלוח לבדיקה, לוחצים על פעולות > שליחה לבדיקה. הסטטוס של התבנית הוא עכשיו נדרשת בדיקה.

API

בדוגמה הבאה מוסבר איך לשלוח תבנית שאילתה לבדיקה באמצעות הפקודה curl:

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID:submit

מחליפים את מה שכתוב בשדות הבאים:

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של החדר הנקי לנתונים.
  • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.

מחיקת תבנית של שאילתה

אפשר למחוק תבנית של שאילתה רק אם היא בסטטוס DRAFT. אחרי ששולחים תבנית שאילתה לבדיקה, אי אפשר למחוק אותה.

כדי למחוק תבנית שאילתה, בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

  2. לוחצים על השם המוצג של החדר הנקי לנתונים שמכיל את תבנית השאילתה.

  3. בחדר הנקי, עוברים לכרטיסייה תבניות.

  4. בשורה של התבנית שרוצים למחוק, לוחצים על Actions > Delete template.

API

בדוגמה הבאה מוסבר איך למחוק תבנית של שאילתה באמצעות הפקודה curl:

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X DELETE https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID

מחליפים את מה שכתוב בשדות הבאים:

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של החדר הנקי לנתונים.
  • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.

תהליכי עבודה של אישור תבניות

כמאשרים של תבניות שאילתות, אתם יכולים לאשר תבנית שאילתה.

כשפונקציה עם ערך טבלה מפנה לנתונים שלא בבעלותכם – למשל, נתונים של שותף אחר – רק הבעלים של הנתונים האלה יכול לאשר את תבנית השאילתה. אם אתם יוצרים TVF שמפנה רק לנתונים שלכם לשיתוף בכיוון אחד, אתם יכולים לאשר את תבנית השאילתה בעצמכם.

אישור תבנית שאילתה

כדי לאשר תבנית שאילתה, בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. במסוף Google Cloud , נכנסים לדף שיתוף (מאגר הניתוחים ב-Analysis).

    מעבר אל Sharing (Analytics Hub)

  2. לוחצים על השם המוצג של החדר הנקי לנתונים שמכיל את תבנית השאילתה.

  3. בחדר הנקי, עוברים לכרטיסייה תבניות.

  4. בשורה של התבנית שצריך לבדוק, לוחצים על סטטוס אישור > נדרשת בדיקה.

  5. לוחצים על אישור.

  6. בוחרים את המיקום של התבנית. זה המיקום שבו נוצרת פונקציית ה-TVF לשיתוף.

  7. בודקים את תבנית השאילתה המוצעת.

  8. כדי לאשר את תבנית השאילתה לשימוש בחדר הנקי לנתונים, לוחצים על Approve.

API

  1. יוצרים את השגרה מתבנית השאילתה באמצעות קריאה ל-method jobs.query:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://bigquery.googleapis.com/bigquery/v2/projects/ROUTINE_PROJECT_ID/queries --data '{"query":"ROUTINE_CREATION_QUERY","useLegacySql":false}'

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫ROUTINE_PROJECT_ID: מזהה הפרויקט שבו נוצרה השגרה.
    • ‫ROUTINE_CREATION_QUERY: השאילתה ליצירת השגרה.

  2. מוסיפים את השגרה שיצרתם לחדר הנקי לנתונים:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H 'x-goog-user-project:DCR_PROJECT_ID' -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/listings?listingId=LISTING_ID -d \
'{"bigqueryDataset":{"dataset":"projects/PROJECT_ID/datasets/DATASET_ID","selectedResources":[{"routine":"projects/PROJECT_ID/datasets/DATASET_ID/routines/ROUTINE_ID"}]},"displayName":"LISTING_NAME"}'

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
    • ‫LOCATION: המיקום של החדר הנקי לנתונים.
    • ‫CLEAN_ROOM_ID: המזהה של החדר הנקי לנתונים.
    • ‫LISTING_ID: מזהה דף האפליקציה.
    • ‫PROJECT_ID: מזהה הפרויקט שמכיל את מערך הנתונים של המקור.
    • ‫DATASET_ID: מזהה מערך הנתונים של המקור.
    • ‫ROUTINE_ID: מזהה התרחיש.
    • ‫LISTING_NAME: השם המוצג של דף האפליקציה.

  3. מעדכנים את הסטטוס של תבנית השאילתה ל-APPROVED:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID/queryTemplates/QUERY_TEMPLATE_ID:approve  --data '{}'

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
    • ‫LOCATION: המיקום של החדר הנקי לנתונים.
    • ‫CLEAN_ROOM_ID: המזהה של החדר הנקי לנתונים.
    • ‫QUERY_TEMPLATE_ID: מזהה תבנית השאילתה.

דחיית תבנית שאילתה

במסוף Google Cloud , אתם יכולים לדחות תבנית שאילתה על ידי אי-אישור של תבנית השאילתה שנשלחה לבדיקה.

תהליכי עבודה של תבניות למנויים

מנוי לתבנית שאילתה יכול לראות חדר נקי לנתונים ולהירשם אליו. אם רק תבנית השאילתה נוספה לחדר הנקי, ההרשמה לחדר הנקי מעניקה גישה רק ל-TVF התואם, ולא לנתונים המשותפים הבסיסיים.

הרשמה לתבנית שאילתה

כדי להירשם לתבנית שאילתה, בוחרים באחת מהאפשרויות הבאות:

המסוף

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

אחרי שנרשמים לחדר הנקי לנתונים, פועלים לפי השלבים הבאים כדי להריץ תבנית שאילתה:

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

  2. בחלונית Explorer, עוברים למערך הנתונים המקושר שיצרתם כשנרשמתם ל-Clean Room.

  3. פותחים את השגרה או את ה-TVF שמשותפים במערך הנתונים המקושר.

  4. לוחצים על Invoke table function.

  5. מחליפים את הפרמטר בקלט המקובל, שהוא שם הטבלה או שדה.

  6. לוחצים על Run.

אם אתם לא רואים את ה-TVF בתור רכיב צאצא של מערך הנתונים המקושר בחלונית Explorer, אתם יכולים לשלוח שאילתה ל-TVF ישירות במערך הנתונים המקושר:

SELECT * FROM `my_project.dcr_linked_dataset.mytvf`(TABLE myTable);

API

משתמשים בשיטה projects.locations.dataExchanges.subscribe.

בדוגמה הבאה מוסבר איך להפעיל את ה-method‏ projects.locations.dataExchanges.subscribe באמצעות הפקודה curl:

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -L -X POST https://analyticshub.googleapis.com/v1/projects/DCR_PROJECT_ID/locations/LOCATION/dataExchanges/CLEAN_ROOM_ID:subscribe  --data '{"destination":"projects/SUBSCRIBER_PROJECT_ID/locations/LOCATION","subscription":"SUBSCRIPTION"}'

מחליפים את מה שכתוב בשדות הבאים:

  • ‫DCR_PROJECT_ID: מזהה הפרויקט שבו נוצר החדר הנקי לנתונים.
  • ‫LOCATION: המיקום של החדר הנקי לנתונים.
  • ‫CLEAN_ROOM_ID: המזהה של החדר הנקי לנתונים.
  • ‫SUBSCRIBER_PROJECT_ID: מזהה הפרויקט של הפרויקט המנוי לתבנית.
  • ‫SUBSCRIPTION: שם המינוי.

אחרי שנרשמים לתבנית השאילתה, אפשר לשלוח שאילתה ל-TVF ישירות במערך הנתונים המקושר:

SELECT * FROM `my_project.dcr_linked_dataset.mytvf`(TABLE myTable);

תרחישים לדוגמה

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

תרחיש של שיתוף בכיוון אחד

בעל תוכן דיגיטלי של נתונים יוצר תבנית שאילתה, כדי ששותפים מנויים יוכלו להריץ רק את השאילתות שבעל התוכן הדיגיטלי מגדיר. יוצרי תבניות השאילתות מאשרים בעצמם את תבניות השאילתות, כי לא נוספו תורמים אחרים ל-Clean Room.

בתרחיש הזה, משתמש א' הוא הבעלים של חדר נקי לנתונים. הוא יוצר חדר נקי לנתונים בשם campaign_analysis ומוסיף קבוצת נתונים בשם my_campaign עם טבלה בשם campaigns. משתמש א' מגדיר מדיניות של סף צבירת נתונים ואמצעי בקרה על מטא-נתונים, כך שרק סכימת המטא-נתונים גלויה ולמנויי התבנית אין גישה לנתוני המקור. לאחר מכן, משתמש א' יוצר תבנית שאילתה על ידי הגדרת TVF מהטבלה campaigns, ומגביל את המנויים של מערך הנתונים המקושר להרצת ה-TVF בלבד.

זה התחביר של TVF:

campaigns_template(t1 TABLE<campaign_ID STRING>) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, sum(impressions) FROM my_project.my_campaign.campaigns
group by company_id, company
);

למשתמש א' יש את ההרשאות המתאימות לטבלה campaigns עם התפקיד "בעלים של נתונים ב-BigQuery", ולכן הוא יכול לאשר בעצמו את תבנית השאילתה מיד אחרי שהוא שולח אותה לבדיקה.

שיתוף פעולה עם כמה משתמשים

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

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

זה התחביר של TVF:

campaigns_template(t1 TABLE<campaign_ID STRING>) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, sum(impressions) FROM my_project.my_campaign.campaigns
group by company_id, company
);

מכיוון שמשתמש ב' לא הוסיף את הטבלה campaigns והיא לא בבעלותו, רק משתמש א' יכול לאשר את תבנית השאילתה אחרי שהיא נשלחת לבדיקה. כדי להשתמש בתבנית השאילתה, משתמש ב' צריך להירשם ל-Clean Room ולהפעיל את ה-TVF. משתמש ב' מעביר טבלה משלו עם שדה בשם campaign_ID בתור הפרמטר של הטבלה, והוא יכול להריץ את ה-SQL שמתמקד בפרטיות ומוגדר בתבנית השאילתה. משתמש ב' לא צריך להוסיף את הנתונים שלו לחדר הנקי.

משתמש ב' מוסיף גם הוא ל-Clean Room מערך נתונים בשם my_transactions, שכולל טבלה בשם transactions וטבלה בשם products. משתמש ב' מגדיר מדיניות של סף צבירת נתונים ואמצעי בקרה על מטא-נתונים, כך שרק סכימת המטא-נתונים גלויה ולמנויים של התבנית אין גישה לנתוני המקור.

עכשיו משתמש א' יכול להציע תבניות שונות של שאילתות כדי לצרף את הנתונים שלו לטבלה transactions, על ידי צפייה בסכימת המטא-נתונים של הטבלה. הנה כמה דוגמאות לתחביר של פונקציות TVF:

transactions_template(t1 TABLE<user_ID STRING>) AS (
SELECT WITH AGGREGATION_THRESHOLD company_id, company, campaign_id, sku, category, date, sum(amount) FROM my_project.my_transactions.transactions
group by company_id, company, campaign_id, sku, category, date
);

transactions_template_with_join(t1 TABLE<user_ID STRING>) AS (
SELECT WITH AGGREGATION_THRESHOLD t.company_id, t.company, t.campaign_id, t.sku, t.date, p.product_name, p.product_category, sum(t.amount) FROM my_project.my_transactions.transactions t
left join my_project.my_transactions.products p
on t.product_id = p.product_id
group by t.company_id, t.company, t.campaign_id, t.sku, t.date, p.product_name, p.product_category
);

מכיוון שמשתמש א' לא הוסיף את הטבלאות transactions ו-products והן לא בבעלותו, רק משתמש ב' יכול לאשר את תבנית השאילתה אחרי שהיא נשלחת לבדיקה. כדי להשתמש בתבנית השאילתה, משתמש א' צריך להירשם ל-Clean Room ולהפעיל את ה-TVF. משתמש א' מעביר טבלה משלו עם שדה בשם user_ID כפרמטר הטבלה, והוא יכול להריץ את ה-SQL שמתמקד בפרטיות ומוגדר בתבנית השאילתה. משתמש א' לא צריך להוסיף את הנתונים שלו ל-Clean Room.

תמחור

בטבלה הבאה מפורטים המחירים של תבניות השאילתות בחדר הנקי לנתונים ב-BigQuery:

תפקיד פרטי התמחור
תורם נתונים החיוב הוא רק על אחסון הנתונים.
מנוי לתבנית חיוב רק על מחשוב (ניתוח) כשמריצים שאילתות.

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