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

במסמך הזה מובאת תבנית הפניה ליצירת מחבר בהתאמה אישית לחילוץ מטא-נתונים ממקורות של צד שלישי, כמו MySQL,‏ SQL Server ו-Oracle. אפשר להשתמש במחבר הזה כדי לייבא מטא-נתונים אל Knowledge Catalog (לשעבר Dataplex Universal Catalog) באמצעות צינור קישוריות מנוהל. דוגמה למחבר Python ל-Oracle Database Express Edition ‏ (XE) כלולה כנקודת התחלה. אפשר גם לפתח מחברים באמצעות Java,‏ Scala או R.

איך פועלים מחברים

מחבר מחלץ מטא-נתונים ממקור נתונים של צד שלישי, משנה את המטא-נתונים לפורמט של Knowledge Catalog ImportItem ויוצר קבצים של ייבוא מטא-נתונים שאפשר לייבא באמצעות Knowledge Catalog.

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

פייפליין הקישוריות המנוהל מפעיל את המחבר באמצעות משימה באצווה של Managed Service for Apache Spark. ‫Managed Service for Apache Spark מספק סביבת הפעלה של Spark ללא שרת (serverless). אפשר ליצור מחבר שלא משתמש ב-Spark, אבל מומלץ להשתמש ב-Spark כי הוא יכול לשפר את הביצועים של המחבר.

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

המחבר צריך לעמוד בדרישות הבאות:

• המחבר חייב להיות תמונה ב-Artifact Registry שאפשר להריץ ב-Managed Service for Apache Spark.
• המחבר צריך ליצור קובצי מטא-נתונים בפורמט שאפשר לייבא באמצעות משימת ייבוא מטא-נתונים של קטלוג הידע (שיטת ה-API‏ metadataJobs.create). דרישות מפורטות מופיעות במאמר בנושא קובץ ייבוא מטא נתונים.

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

  ארגומנט בשורת הפקודה	הערך שהצינור מספק
  target_project_id	PROJECT_ID
  target_location_id	REGION
  target_entry_group_id	ENTRY_GROUP_ID
  output_bucket	CLOUD_STORAGE_BUCKET_ID
  output_folder	FOLDER_ID

  המחבר משתמש בארגומנטים האלה כדי ליצור מטא-נתונים בקבוצת רשומות יעד projects/PROJECT_ID/locations/REGION/entryGroups/ENTRY_GROUP_ID, וכדי לכתוב לקטגוריה של Cloud Storage gs://CLOUD_STORAGE_BUCKET_ID/FOLDER_ID. כל הרצה של צינור העברת הנתונים יוצרת תיקייה חדשה FOLDER_ID בדלי CLOUD_STORAGE_BUCKET_ID. המחבר צריך לכתוב קבצים של ייבוא מטא-נתונים לתיקייה הזו.

תבניות הצינורות תומכות במחברים של PySpark. התבניות מניחות שהדרייבר (mainPythonFileUri) הוא קובץ מקומי בתמונת המחבר בשם main.py. אפשר לשנות את תבניות הצינור לתרחישים אחרים, כמו מחבר Spark, כתובת URI שונה של מנהל התקן או אפשרויות אחרות.

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

"""PySpark schemas for the data."""
entry_source_schema = StructType([
      StructField("display_name", StringType()),
      StructField("source", StringType())])

aspect_schema = MapType(StringType(),
                        StructType([
                            StructField("aspect_type", StringType()),
                            StructField("data", StructType([
                            ]))
                          ])
                        )

entry_schema = StructType([
  StructField("name", StringType()),
  StructField("entry_type", StringType()),
  StructField("fully_qualified_name", StringType()),
  StructField("parent_entry", StringType()),
  StructField("entry_source", entry_source_schema),
  StructField("aspects", aspect_schema)
])

import_item_schema = StructType([
  StructField("entry", entry_schema),
  StructField("aspect_keys", ArrayType(StringType())),
  StructField("update_mask", ArrayType(StringType()))
])

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

במדריך הזה אנחנו יוצאים מנקודת הנחה שאתם מכירים את Python ו-PySpark.

כדאי לבדוק את המידע הבא:

• מושגים שקשורים למטא-נתונים ב-Knowledge Catalog
• מסמכים בנושא משימות ייבוא של מטא-נתונים

צריך לבצע את הפעולות הבאות. יוצרים את כל המשאבים באותו Google Cloud מיקום.

