ייצוא מטא-נתונים

‫Knowledge Catalog (לשעבר Dataplex Universal Catalog) מאפשר לייצא מטא-נתונים לשימוש במערכות חיצוניות באמצעות משימת ייצוא מטא-נתונים. לאחר מכן תוכלו לנתח את המטא-נתונים האלה באמצעות כלים כמו BigQuery, לעבד כמויות גדולות באופן פרוגרמטי או לשלב אותם עם אפליקציות בהתאמה אישית.

במסמך הזה אנחנו מניחים שאתם מכירים את המושגים שקשורים למטא-נתונים של Knowledge Catalog, כולל קבוצות של רשומות, סוגי רשומות וסוגי היבטים.

היקף המשרה

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

  • ארגון: ייצוא המטא-נתונים ששייכים לארגון.
  • ‫Projects: ייצוא המטא-נתונים ששייכים לפרויקטים שצוינו.
  • ‫Entry groups: ייצוא המטא-נתונים ששייכים לקבוצות הרשומות שצוינו.

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

VPC Service Controls

ב-Knowledge Catalog משתמשים ב-VPC Service Controls כדי לספק אבטחה נוספת למשימות של ייצוא מטא-נתונים. הפרויקט שאליו שייכת המשימה קובע את ההיקף של VPC Service Controls, באופן הבא:

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

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

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

התפקידים הנדרשים למשתמשי קצה

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

  • יצירת משימות לייצוא מטא-נתונים:
    • Dataplex Entry Group Exporter (roles/dataplex.entryGroupExporter) באופן כללי בארגון, בפרויקטים או בקבוצות הרשומות לייצוא
    • ‫Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) בפרויקט שבו מריצים את משימת המטא-נתונים
  • גישה לתוצאות שיוצאו: צפייה באובייקט אחסון (roles/storage.objectViewer) בפרויקט או בקטגוריה
  • הצגת משימות של מטא-נתונים: Dataplex Metadata Job Viewer (roles/dataplex.metadataJobViewer) בפרויקט

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

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

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

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

  • מטא-נתונים של הייצוא:
    • dataplex.metadataJobs.create
    • dataplex.entryGroups.export
    • dataplex.entryGroups.get
    • resourcemanager.projects.get
    • resourcemanager.projects.list
  • ניגשים לתוצאות שיוצאו: storage.objects.get

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

התפקידים הנדרשים לחשבון השירות של Knowledge Catalog

כדי לוודא שלחשבון השירות של Knowledge Catalog יש את ההרשאות הנדרשות לגישה לקטגוריית Cloud Storage, צריך לבקש מהאדמין לתת לחשבון השירות של Knowledge Catalog את ההרשאות הבאות בקטגוריה: storage.buckets.get,‏ storage.objects.get ו-storage.objects.create.

איך מגדירים משאבים ב- Google Cloud

  1. התקינו את ה-CLI של Google Cloud. אחר כך, מאתחלים את ה-CLI של Google Cloud באמצעות הפקודה הבאה: 

    gcloud init

    אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  2. יוצרים קטגוריה של Cloud Storage כדי לאחסן את התוצאות שיוצאו.

    הקטגוריה צריכה להיות באותו המיקום ובאותו מתחם היקפי של VPC Service Controls כמו עבודת המטא-נתונים.

הפעלת משימת ייצוא של מטא-נתונים

בקטעים הבאים מוסבר איך לייצא מטא-נתונים עם היקפי משימות שונים.

ייצוא מטא-נתונים מהארגון

כדי לייצא את המטא-נתונים מהארגון, משתמשים בשיטה metadataJobs.create ומגדירים את הערך הבוליאני organizationLevel כ-true.

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

  • ‫JOB_PROJECT: הפרויקט Google Cloud שבו מריצים את עבודת המטא-נתונים. מציינים מספר פרויקט או מזהה פרויקט.
  • ‫LOCATION_ID: ה Google Cloud מיקום, למשל us-central1.
  • ‫METADATA_JOB_ID: אופציונלי. מזהה המשימה של המטא-נתונים.

  • ‫BUCKET: קטגוריית Cloud Storage שאליה רוצים לייצא את המטא-נתונים.

    אפשר גם לכלול קידומת בהתאמה אישית אחרי שם הקטגוריה, בפורמט gs://BUCKET/PREFIX/. האורך המקסימלי של הקידומת בהתאמה אישית הוא 128 תווים.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

