החל מ-10 באפריל 2026, Dataplex Universal Catalog נקרא עכשיו Knowledge Catalog. השמות של ה-API, ספריית הלקוח, ה-CLI ו-IAM לא משתנים. מידע נוסף זמין במאמר הכרות עם קטלוג הידע של Google Cloud.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

ייבוא מטא-נתונים מ-dbt Core

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

כדי לשלב את המידע הזה בקטלוג המרכזי, אפשר לייבא מטא-נתונים מ-dbt Core,‏ dbt Cloud ו-MetricFlow אל Knowledge Catalog (לשעבר Dataplex Universal Catalog).

מכיוון ש-dbt Core פועל כמנוע טרנספורמציה ולא כמערכת אחסון כמו Oracle או PostgreSQL, ייבוא המטא-נתונים שלו מאפשר תרחישי שימוש שונים. אתם מייבאים מטא-נתונים של Oracle או PostgreSQL כדי לענות על השאלה 'אילו נתונים גולמיים יש לנו?', ומייבאים מטא-נתונים של dbt Core כדי לענות על השאלה 'איך הנתונים שלנו עוברים טרנספורמציה, האם הם מהימנים ומה המשמעות שלהם לעסק?'.

במאמר הזה מוסבר איך לייבא מטא-נתונים באמצעות הפקודה Google Cloud CLI וקובצי הארטיפקט של dbt.

כשמריצים את השילוב של dbt, המערכת מתעדת את המטא-נתונים הבאים:

מטא-נתונים טכניים: גילוי נתונים ארגוניים על ידי עיון במשאבים מרכזיים (מקורות, נתונים ראשוניים, מודלים) ובמאפיינים הטכניים שלהם (שמות עמודות, סוגי נתונים, מספר שורות).
מטא-נתונים עסקיים וסמנטיים: מתן הקשר לכלי BI ולסוכני AI באמצעות עיון בהגדרות עסקיות ובלוגיקה שמבוססת על dbt MetricFlow, כמו מודלים סמנטיים, מדדים ושאילתות שמורות.
מטא-נתונים תפעוליים ומטא-נתונים של איכות הנתונים: כדי לעקוב אחרי תקינות צינור עיבוד הנתונים ולפתור בעיות בנתונים, אפשר לבדוק מטא-נתונים של ביצועים כמו תזמון, סטטוס הצלחה או כישלון, עדכניות הנתונים ותוצאות הבדיקה.
מטא-נתונים של שושלת וקשרים: אפשר לנתח את ההשפעה במורד הזרם ולעקוב אחרי שורש הבעיה על ידי עיון בתרשימי טרנספורמציה (DAG) ובתלות בין משאבי dbt, בשושלת פיזית שעוקבת אחרי בלוקים של טרנספורמציה פיזית ומקשרת ביניהם, במפתחות של צירופים ובצירופים דינמיים, וגם בקשרים של הורה/צאצא.
מטא-נתונים של צריכה: כדי לפתור בעיות שקשורות לאופן שבו אפליקציות במורד הזרם צורכות נתונים שעברו טרנספורמציה, אפשר לעיין במטא-נתונים שמתועדים בחשיפות שממפות את אופן השימוש בנתונים מחוץ ל-dbt.

מגבלות

תמיכה ב-dbt Core v1 (אומת בגרסאות 1.11 ו-1.12), ב-dbt Core v2 וב-dbt Fusion.
גרסה 586.0.0 ואילך של ה-CLI של gcloud תומכות בשילוב של dbt ו-BigQuery. הוראות להתקנה או לעדכון של ה-CLI מופיעות במאמר התקנת Google Cloud CLI.
אין חיבור ישיר ל-dbt Cloud. כדי לייבא מטא-נתונים ממשימת dbt Cloud, צריך קודם לאחזר את הארטיפקטים של המשימה. איך מייבאים מטא-נתונים מהרצות של dbt Cloud
סכימות גדולות מאוד או עם קינון עמוק נחתכות: גודל של היבט יחיד לא יכול לחרוג מהמגבלה, ולכן יכול להיות שסכימות עם קינון עמוק יאבדו שדות בסוף.
--aspects-only יכול להוסיף ולרענן את המטא-נתונים, אבל לא להסיר אותם. כדי למחוק משאב dbt, צריך להריץ את כל התהליך.
השילוב הזה תומך רק באירועי שושלת נתונים של dbt במשאבי BigQuery ב-API ובגרף של Data Lineage. רשומות dbt (מקורות, נתונים ראשוניים, מודלים) למקורות חיצוניים של צד שלישי לא נכללות בשושלת הנתונים.
- כדי להטמיע את כל אירועי השושלת של dbt ב-Data Lineage API, משתמשים בשילוב OpenLineage dbt. לאחר מכן, משלבים את OpenLineage עם Knowledge Catalog כדי לייבא ולהציג את שרשרת מקורות הנתונים מ-dbt.

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

