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

במאמר הזה מוסבר איך לשלוח בקשה לשינוי מטא-נתונים באצווה של קבוצת רשומות ב-Knowledge Catalog (לשעבר Dataplex Universal Catalog) באמצעות ה-API בארכיטקטורת REST.

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

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

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

מפעילים את Dataplex API, אם הוא עדיין לא מופעל.

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

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

להפעלת ה-API

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

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

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

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

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

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

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

כשמאשר מאשר בקשה לשינוי באצווה, Knowledge Catalog מחיל באופן אוטומטי את הפעולות לפי סדר התלות הבא:

  1. למחוק קישורים לרשומות.
  2. למחוק רשומות.
  3. ליצור ולעדכן רשומות.
  4. ליצור ולעדכן קישורים לרשומות.

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

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

  • אל תפנו לרשומות שנמחקו באותה קבוצה: אי אפשר ליצור או לעדכן קישור לרשומה שמפנה לרשומה שנמחקת באותה קבוצה, ואי אפשר להגדיר את parentEntry לרשומה שאתם מוחקים באותה קבוצה.
  • הצגת רשומות הורה לפני רשומות צאצא: אם רשומה חדשה מפנה לרשומה אחרת באותה קבוצה בתור parentEntry, צריך להציג את הבקשה שיוצרת את רשומת ההורה לפני הבקשה שיוצרת את רשומת הצאצא. כשיוצרים רשומה או קישור לרשומה, השדה של קבוצת הרשומות parent הוא אופציונלי. אם לא מציינים את parent, קבוצת הרשומות ב-changePayload.name משמשת את Knowledge Catalog. אם כוללים את parent, הוא חייב להתאים ל-changePayload.name.

כדי לשלוח בקשה בסיסית לשינוי מטא-נתונים באצווה, משתמשים ב-method‏ entryGroups.requestBatchMetadataChange:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "changePayload": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "createEntryRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryId": "ENTRY_ID",
            "entry": {
              "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID"
            }
          }
        }
      ]
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"

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

  • ‫PROJECT_ID: המזהה של הפרויקט ב- Google Cloudשמכיל את קבוצת הרשומות.
  • ‫LOCATION: המיקום של קבוצת הרשומות, למשל us-central1.
  • ‫ENTRY_GROUP_ID: המזהה של קבוצת הרשומות לטירגוט.
  • ‫ENTRY_ID: המזהה של הרשומה החדשה שרוצים ליצור.
  • ‫ENTRY_TYPE_ID: המזהה של סוג הרשומה החדשה.
  • ‫JUSTIFICATION: הסיבה שבגללה צריך את הבקשה לשינוי המטא-נתונים, עד 1,024 תווים.

השירות מחזיר תשובה שמכילה את שם המשאב של בקשת השינוי שנוצרה:

{
  "changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}

אימות בקשת השינוי באצווה שנוצרה

כדי לבדוק את בקשת השינוי שנוצרה, משתמשים ב-method‏ changeRequests.get:

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

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

  • ‫PROJECT_ID: מזהה הפרויקט ב-Google Cloud .
  • ‫LOCATION: האזור שבו נמצא המשאב, למשל us-central1.
  • ‫CHANGE_REQUEST_ID: המזהה הייחודי של הבקשה.

השירות מחזיר משאב ChangeRequest שמכיל את המטען הייעודי (payload) של האצווה:

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

{
  "name": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32",
  "uid": "eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32",
  "createTime": "2026-09-14T09:06:40.352156739Z",
  "updateTime": "2026-09-14T09:06:41.714939166Z",
  "justification": "Requesting creation of a new entry",
  "author": "requester@example.com",
  "state": "NEW",
  "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
  "etag": "0YSwO12PxwypRJj6kqM3CTZ9BYk4wk3yasxdiMDE3MU",
  "changeType": "BATCH_CHANGE_METADATA",
  "batchChangeMetadataRequest": {
    "name": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "changes": [
      {
        "createEntryRequest": {
          "parent": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
          "entryId": "new-entry-id",
          "entry": {
            "entryType": "projects/my-project/locations/us-central1/entryTypes/my-entry-type"
          }
        }
      }
    ]
  }
}

אם הרצה של סוכן העשרה יוצרת את בקשת השינוי באצווה באופן אוטומטי, השדה author מכיל את חשבון השירות של סוכן ההעשרה, והשדה batchChangeMetadataRequest.description.job.name מכיל את שם המשאב של הרצת ההעשרה.

יצירת בקשה לשינוי של כמה משאבים בו-זמנית

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

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

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

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "changePayload": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "createEntryRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryId": "FIRST_ENTRY_ID",
            "entry": {
              "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID"
            }
          }
        },
        {
          "createEntryRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryId": "SECOND_ENTRY_ID",
            "entry": {
              "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID",
              "aspects": {
                "PROJECT_ID.LOCATION.ASPECT_TYPE_ID": {
                  "data": {
                    "ASPECT_FIELD_NAME": "ASPECT_FIELD_VALUE"
                  }
                }
              }
            }
          }
        },
        {
          "createEntryLinkRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryLinkId": "ENTRY_LINK_ID",
            "entryLink": {
              "entryLinkType": "projects/PROJECT_ID/locations/LOCATION/entryLinkTypes/ENTRY_LINK_TYPE_ID",
              "entryReferences": [
                {
                  "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/FIRST_ENTRY_ID",
                  "type": "SOURCE"
                },
                {
                  "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/SECOND_ENTRY_ID",
                  "type": "TARGET"
                }
              ]
            }
          }
        }
      ]
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"

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

  • ‫PROJECT_ID: המזהה שלGoogle Cloud הפרויקט שמכיל את קבוצת הרשומות.
  • ‫LOCATION: המיקום של קבוצת הרשומות, למשל us-central1.
  • ‫ENTRY_GROUP_ID: המזהה של קבוצת הרשומות לטירגוט.
  • ‫FIRST_ENTRY_ID: המזהה של הרשומה הראשונה בהתאמה אישית, שמשמש כ-SOURCE בקישור לרשומה.
  • SECOND_ENTRY_ID: המזהה של הרשומה השנייה בהתאמה אישית עם היבט מצורף, שמשמשת בתור TARGET בקישור לרשומה.
  • ‫ENTRY_TYPE_ID: המזהה של סוג הרשומה של הרשומות החדשות.
  • ‫ASPECT_TYPE_ID: המזהה של סוג ההיבט שמצורף לרשומה השנייה.
  • ‫ASPECT_FIELD_NAME: שם השדה בתבנית ההיבט.
  • ‫ASPECT_FIELD_VALUE: הערך של שדה ההיבט.
  • ‫ENTRY_LINK_ID: המזהה של קישור הרשומה שמחבר בין שתי הרשומות.
  • ‫ENTRY_LINK_TYPE_ID: המזהה של סוג הקישור לרשומה, למשל my-entry-link-type.
  • ‫JUSTIFICATION: הסבר למה צריך את השינויים האלה במטא-נתונים.

השירות מחזיר תשובה שמכילה את שם המשאב של בקשת השינוי שנוצרה:

{
  "changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}

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