תוכן בקשת JSON: 

{
  "type": "EXPORT",
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
    },
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

התגובה מזהה פעולה ממושכת. המטא-נתונים שמיוצאים נשמרים בקטגוריה של Cloud Storage.

ייצוא מטא-נתונים מפרויקטים ספציפיים

כדי לייצא מטא-נתונים מפרויקט אחד או יותר, משתמשים בשיטה metadataJobs.create ומספקים רשימה של פרויקטים.

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

  • ‫JOB_PROJECT: הפרויקט ב- Google Cloudשבו מריצים את משימת המטא-נתונים. מזינים את מספר הפרויקט או את מזהה הפרויקט.
  • ‫LOCATION_ID: ה Google Cloud מיקום, למשל us-central1.
  • ‫METADATA_JOB_ID: אופציונלי. מזהה המשימה של המטא-נתונים.

  • ‫BUCKET: קטגוריית Cloud Storage שאליה רוצים לייצא את המטא-נתונים.

    אפשר גם לכלול קידומת בהתאמה אישית אחרי שם הקטגוריה, בפורמט gs://BUCKET/PREFIX/. האורך המקסימלי של הקידומת המותאמת אישית הוא 128 תווים.

  • ‫METADATA_SOURCE_PROJECT: פרויקט שרוצים לייצא את המטא-נתונים שלו. מציינים מספר פרויקט או מזהה פרויקט. הפרויקט צריך להיות באותו ארגון ובאותו היקף של VPC Service Controls כמו עבודת המטא-נתונים.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

תוכן בקשת JSON: 

{
  "type": "EXPORT",
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "projects": [
        "projects/METADATA_SOURCE_PROJECT",
        # Additional projects
      ],
    },
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

התגובה מזהה פעולה ממושכת. המטא-נתונים שמיוצאים נשמרים בקטגוריה של Cloud Storage.

ייצוא מטא-נתונים מקבוצות ספציפיות של רשומות

כדי לייצא מטא-נתונים מקבוצות ספציפיות של רשומות, משתמשים בשיטה metadataJobs.create ומספקים רשימה של קבוצות רשומות.

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

  • ‫JOB_PROJECT: הפרויקט Google Cloud שבו מריצים את עבודת המטא-נתונים. מציינים מספר פרויקט או מזהה פרויקט.
  • ‫LOCATION_ID: המיקום ב- Google Cloud , למשל us-central1.
  • ‫METADATA_JOB_ID: אופציונלי. מזהה משימת המטא-נתונים.

  • ‫BUCKET: קטגוריית Cloud Storage שאליה רוצים לייצא את המטא-נתונים.

    אפשר גם לכלול קידומת בהתאמה אישית אחרי שם הקטגוריה, בפורמט gs://BUCKET/PREFIX/. האורך המקסימלי של הקידומת המותאמת אישית הוא 128 תווים.

  • ‫ENTRY_GROUP: שם המשאב היחסי של קבוצת רשומות שנמצאת בהיקף של המשימה, בפורמט projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. קבוצת הרשומות צריכה להיות באותו פרויקט שבו נמצאת משימת המטא-נתונים.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

תוכן בקשת JSON: 

{
  "type": "EXPORT",
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "entryGroups": [
        "ENTRY_GROUP",
        # Additional entry groups
      ],
    },
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

התגובה מזהה פעולה ממושכת. המטא-נתונים המיוצאים נשמרים בקטגוריה של Cloud Storage.

ייצוא מטא-נתונים מסוגי רשומות או מסוגי היבטים ספציפיים

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

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

  • ‫ENTRY_TYPE: אופציונלי. שם המשאב היחסי של סוג רשומה שנכלל בהיקף של המשימה, בפורמט projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.

  • ‫ASPECT_TYPE: אופציונלי. שם המשאב היחסי של סוג ההיבט שנכלל בהיקף המשימה, בפורמט projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://dataplex.googleapis.com/v1/projects/JOB_PROJECT/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

תוכן בקשת JSON: 

{
  "type": "EXPORT",
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
      "entry_types": [
        "ENTRY_TYPE",
        # Additional entry types
      ],
      "aspect_types": [
        "ASPECT_TYPE",
        # Additional aspect types
      ]
    },
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