כדי לייבא מטא-נתונים מ-dbt Core ומ-MetricFlow, צריך לבצע את המשימות הבאות:

נותנים את התפקידים וההרשאות הנדרשים.
הפעלת Knowledge Catalog API
עמידה בדרישות המוקדמות של dbt.
יוצרים את קבוצת הכניסה של היעד אם היא עדיין לא קיימת.
הסבר על התפקידים ב-Cloud Storage

תפקידים והרשאות של IAM

כדי ליצור ולנהל עבודת מחבר של Knowledge Catalog, אתם צריכים תפקידים בניהול הזהויות והרשאות הגישה (IAM) שמעניקים הרשאות ל-Knowledge Catalog ול-Cloud Storage.

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

כדי ליצור ולנהל קבוצות של רשומות וקישורים לרשומות: אדמין של Dataplex Catalog (roles/dataplex.catalogAdmin), עורך של Dataplex Catalog (roles/dataplex.catalogEditor) או בעלים של קבוצת רשומות ב-Dataplex (roles/dataplex.entryGroupOwner) בפרויקט.
כדי להריץ את הפקודה dbt gcloud וליצור משימות ייבוא של מטא-נתונים: פועלים לפי העיקרון של הרשאות מינימליות ומקצים את התפקידים הבאים:
- ‫Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) בפרויקט.
- ‫Dataplex Entry Group Importer‏ (roles/dataplex.entryGroupImporter) בקבוצת הרשומות של היעד או בפרויקט. אם מייבאים גם קישורים לרשומות, צריך להעניק את ההרשאה Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) בפרויקט. צריך גם להעניק את התפקיד Dataplex Entry Owner (roles/dataplex.entryOwner) בכל פרויקט שמכיל את הטבלאות ב-BigQuery שהמודלים של dbt כותבים אליהן. לתפקידים בהתאמה אישית, ההרשאות של קישור הכניסה הן dataplex.entryGroups.useReferenceEntryLink,‏ dataplex.entryGroups.useSchemaJoinEntryLink ו-dataplex.entryLinks.reference.
אפשרות אחרת היא להקצות את התפקיד Dataplex Catalog Admin (roles/dataplex.catalogAdmin) ואת התפקיד Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) בפרויקט.
כדי להעלות מטא-נתונים שעברו טרנספורמציה לקטגוריית הביניים של הפלט (--storage-uri): יצירת אובייקטים באחסון (roles/storage.objectCreator) או אדמין של אובייקטים באחסון (roles/storage.objectAdmin) בקטגוריית הביניים.
כדי לקרוא ארטיפקטים של dbt מקטגוריית Cloud Storage של קלט (--artifacts-path, אם משתמשים ב-Cloud Storage): Storage Object Viewer (roles/storage.objectViewer) או Storage Object Admin (roles/storage.objectAdmin) בקטגוריית הארטיפקטים של הקלט. אם יש לכם את התפקיד Storage Object Admin, לא נדרש התפקיד Storage Object Viewer.
כדי להציג מטא-נתונים של dbt: Dataplex Catalog Viewer (roles/dataplex.catalogViewer) בפרויקט.
כדי לצפות ביומנים ב-Cloud Logging: מציג היומנים (roles/logging.viewer) בפרויקט.

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

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

אם מריצים את הייבוא באמצעות חשבון שירות, למשל בצינור עיבוד נתונים אוטומטי של CI/CD, אפשר להקצות את התפקידים האלה לחשבון השירות על ידי הרצת הפקודות הבאות של gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

בנוסף, צריך להקצות לסוכן השירות של Knowledge Catalog‏ (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) את התפקיד Storage Object Viewer‏ (roles/storage.objectViewer) בקטגוריה של Cloud Storage שמשמשת כשלב ביניים לפלט (--storage-uri), כדי שעבודת הייבוא תוכל לקרוא את קובץ המטא-נתונים שמוכן להעברה.

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

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

‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
USER_EMAIL: כתובת האימייל בחשבון שלכם.
SERVICE_ACCOUNT_EMAIL: כתובת האימייל בחשבון השירות.
‫STAGING_BUCKET: השם של קטגוריית Cloud Storage של פלט הביניים (--storage-uri).
‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .

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

הפעלת ממשקי ה-API

מפעילים את Knowledge Catalog API.

להפעלת ה-API

דרישות מוקדמות ל-dbt

כדי לייבא את כל המטא-נתונים של dbt, מומלץ ליצור את כל ארבעת קובצי הארטיפקט של dbt בפורמט JSON. רק manifest.json הוא שדה חובה. שאר השדות משפרים את הייבוא, וההמרות מתבצעות בצורה חלקה גם בלעדיהם:

‫manifest.json (חובה): מבנה הפרויקט המרכזי וגרף הביצוע. הוא כולל גם את המודלים הסמנטיים, המדדים והשאילתות השמורות של MetricFlow.
‫catalog.json: שמות העמודות וסוגי הנתונים. בלי catalog.json, היבט הסכימה מיובא עם עמודות לא מוקלדות.
‫run_results.json: תוצאות הבדיקה ומטא-נתונים של ההרצה.
sources.json: רעננות המקור.

בטרמינל המקומי, ב-Cloud Shell או בסביבת CI/CD אוטומטית שבה dbt מותקן, עוברים לספריית הבסיס של פרויקט dbt ומריצים את פקודות dbt הבאות לפי הסדר מול פרופיל ויעד יחידים כדי ליצור את כל קובצי ה-JSON של ארטיפקטים של מטא-נתונים של dbt:

ל-dbt Core 2.x ול-dbt Fusion:
1. dbt source freshness
2. dbt build
3. dbt parse --write-catalog
  
  אזהרה: אין להשתמש ב-dbt docs generate ב-dbt Core 2.x או ב-dbt Fusion. הוא לא כותב catalog.json, והוא דורס את run_results.json בלי תוצאות בדיקה. dbt build --write-catalog לא כותב קטלוג, לכן צריך להשתמש בשלב נפרד של dbt parse --write-catalog.
ב-dbt Core 1.x (כאשר dbt parse לא כותב קטלוג):
1. dbt source freshness
2. dbt build
3. dbt docs generate --no-compile
  
  אזהרה: בלי --no-compile, ‏ dbt docs generate מחליף את run_results.json בסטטוס success בכל צומת. תוצאות הבדיקה מהשלב הקודם dbt build יאבדו, ובדוח הקטלוג יופיע שכל בדיקת איכות הנתונים עברה בהצלחה.

הסבר על תפקידים ב-Cloud Storage

ייבוא מטא-נתונים של dbt כולל שני מיקומים נפרדים ב-Cloud Storage שמיועדים למטרות שונות, ולכן לא כדאי לערבב ביניהם:

קלט (ארטיפקטים של מקור dbt): המקום שבו נמצאים קובצי ה-JSON של dbt שנוצרו. זה יכול להיות נתיב של ספרייה מקומית במחשב או ב-CI runner (למשל ./target/ או .) או קידומת של מזהה URI של קטגוריה של Cloud Storage (למשל gs://my-dbt-artifacts-bucket/target/). את הנתיב הזה מציינים באמצעות הדגל --artifacts-path. הפקודה gcloud קוראת את קובצי הקלט האלה במהלך הכנת העבודה. אם משתמשים ב-Cloud Storage, למשתמש שמפעיל את הפקודה gcloud צריכה להיות גישת קריאה (roles/storage.objectViewer או roles/storage.objectAdmin). לסוכן השירות של Knowledge Catalog לא נדרשת גישה לקטגוריית האחסון של ארטיפקטים של קלט.
פלט (קטגוריית אחסון זמני לייבוא ל-Knowledge Catalog): קידומת של URI של קטגוריה של Cloud Storage (למשל gs://my-staging-bucket/dbt-imports/) שאליה הפקודה gcloud מעלה את קובץ הייבוא של המטא-נתונים שעברו טרנספורמציה (dbt_metadata.jsonl), ושממנה קורא תהליך הייבוא ל-Knowledge Catalog במהלך הטמעת הנתונים. אתם מספקים את ה-URI הזה באמצעות הדגל --storage-uri. למבצע הקריאה שמריץ את הפקודה gcloud צריכה להיות הרשאת כתיבה (roles/storage.objectCreator או roles/storage.objectAdmin) כדי להעלות את הקובץ, ולסוכן השירות של קטלוג הידע צריכה להיות הרשאת קריאה (roles/storage.objectViewer) כדי לייבא אותו.

ייבוא מטא-נתונים מהרצות של dbt Cloud

אי אפשר להתחבר ישירות ל-dbt Cloud מ-Knowledge Catalog. מכיוון שעבודת dbt Cloud יוצרת את אותם קובצי ארטיפקט כמו dbt Core, אפשר לייבא מטא-נתונים מ-dbt Cloud על ידי אחזור קובצי הארטיפקט האלה לספרייה מקומית או לקטגוריית קלט של Cloud Storage והפעלת הפקודה gcloud.

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

הורדת ארטיפקטים ממסוף dbt Cloud: הורדה ידנית של קובצי הארטיפקטים מדף הפרטים של הרצת העבודה בממשק המשתמש של dbt Cloud לייבוא חד-פעמי או לבדיקה ראשונית.
הורדת ארטיפקטים באמצעות dbt platform CLI: מריצים פקודות dbt ב-dbt Cloud מהטרמינל המקומי כדי לשמור אוטומטית את הארטיפקטים שנוצרו בספריית הפרויקט המקומית במהלך הפיתוח.
הורדת ארטיפקטים באמצעות dbt Administrative API: אחזור ארטיפקטים באופן פרוגרמטי מריצות שהושלמו באמצעות HTTP לצינורות אוטומטיים ומתוזמנים.

הגדרת משימת dbt Cloud

במסוף dbt Google Cloud , מגדירים את הגדרות העבודה כדי ליצור את כל ארטיפקטי המטא-נתונים:

בקטע Execution settings (הגדרות ההרצה), בוחרים באפשרות Run source freshness (הרצת רעננות המקור). מערכת dbt Cloud מריצה את הפקודה dbt source freshness לפני פקודות העבודה כדי ליצור את sources.json.
בקטע Commands מוסיפים את הערך dbt build.
מוסיפים פקודה ליצירת catalog.json בהתאם למסלול ההפצה:
- ל-dbt Core 2.x ולמסלולי ההפצה של dbt Fusion: מוסיפים את dbt parse --write-catalog כפקודת עבודה.
- לגרסאות dbt Core 1.x: מוסיפים את dbt docs generate --no-compile כפקודת עבודה במקום לבחור באפשרות Generate docs on run. אם מסמנים את תיבת הסימון Generate docs on run, הפקודה dbt docs generate מופעלת בלי --no-compile, וכך התוצאות של הבדיקה מוחלפות בתוצאות של dbt build, כמו שמתואר בדרישות המוקדמות של dbt. שימו לב: אם שלב הפקודה נכשל, גם המשימה נכשלת. לעומת זאת, אם שלב תיבת הסימון נכשל, המשימה לא נכשלת.

אם dbt build נכשל, למשל בגלל שהבדיקה נכשלה, dbt Cloud מדלג על הפקודות שאחריו וההרצה לא כוללת catalog.json. כדי ליצור תמיד קובץ אחד, מוסיפים את פקודת הקטלוג לפני dbt build. לאחר מכן, הקטלוג מתאר את הטבלאות כפי שהיו לפני הבנייה.

מידע נוסף זמין במאמרים בנושא פקודות של משימות ומסלולי הפצה במסמכי התיעוד של dbt.

הורדת ארטיפקטים ממסוף dbt Google Cloud

כדי להוריד באופן ידני ארטיפקטים מהרצה שהסתיימה במסוף dbtGoogle Cloud :

במסוף dbt Google Cloud , פותחים את ההרצה של העבודה שהושלמה.
כדי לראות את קובצי הארטיפקטים שנוצרו, עוברים לכרטיסייה Artifacts (פריטי מידע שנוצרו בתהליך פיתוח).
הורדה של manifest.json,‏ catalog.json,‏ run_results.json ו-sources.json לספרייה מקומית.
בטרמינל המקומי או ב-Cloud Shell, מריצים את gcloud פקודת הייבוא שמתוארת במאמר הגדרת קישוריות dbt ומגדירים את --artifacts-path לספרייה שמכילה את הקבצים שהורדתם.

מידע נוסף זמין במאמר בנושא הצגת נתוני הרצה במסמכי התיעוד של dbt.

הורדת ארטיפקטים באמצעות dbt CLI

ה-CLI של פלטפורמת dbt (לשעבר dbt Cloud CLI) מריץ פקודות dbt בפלטפורמת dbt Cloud מהטרמינל המקומי, ומוריד אוטומטית את הארטיפקטים שנוצרו לספרייה target/ של פרויקט dbt המקומי.

בטרמינל המקומי, עוברים לתיקיית השורש של פרויקט dbt ומריצים את שלוש הפקודות שמפורטות במאמר תנאים מוקדמים ל-dbt.
מריצים את פקודת הייבוא gcloud שמתוארת במאמר הגדרת קישוריות dbt ומגדירים את --artifacts-path כספריית הבסיס של הפרויקט או כספרייה target/.

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

מידע נוסף זמין במאמר Install the dbt platform CLI (התקנת dbt platform CLI) במסמכי העזרה של dbt.

הורדת ארטיפקטים באמצעות dbt Administrative API

אתם יכולים להשתמש ב-dbt Administrative API כדי לאחזר באופן פרוגרמטי ארטיפקטים מכל הפעלה שהסתיימה של עבודת dbt. נקודת הקצה List Run Artifacts מחזירה את נתיבי הקבצים שנוצרו על ידי הרצה, ונקודת הקצה Retrieve Run Artifact מורידה קובץ ארטיפקט ספציפי מכתובת ה-URL הבאה:

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

‫ACCESS_URL תלוי באזור שבו מתארח חשבון dbt Cloud שלכם. אימות בקשות באמצעות אסימון שירות של dbt Cloud. מידע נוסף זמין בדפים הבאים במאמרי העזרה של dbt:

מהטרמינל המקומי, מ-Cloud Shell או מסביבת זרימת עבודה אוטומטית, מורידים את manifest.json, catalog.json, run_results.json ו-sources.json לספרייה מקומית או לקטגוריה של Cloud Storage, ואז מריצים את הפקודה gcloud שמתוארת במאמר הגדרת קישוריות dbt לנתיב הזה.

כברירת מחדל, נקודת הקצה של הארטיפקט מחזירה ארטיפקטים מהשלב האחרון של ההרצה, אלא אם מציינים את פרמטר השאילתה step. כשמגדירים את המשימה כמו שמתואר במאמר הגדרת המשימה ב-dbt Cloud, השלב האחרון הוא dbt parse --write-catalog או dbt docs generate --no-compile, שכותב רק את catalog.json ומשאיר את שלושת הארטיפקטים האחרים ללא שינוי בשלב ברירת המחדל.

אחזור מזהה ההרצה

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

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

בפרמטרים של השאילתה, המסנן status=10 מיועד להרצות שהושלמו עם סטטוס Success. אפשר לשלוח בקשות לנקודת הקצה הזו לפי לוח זמנים כדי לזהות את ההרצה האחרונה שהצליחה, להוריד את הארטיפקטים שלה ולהפעיל את פקודת הייבוא gcloud.

הפעלת הייבוא באמצעות תגובה לפעולה מאתר אחר (webhook)

במקום לבצע סקר של ה-API, אפשר להגדיר webhook של dbt Cloud כדי להפעיל ייבוא אוטומטי של מטא-נתונים בכל פעם שהרצת משימה מסתיימת. ה-webhook שולח מטען ייעודי (payload) לנקודת קצה (endpoint) של HTTP שאתם מספקים:

במסוף dbt Google Cloud , עוברים אל Account settings (הגדרות חשבון) > Webhooks (ווּבְּהוּקים) ולוחצים על Create webhook (יצירת ווּבְּהוּק) או על Create new webhook (יצירת ווּבְּהוּק חדש). מגדירים את המינוי ל-webhook:
- אירועים: בוחרים באפשרות הפעלה הושלמה (job.run.completed), שמופעלת רק אחרי שההפעלה מסתיימת והארטיפקטים שלה זמינים להורדה.
- משימות: בוחרים את משימות הפריסה של dbt Cloud שרוצים לעקוב אחריהן.
- נקודת קצה: מזינים את כתובת ה-HTTPS של שירות שמופעל (לדוגמה, שירות Cloud Run או פונקציית Cloud Run).
שומרים את אסימון הסוד של ה-webhook שמוצג ב-dbt Cloud. השירות שלכם משתמש בסוד הזה כדי לאמת את הכותרת Authorization, שמכילה חתימת HMAC-SHA256 של גוף הבקשה.
בשירות שלכם, קוראים את data.runId מהמטען הייעודי (payload) בפורמט JSON, מורידים את הארטיפקטים של ההרצה באמצעות Administrative API כמו שמתואר קודם, ומריצים את הפקודה gcloud alpha dataplex dbt metadata-jobs create.

כשמטמיעים את ה-handler של ה-webhook, כדאי לקחת בחשבון את הנקודות הבאות:

dbt Cloud ממתין לתגובה למשך 10 שניות לכל היותר. מכיוון שיבוא המטא-נתונים נמשך כמה דקות, צריך להחזיר קודם תגובת HTTP ולהריץ את היבוא ברקע (לדוגמה, כמשימה ב-Cloud Run או באמצעות הדגל --async).
ההגדרה job.run.completed מופעלת גם להרצות שנכשלו, כך שהרצות עם בדיקות שנכשלו עדיין מיובאות. אל תירשמו ל-job.run.errored, כי יכול להיות שהיא תופעל לפני שהארטיפקטים של הריצה יהיו זמינים.

מידע נוסף על מטען ייעודי (payload) של webhook ועל אימות חתימה זמין במאמר Webhooks for your jobs במסמכי התיעוד של dbt.

הגדרת קישוריות ל-dbt

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

קריאת ארטיפקטים של קלט: קריאת ארטיפקטים של JSON שנוצרו על ידי dbt Core ו-MetricFlow ממיקום הקלט (ספרייה מקומית או URI של Cloud Storage שצוינו ב---artifacts-path).
המרת מטא-נתונים: המרת התוכן לפורמט ייבוא המטא-נתונים של Knowledge Catalog (dbt_metadata.jsonl).
העלאה לאזור ההמתנה: מעלים את קובץ הייבוא של המטא-נתונים שעברו טרנספורמציה למיקום של אזור ההמתנה לפלט ב-Cloud Storage שצוין ב---storage-uri.
הפעלת עבודת ייבוא: הפעלת עבודת ייבוא של מטא-נתונים של Knowledge Catalog, שמורה לסוכן של שירות Knowledge Catalog לקרוא את המטא-נתונים שהועברו ל---storage-uri ולהוסיף אותם למשאבים של Knowledge Catalog.

המסוף

נכנסים לדף Knowledge Catalog Connectors במסוף Google Cloud .

כניסה לדף Connectors
לוחצים על הוספת חיבור.
ברשימה Connectors, בוחרים בכרטיס dbt Core and MetricFlow.

הערה: כדי להטמיע מטא-נתונים של dbt Core, צריך להמיר קובצי JSON של ארטיפקטים של dbt בצד הלקוח (manifest.json,‏ catalog.json,‏ run_results.json,‏ sources.json) לפורמט הייבוא של Knowledge Catalog לפני ההטמעה. לכן, אם תבחרו בכרטיס הזה, תועברו להוראות לשימוש ב-CLI או ב-API.
כדי לראות את נכסי ה-dbt המיובאים, עוברים לדף חיפוש או לדף קבוצות של רשומות ביעד.

gcloud

כדי ליצור משימת מטא-נתונים של dbt:

מוודאים שקובצי הארטיפקט של המטא-נתונים של dbt מאוחסנים באופן מקומי או בקטגוריה של Cloud Storage כקלט.
צריך לוודא שהגדרתם קטגוריה של Cloud Storage לביניים עם ההרשאות המתאימות גם למתקשר וגם לסוכן השירות של Knowledge Catalog.
מריצים את הפקודה gcloud מ-Cloud Shell, מטרמינל מקומי או מכלי אוטומטי של תהליך עבודה:
```
gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/
```
דגלים נדרשים
- ‫--storage-uri=STORAGE_URI: (פלט/הכנה) קידומת של URI של Cloud Storage‏ (gs://bucket/path/) שאליה מועלה קובץ ה-JSONL שעבר טרנספורמציה, ושממנה עבודת הייבוא קוראת במהלך הטמעת הנתונים. למבצע הקריאה צריכה להיות הרשאת כתיבה (roles/storage.objectCreator או roles/storage.objectAdmin), ולאגנט השירות של Knowledge Catalog צריכה להיות הרשאת קריאה (roles/storage.objectViewer).
דגלים אופציונליים
- ‫--artifacts-path=ARTIFACTS_PATH: (קלט) הנתיב לארטיפקטים של dbt במקור. הנתיב יכול להיות נתיב של ספרייה מקומית (למשל . או ./target) או קידומת URI של Cloud Storage (למשל gs://my-bucket/dbt-artifacts/). יכול להיות שהנתיב מצביע על ספריית הבסיס של פרויקט dbt (תת-הספרייה target/ מזוהה באופן אוטומטי) או ישירות על הספרייה שמכילה את manifest.json. ברירת המחדל היא .. אם מצוין URI של Cloud Storage, למבצע הקריאה צריכה להיות הרשאת גישה לקריאה (roles/storage.objectViewer או roles/storage.objectAdmin) לקטגוריית הקלט.
- ‫--async: חזרה מיידית, בלי להמתין שהפעולה תסתיים.
- ‫--entry-group=ENTRY_GROUP: המזהה הקצר של קבוצת הרשומות שמקבלת את הרשומות של dbt. היא חייבת כבר להיות קיימת בפרויקט ובמיקום (ברירת המחדל היא dbt-metadata-ingestion).
- ‫--aspects-only: מעדכן רק את המטא-נתונים שנצפו בהרצת ה-dbt הזו, ולא משנה את שאר הנתונים בקבוצת הרשומות. לא נוצרת רשומה, לא נמחקת רשומה, לא משויכת רשומה לתיקייה אחרת, לא נוצר קישור לרשומה, והערך של היבט שרכיב ה-dbt שלו לא היה קיים בהרצה הזו נשאר הערך שניתן לו בהרצה הקודמת. אפשר להשתמש בזה להטמעה שגרתית וחוזרת. איך מפעילים מחדש את ההעברה
- ‫--include-entry-links: שליחת קישורים לרשומות של קשרי גומלין ב-dbt. ההגדרה הזו מופעלת כברירת מחדל. כדי להשבית את ההגדרה, משתמשים במדיניות --no-include-entry-links. הפקודה מחזירה את סוגי הקישורים הבאים:
  - ‫reference: משאב אחד תלוי במשאב אחר, מתאר אותו או משתמש בו. ההסבר כולל תלות של dbt בין צמתים, בדיקה והמשאב שהיא בודקת, מודל סמנטי או מדד והמשאב שהוא מבוסס עליו, צומת ופקודות המאקרו של הפרויקט שהוא קורא להן, וצומת והטבלה ב-BigQuery שהוא יוצר.
  - ‫schema-join: עמודות שאפשר לבצע בהן הצטרפות, שהוגדרו על ידי בדיקת relationships dbt.
- ‫--skip-bigquery-link: דילוג על קישורי reference (צומת dbt‏ ← טבלה ב-BigQuery). כברירת מחדל, נוצר reference קישור לכל צומת dbt מגובה (מודל, seed, תמונת מצב) שמערך הנתונים שלו ב-BigQuery נמצא במיקום הייבוא (--location). מקורות dbt לא מקבלים reference קישור לטבלה שלהם ב-BigQuery. קישורי כניסה יכולים להפנות רק לערכים של @bigquery באותו אזור, ולכן מערכי נתונים באזור אחר נדלגים אוטומטית. כדי לקבוע את האזור של כל מערך נתונים, הפקודה קוראת ל-BigQuery API, ולכן למשתמש שקורא לפקודה צריכה להיות הרשאה bigquery.datasets.get במערכי הנתונים האלה. בלי הרשאה כזו, הפקודה לא יכולה לדלג על מערכי נתונים באזורים אחרים, והקישורים אליהם לא יפעלו. אם הטבלאות ב-BigQuery לא מופיעות ב-Knowledge Catalog, צריך להשתמש ב---skip-bigquery-link.
- ‫--validate-only: יצירה והעלאה של קובץ ה-JSON ואימות של משימת המטא-נתונים, אבל לא מתבצעת הטמעה בפועל.
מוודאים שקיבלתם סטטוס נוצר.

REST

כדי לייבא מטא-נתונים של dbt באמצעות API בארכיטקטורת REST:

יוצרים את הארטיפקטים של dbt וממירים אותם לקובץ ייבוא JSON של Knowledge Catalog (dbt_metadata.jsonl).
מעלים את הקובץ שעבר טרנספורמציה לקטגוריית הביניים של Cloud Storage (gs://BUCKET_NAME/PATH/).

מבצעים קריאה ל-projects.locations.metadataJobs.create:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

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

‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud שבו נמצאת קבוצת הרשומות.
‫LOCATION: האזור של קבוצת הרשומות (לדוגמה, us-central1).
‫JOB_ID: מזהה ייחודי של משימת המטא-נתונים.
‫BUCKET_NAME/PATH: הקידומת של ה-URI של Cloud Storage שבה הועלה dbt_metadata.jsonl.
‫ENTRY_GROUP: המזהה הקצר של קבוצת הרשומות של היעד.

כדי לעקוב אחרי הסטטוס של עבודת הייבוא, משתמשים בשיטה projects.locations.metadataJobs.get:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs/JOB_ID

אחרי שיוצרים את העבודה, Knowledge Catalog מתזמן את ההרצה הראשונה בהתאם להגדרה, או שאפשר להתחיל אותה באופן ידני.

הפעלה מחדש של ההעברה

אחרי הייבוא הראשון, ברוב ההרצות צריך רק לרענן את המטא-נתונים של משאבים שכבר קיימים. משתמשים ב---aspects-only להפעלות האלה. הוא מעדכן רק את מה שהריצת dbt זיהתה, ולא משנה את כל השאר בקבוצת הרשומות. לכן, אפשר להריץ אותו שוב ושוב, בכל לוח זמנים, ומכמה עבודות.

הפעלת הטמעה מלאה (השמטה של --aspects-only) כשקבוצת הרשומות משתנה:

הטמעה ראשונה בקבוצת רשומות.
משאב dbt מתווסף, משנה שם או נמחק.
השם המוצג, התיאור או התוויות של רשומה משתנים.
ההיררכיה של הרשומה משתנה.
התלות ב-dbt משתנה, למשל כשמוסיפים או מסירים קריאה של ref(), source(), test או macro. המשתנה --aspects-only לא יוצר או מעדכן קישורים לרשומות.
משנים את --include-entry-links או את --skip-bigquery-link.

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

מריצים את הפקודה --aspects-only כדי לרענן את הנתונים באופן שוטף:

אחרי כל פקודת dbt שצינור עיבוד הנתונים מריץ: dbt build,‏ dbt test,‏ dbt source freshness או בנייה מחדש מצומצמת של --select.
עמודה נוספת, מוסרת, מוקלדת מחדש או מתוארת מחדש.
היה שינוי ב-SQL של המודל, וההרצה גם כתבה catalog.json.
תוצאות חדשות של בדיקות או רענון של המקור.

--aspects-only יכול להוסיף ולרענן את המטא-נתונים, אבל לא להסיר אותם.

חיפוש והצגה של מטא-נתונים של dbt

המסוף

נכנסים לדף Search בKnowledge Catalog במסוף Google Cloud .

מעבר אל חיפוש
בחלונית Filters, מסננים את נכסי dbt:
- בקטע System (מערכת), בוחרים באפשרות Imported Context (הקשר מיובא).
- בקטע המשנה Managed Connectors (מחברים מנוהלים) שמופיע, בוחרים באפשרות dbt.
בשדה החיפוש, מזינים את השאילתה באמצעות מילת מפתח או חיפוש בשפה טבעית. לדוגמה, כדי לראות את כל נכסי dbt באמצעות חיפוש מילות מפתח, מזינים system=DBT או system=DBT AND type=dbt-model.
בתוצאות החיפוש, לוחצים על נכס dbt כלשהו כדי לפתוח את דף פרטי הרשומה שלו ולראות את הסכימה, את ההסתעפות ואת ההיבטים הטכניים שלו.

gcloud

כדי לחפש רשומות של dbt בפרויקט, משתמשים בפקודה gcloud dataplex entries search:
```
gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID
```
כדי לסנן לפי סוג ספציפי של רשומה ב-dbt (כמו מודלים או מקורות):
```
gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID
```
כדי לראות את כל הפרטים וההיבטים של רשומה ספציפית ב-dbt, משתמשים בפקודה gcloud dataplex entries lookup:
```
gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
- ‫LOCATION: המיקום של קבוצת הרשומות (לדוגמה, us-central1).
- ‫ENTRY_GROUP: המזהה הקצר של קבוצת הערכים של היעד (לדוגמה, dbt-metadata-ingestion).
- ‫ENTRY_ID: המזהה הקצר או שם המשאב היחסי של רשומת ה-dbt.

REST

כדי לחפש רשומות של dbt, מבצעים קריאה לשיטה projects.locations:searchEntries:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

כדי לסנן לפי סוג משאב ספציפי של dbt:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

כדי לאחזר את כל הפרטים וההיבטים של המטא-נתונים של רשומה ספציפית, מפעילים את השיטה projects.locations.entryGroups.entries.get:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

כדי לאחזר הקשר של מודל שפה גדול (LLM) למשאבי dbt ספציפיים, משתמשים ב-API‏ projects.locations:lookupContext:
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
- ‫LOCATION: המיקום של קבוצת הרשומות (לדוגמה, us-central1).
- ‫ENTRY_GROUP: המזהה הקצר של קבוצת הערכים של היעד (לדוגמה, dbt-metadata-ingestion).
- ‫ENTRY_ID: המזהה הקצר או שם המשאב היחסי של רשומת ה-dbt.

כדי להציג את קישורי הכניסה של רשומה ב-dbt, צריך לבצע קריאה ל-method‏ projects.locations:lookupEntryLinks. לדוגמה, כדי לאחזר את טבלת BigQuery שנוצרת על ידי מודל dbt:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

‫ENTRY_NAME הוא השם המלא של המשאב של רשומת dbt. התוצאות מחולקות לדפים, ומוגבלות ל-10 קישורים בכל דף.

מידע נוסף על חיפוש משאבים זמין במאמר חיפוש משאבים ב-Knowledge Catalog. מידע נוסף על ביטויי שאילתות ומסננים זמין במאמר תחביר החיפוש ב-Knowledge Catalog.

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

איך מנהלים את עבודות המחבר

ייבוא מטא-נתונים מ-dbt Core קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מגבלות

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

תפקידים והרשאות של IAM

הפעלת ממשקי ה-API

דרישות מוקדמות ל-dbt

הסבר על תפקידים ב-Cloud Storage

ייבוא מטא-נתונים מהרצות של dbt Cloud

הגדרת משימת dbt Cloud

הורדת ארטיפקטים ממסוף dbt Google Cloud

הורדת ארטיפקטים באמצעות dbt CLI

הורדת ארטיפקטים באמצעות dbt Administrative API

אחזור מזהה ההרצה

הפעלת הייבוא באמצעות תגובה לפעולה מאתר אחר (webhook)

הגדרת קישוריות ל-dbt

המסוף

gcloud

דגלים נדרשים

דגלים אופציונליים

REST

הפעלה מחדש של ההעברה

חיפוש והצגה של מטא-נתונים של dbt

המסוף

gcloud

REST

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

ייבוא מטא-נתונים מ-dbt Core