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

במאמר הזה מוסבר איך מבקשים, מאשרים ומנהלי תהליכי עבודה מנהלים בקשות פיקוח ב-Knowledge Catalog (לשעבר Dataplex Universal Catalog).

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

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

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

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

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

להפעלת ה-API

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

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

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

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

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

ניהול בקשות בתור מגיש הבקשה

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

צפייה בבקשות ששלחתם

כדי לראות את הבקשות שיצרתם או לבדוק בקשה ספציפית:

המסוף

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

    כניסה לדף Governance Workflows

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

REST

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

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

כדי להציג בקשה ספציפית, משתמשים ב-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.
  • ‫USER_EMAIL: כתובת האימייל שלכם.
  • ‫CHANGE_REQUEST_ID: המזהה הייחודי של הבקשה.

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

  • בקשה שנשלחה על ידי משתמש: author היא כתובת האימייל של שולח הבקשה, ו-batchChangeMetadataRequest.description.job לא מוגדר.
  • בקשה שנוצרה על ידי סוכן העשרה: author הוא חשבון השירות של סוכן ההעשרה, ו-batchChangeMetadataRequest.description.job.name מוגדר למזהה של הרצת ההעשרה.

עריכת בקשה

אפשר לעדכן בקשה בהמתנה באמצעות ה-API ל-REST כשהיא במצב NEW או FAILED. עדכון של בקשה במצב FAILED מאפס את המצב שלה ל-NEW, כדי שמאשר יוכל לבדוק אותה שוב. מי יכול לערוך בקשה לשינוי מטא-נתונים? זה תלוי באופן שבו היא נוצרה:

  • בקשות שנשלחו על ידי משתמשים: רק המחבר המקורי יכול לשלוח בקשה לעדכון ההצדקה או המטען הייעודי (payload) של הבקשה ב-PATCH.
  • בקשות שנוצרו על ידי סוכני העשרה: בנוסף ליוצר, בודקים ומאשרים יכולים לשלוח בקשת PATCH בזמן שהבקשה נמצאת במצב NEW או FAILED כדי לאסוף את הנתונים באצווה – לדוגמה, כדי לשנות ערכי מאפיינים שהוצעו או להסיר פריטים מהמערך changes. השדה author נשאר חשבון השירות של סוכן ההעשרה.

כדי לעדכן בקשה לשינוי בהמתנה, משתמשים ב-method‏ changeRequests.patch.

כדי לעדכן רק את ההצדקה לבקשה, שולחים את בקשת ה-PATCH הבאה:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "NEW_JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID?updateMask=justification"

כדי לעדכן את המטען הייעודי (payload) של בקשה לשינוי מטא-נתונים באצווה, שולחים את בקשת ה-PATCH הבאה:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "NEW_JUSTIFICATION",
    "batchChangeMetadataRequest": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "updateEntryRequest": {
            "entry": {
              "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/EXISTING_ENTRY_ID",
              "aspects": {
                "ASPECT_PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID": {
                  "data": {
                    "ASPECT_FIELD_NAME": "UPDATED_ASPECT_FIELD_VALUE"
                  }
                }
              }
            },
            "updateMask": "aspects",
            "aspectKeys": [
              "ASPECT_PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID"
            ]
          }
        }
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID?updateMask=batchChangeMetadataRequest.changes,justification"

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

  • ‫PROJECT_ID: מזהה הפרויקט ב-Google Cloud .
  • ‫LOCATION: האזור שבו נמצאת בקשת השינוי, למשל us-central1.
  • ‫CHANGE_REQUEST_ID: המזהה הייחודי של בקשת השינוי.
  • ‫NEW_JUSTIFICATION: ההצדקה המעודכנת לבקשת השינוי.
  • ‫ENTRY_GROUP_ID: המזהה של קבוצת הרשומות לטירגוט.
  • ‫EXISTING_ENTRY_ID: המזהה של הרשומה במטען הייעודי (payload) של האצווה המעודכנת.
  • ‫ASPECT_PROJECT_ID: מזהה הפרויקט שמכיל את סוג ההיבט.
  • ‫ASPECT_LOCATION: המיקום של סוג ההיבט, למשל us-central1 או global.
  • ‫ASPECT_TYPE_ID: המזהה של סוג ההיבט שמעדכנים.
  • ‫ASPECT_FIELD_NAME: השם של שדה ההיבט שרוצים לעדכן.
  • ‫UPDATED_ASPECT_FIELD_VALUE: הערך המעודכן של שדה ההיבט.

מחיקת בקשה

כמגיש הבקשה, אתם יכולים למחוק רק בקשות במצב NEW. כדי למחוק בקשה:

המסוף

  1. נכנסים לדף Governance Workflows ב-Knowledge Catalog במסוף Google Cloud .

    כניסה לדף Governance Workflows

  2. לוחצים על הכרטיסייה הבקשות שלי.

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

  4. לוחצים על Actions ואז על Delete.

REST

כדי למחוק בקשה, משתמשים ב-method‏ changeRequests.delete.

לדוגמה, שולחים את בקשת ה-DELETE הבאה:

curl -X DELETE \
  -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: המזהה הייחודי של הבקשה שרוצים למחוק.

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

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

התראות

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

שיקולים שקשורים לאישור

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

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

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

המסוף

  1. נכנסים לדף Governance Workflows ב-Knowledge Catalog במסוף Google Cloud .

    כניסה לדף Governance Workflows

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

REST

כדי להציג רשימה של בקשות שממתינות לבדיקה בפרויקט ובמיקום ספציפיים, משתמשים ב-method‏ changeRequests.list.