התגובה מזהה פעולה ממושכת. המטא-נתונים המיוצאים נשמרים בקטגוריה של Cloud Storage.

קבלת פרטים על משימת מטא-נתונים

כדי לקבל מידע על משימת מטא-נתונים, כמו סטטוס המשימה ומספר הרשומות שיוצאו, משתמשים בשיטה metadataJobs.get.

תוצאות ייצוא המטא-נתונים

משימת ייצוא המטא-נתונים מייצאת תמונת מצב של המטא-נתונים של Knowledge Catalog בזמן שבו נוצרה משימת המטא-נתונים.

ייצוא תוכן הקובץ

התוכן של קובץ הפלט הוא באותו פורמט של קובץ ייבוא המטא-נתונים שמשמש למשימות ייבוא של מטא-נתונים. אתם יכולים להשתמש בקובץ הפלט ישירות כקלט למשימת ייבוא מטא-נתונים.

מיקום קובץ הייצוא

Knowledge Catalog שומר את קובצי תוצאות הייצוא כאובייקטים בקטגוריה של Cloud Storage.

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

gs://BUCKET/PREFIX/year=YYYY/month=MM/day=DD/consumer_project=JOB_PROJECT/job=METADATA_JOB_ID/project=METADATA_SOURCE_PROJECT/entry_group=ENTRY_GROUP/FILE_NUMBER.jsonl

שימו לב לנקודות הבאות:

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

  • לכל קובץ פלט יש שם שכולל מספר קובץ, שהוא מספר שלם שמתחיל ב-1.

    אם משימת ייצוא של מטא-נתונים מכילה מספר גדול של רשומות, המשימה מפצלת את התוצאות לכמה קבצים כדי להגביל את הגודל של כל קובץ פלט. מספר הרשומות המקסימלי בכל קובץ פלט הוא 1,000,000.

קובצי פלט לדוגמה

הנה דוגמאות לקובצי פלט של משימת ייצוא מטא-נתונים שכללה כמה פרויקטים:

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-1/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-2/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-3/entrygroup=entry-group-2/1.jsonl

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

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/2.jsonl

ניתוח המטא-נתונים המיוצאים ב-BigQuery

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

מבצעים את הפעולות הבאות:

  • יצירת טבלה חיצונית לנתונים שחולקו למחיצות ב-Hive. ממלאים את הפרטים הבאים:

    • בחירת קובץ מקטגוריה של Cloud Storage: מציינים את הנתיב לתיקייה ב-Cloud Storage שמכילה את קובצי המטא-נתונים שיוצאו. כדי לכלול את כל הקבצים בדלי, משתמשים בתו הכללי כוכבית (*). לדוגמה, gs://export-bucket/example-folder/*.
    • File format: בוחרים באפשרות JSONL (Newline delimited JSON).
    • מסמנים את תיבת הסימון חלוקה למחיצות של נתוני המקור, ואז בשדה בחירת קידומת URI של מקור, מציינים את קידומת ה-URI של Cloud Storage לטבלה ב-BigQuery כדי להגדיר מחיצות. לדוגמה: gs://export-bucket/example-folder/.
    • ‫מצב היסק של מחיצה: בוחרים באפשרות Automatically infer types.
    • ‫Table type: בוחרים באפשרות External table.

    • סכימה: לוחצים על המתג Edit as text ומזינים את הגדרת הסכימה הבאה לקובצי הייצוא:

      [
  {
    "name": "entry",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "name",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "entryType",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "createTime",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "updateTime",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "aspects",
        "type": "JSON"
      },
      {
        "mode": "NULLABLE",
        "name": "parentEntry",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "fullyQualifiedName",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "entrySource",
        "type": "RECORD",
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "resource",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "system",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "platform",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "displayName",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "description",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "labels",
            "type": "JSON"
          },
          {
            "mode": "REPEATED",
            "name": "ancestors",
            "type": "RECORD",
            "fields": [
              {
                "mode": "NULLABLE",
                "name": "name",
                "type": "STRING"
              },
              {
                "mode": "NULLABLE",
                "name": "type",
                "type": "STRING"
              }
            ]
          },
          {
            "mode": "NULLABLE",
            "name": "createTime",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "updateTime",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "location",
            "type": "STRING"
          }
        ]
      }
    ]
  }
]

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

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

SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000

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