1. יוצרים או בוחרים Google Cloud פרויקט.

   תפקידים שנדרשים כדי לבחור או ליצור פרויקט

   • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
   • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

   • יוצרים Google Cloud פרויקט:

     gcloud projects create PROJECT_ID

     מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

   • בוחרים את הפרויקט שיצרתם: Google Cloud

     gcloud config set project PROJECT_ID

     מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

2. מוודאים שהחיוב מופעל בפרויקט Google Cloud .

3. מפעילים את ממשקי ה-API של Dataplex,‏ Dataproc,‏ Workflows ו-Artifact Registry:

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

   כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

   gcloud services enable dataplex.googleapis.com dataproc.googleapis.com workflows.googleapis.com artifactregistry.googleapis.com

4. התקינו את ה-CLI של Google Cloud.

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

6. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

   gcloud init

7. מעניקים תפקידים לחשבון המשתמש. מריצים את הפקודה הבאה לכל אחד מהתפקידים הבאים ב-IAM: roles/resourcemanager.projectCreator, roles/billing.projectManager, roles/serviceusage.admin, roles/iam.serviceAccountCreator, roles/iam.securityAdmin, roles/storage.admin, roles/artifactregistry.writer, roles/dataplex.entryGroupOwner, roles/dataplex.entryOwner, roles/dataplex.aspectTypeOwner

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

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

   • ‫PROJECT_ID: מזהה הפרויקט.
   • ‫USER_IDENTIFIER: המזהה של חשבון המשתמש . לדוגמה, myemail@example.com.
   • ‫ROLE: תפקיד ה-IAM שאתם מקצים לחשבון המשתמש.

8. מגדירים את האימות:

   1. מוודאים שיש לכם את תפקיד ה-IAM ‏Create Service Accounts ‏(roles/iam.serviceAccountCreator) ואת תפקיד ה-IAM ‏Project Admin ‏(roles/resourcemanager.projectIamAdmin). איך מקצים תפקידים

   2. יוצרים את חשבון השירות:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      מחליפים את הערך SERVICE_ACCOUNT_NAME בשם שרוצים לתת לחשבון השירות.

   3. מקצים לחשבון השירות את התפקיד roles/owner ב-IAM:

      gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=roles/owner

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

      • SERVICE_ACCOUNT_NAME: השם של חשבון השירות
      • PROJECT_ID: מזהה הפרויקט שבו יצרתם את חשבון השירות

9. יוצרים קטגוריה של Cloud Storage לאחסון קובצי ייבוא של מטא-נתונים.

10. יוצרים את משאבי המטא-נתונים הבאים באותו פרויקט.

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

    1. יצירת קבוצה של רשומות

    2. יוצרים סוגים מותאמים אישית של היבטים לרשומות שרוצים לייבא. משתמשים במוסכמה למתן שמות SOURCE-ENTITY_TO_IMPORT.

       לדוגמה, במסד נתונים של Oracle, יוצרים סוג היבט בשם oracle-database.

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

    3. יוצרים סוגי רשומות מותאמים אישית למשאבים שרוצים לייבא, ומקצים להם את סוגי ההיבטים הרלוונטיים. משתמשים במוסכמה למתן שמות SOURCE-ENTITY_TO_IMPORT.

       לדוגמה, במסד נתונים של Oracle, יוצרים סוג רשומה בשם oracle-database. מקשרים אותו לסוג ההיבט שנקרא oracle-database.

11. מוודאים שאפשר לגשת למקור של הצד השלישי מ Google Cloud הפרויקט. מידע נוסף מופיע במאמר בנושא הגדרת הרשת של Managed Service for Apache Spark.

יצירת מחבר Python בסיסי

מחבר Python בסיסי לדוגמה יוצר רשומות ברמה העליונה למקור נתונים של Oracle באמצעות מחלקות של ספריית הלקוח Knowledge Catalog. לאחר מכן מציינים את הערכים בשדות של הרשומה.

המחבר יוצר קובץ ייבוא של מטא-נתונים עם הרשומות הבאות:

• רשומה מסוג instance, עם סוג רשומה projects/PROJECT_ID/locations/LOCATION/entryTypes/oracle-instance. הרשומה הזו מייצגת מערכת Oracle Database XE.
• רשומה database שמייצגת מסד נתונים בתוך מערכת Oracle Database XE.

כדי ליצור מחבר Python בסיסי:

1. משכפלים את