לדוגמה, שולחים את בקשת ה-GET הבאה:

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

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

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

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

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

{
"changeRequests": [
  {
    "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
    "uid": "b326114f-472b-457d-81e8-98b8ad89c608",
    "justification": "Enrichment Agent Proposal: Batch Metadata Change",
    "author": "enrichment-agent@my-project.iam.gserviceaccount.com",
    "state": "NEW",
    "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "changeType": "BATCH_CHANGE_METADATA",
    "batchChangeMetadataRequest": {
      "name": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
      "description": {
        "job": {
          "name": "projects/123456789012/locations/us-central1/enrichmentTasks/my-enrichment-task/runs/55199e83-1a1e-4837-bb8c-c402c6bee641"
        }
      },
      "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"
            }
          }
        }
      ]
    }
  }
]
}

אישור בקשה

כדי לאשר בקשה:

המסוף

  1. נכנסים לדף Governance Workflows ב-Knowledge Catalog במסוף Google Cloud .

    כניסה לדף Governance Workflows

  2. לוחצים על הכרטיסייה אישורים בהמתנה.

  3. מאתרים את השורה שמכילה את הבקשה שרוצים לאשר.

  4. לוחצים על Actions ואז על Approve.

REST

כדי לאשר בקשה, משתמשים ב-method ‏changeRequests.approve.

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

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID:approve"

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

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

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

  • אם האימות מצליח, ה-method מחזירה את ChangeRequest במצב APPLYING בזמן ש-Knowledge Catalog מפעיל את האצווה ברקע:
  {
    "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
    "uid": "b326114f-472b-457d-81e8-98b8ad89c608",
    "justification": "Proposing new entry using RequestBatchMetadataChange",
    "author": "requester@example.com",
    "state": "APPLYING",
    "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "approver": "approver@example.com",
    "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"
            }
          }
        }
      ]
    }
  }
  ```

* If synchronous payload validation fails (for example, with an
`INVALID_ARGUMENT` or `NOT_FOUND` error), the request immediately
transitions to the `FAILED` state instead of `APPLYING`.
* If permission validation fails with a `PERMISSION_DENIED` error, the request
remains in the `NEW` state.

After background execution finishes, poll `changeRequests.get` to check the
final state (`APPROVED` or `FAILED`). If any changes in the batch fail,
`batchChangeMetadataResponse.failedRequests` lists each failed change by its
position in `changes` (starting at `0`) along with the error details:

```json
{
  "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
  "state": "APPROVED",
  "changeType": "BATCH_CHANGE_METADATA",
  "batchChangeMetadataResponse": {
    "failedRequests": {
      "1": {
        "code": 5,
        "message": "Entry not found."
      }
    }
  }
}

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

דחיית בקשה

כדי לדחות בקשה:

המסוף

  1. נכנסים לדף Governance Workflows ב-Knowledge Catalog במסוף Google Cloud .

    כניסה לדף Governance Workflows

  2. לוחצים על הכרטיסייה אישורים בהמתנה.

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

  4. לוחצים על פעולות ואז על דחייה.

  5. בתיבת הדו-שיח, מזינים את הסיבה לדחייה.

  6. לוחצים על דחייה כדי לאשר.

REST

כדי לדחות בקשה, משתמשים ב-method‏ changeRequests.reject.

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

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "REJECTION_REASON"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID:reject"

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

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

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

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

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

הגדרת התראות באימייל למאשרים

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

כדי להגדיר התראות בקבוצת רשומות, משתמשים ב-method‏ entryGroups.patch:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "changeRequestConfig": {
      "approverEmails": [
        "APPROVER_EMAIL_1",
        "APPROVER_EMAIL_2"
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID?updateMask=changeRequestConfig"

כדי להגדיר התראות במילון המונחים הארגוני, משתמשים ב-method‏ glossaries.patch:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "changeRequestConfig": {
      "approverEmails": [
        "APPROVER_EMAIL_1",
        "APPROVER_EMAIL_2"
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/glossaries/GLOSSARY_ID?updateMask=changeRequestConfig"

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

  • ‫PROJECT_ID: מזהה הפרויקט ב-Google Cloud .
  • ‫LOCATION: המיקום של קבוצת הרשומות, למשל us-central1 או global.
  • ‫ENTRY_GROUP_ID: המזהה של קבוצת הרשומות.
  • ‫GLOSSARY_ID: המזהה של מילון המונחים הארגוני.
  • ‫APPROVER_EMAIL_1, APPROVER_EMAIL_2: כתובות האימייל של המאשרים הפוטנציאליים שיקבלו התראה כשנוצרת בקשת שינוי. אפשר לציין עד 10 כתובות אימייל.

לראות את כל הבקשות ולעקוב אחרי היסטוריית האישורים

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

המסוף

  1. נכנסים לדף Governance Workflows ב-Knowledge Catalog במסוף Google Cloud .

    כניסה לדף Governance Workflows

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

REST

כדי להציג את כל הבקשות הפעילות וההיסטוריות בפרויקט ובמיקום ספציפיים, משתמשים ב-method‏ changeRequests.list.

לדוגמה, שולחים את בקשת ה-GET הבאה:

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

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

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

מחיקת בקשה בכל מצב

בניגוד למגישי הבקשות, שיכולים למחוק רק בקשות במצב NEW, מנהלי תהליכי עבודה יכולים למחוק בקשות בכל מצב באמצעות מסוף Google Cloud או השיטה changeRequests.delete. הוראות מפורטות זמינות במאמר מחיקת בקשה.

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