ניהול אישורים

במאמר הזה מוסבר איך לנהל אישורים ב-Google Drive API.

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

אתם יכולים ליצור ולנהל אישורי תוכן ב-Drive. ‫Google Drive API מספק את משאב approvals לעבודה עם אישורי קבצים. השיטות של מקור המידע approvals פועלות על פריטים ב-Drive, ב-Google Docs ובעורכים אחרים של Google Workspace. הבודקים יכולים לאשר או לדחות את המסמכים או להשאיר עליהם משוב ישירות.

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

  1. הקובץ צריך להכיל את היכולת canStartApproval . כדי לבדוק את היכולות של קובץ, קוראים ל-method‏ get במשאב files עם פרמטר הנתיב fileId, ומשתמשים בשדה היכולת canStartApproval בפרמטר fields. מידע נוסף זמין במאמר בנושא הסבר על היכולות של קבצים.

    היכולת הבוליאנית canStartApproval היא false אם:

    • הגדרות האדמין מגבילות את הגישה לתכונה.
    • המהדורה שלכם ב-Google Workspace לא עומדת בדרישות.
    • הקובץ בבעלות של משתמש מחוץ לדומיין.
    • למשתמש אין הרשאה role=writer בקובץ.

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

מושגים

המושגים הבאים הם הבסיס לאישורים.

סטטוס אישור

כשמבקשים אישור למסמך, תהליך האישור מוודא שלכל בודק יש אפשרות להוסיף הערות למסמך.

המשאב approvals כולל אובייקט Status שמפרט את סטטוס האישור כשמבקשים את המשאב. הוא כולל גם את האובייקט ReviewerResponse שמפרט את התשובות לאישור שניתן על ידי בודקים ספציפיים. התשובה של כל בודק מיוצגת על ידי האובייקט Response.

ההתנהגות של האישור כשתוכן הקובץ משתנה בזמן שהאישור Status הוא IN_PROGRESS נקבעת על ידי השדה fileContentChangeBehavior של המשאב approvals. אפשר להחיל את ההתנהגויות הבאות:

  • ‫RESET_APPROVAL: תהליך האישור מוודא שכל בודק מאשר את אותה גרסה של התוכן. אם הקובץ נערך אחרי שהבודק אישר את הבקשה ולפני שהבקשה הושלמה, האישורים של הבודק מאופסים (התשובה משתנה חזרה ל-NO_RESPONSE), והבודקים צריכים לאשר את הגרסה החדשה. כשהאישור הוא בסטטוס APPROVED, הקובץ נעול כדי למנוע שינויים נוספים. אם תערכו תוכן נוסף אחרי האישור הסופי, יופיע באנר במסמך שמציין שהגרסה הנוכחית שונה מהגרסה שאושרה. זו התנהגות ברירת המחדל.

  • ‫NO_APPROVAL_ACTION: עריכות בתוכן הקובץ לא מאפסות את ההחלטות של הבודקים בזמן שהאישור בהמתנה. בנוסף, הקובץ לא ננעל אחרי האישור הסופי. הבודקים יכולים גם לאפס את ההחלטה שלהם APPROVED לסטטוס 'בהמתנה' (התשובה חוזרת לסטטוס NO_RESPONSE) בכל שלב לפני השלמת האישור.

אחרי שהאישור יושלם, ההתנהגות הזו לא תהיה רלוונטית יותר.

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

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

אחרי שהאישור הושלם (הסטטוס הוא APPROVED, CANCELLED או DECLINED), הוא נשאר במצב 'הושלם' ואי אפשר לבצע בו פעולות על ידי יוזם הבקשה או הבודקים. אתם יכולים להוסיף הערות לאישור שהושלם, כל עוד אין אישור קיים בקובץ עם סטטוס IN_PROGRESS.

מחזור החיים של אישור

מחזור החיים של אישור.
איור 1. מחזור החיים של אישור.

תהליך האישור עובר כמה שלבים במהלך מחזור החיים שלו. איור 1 מציג את השלבים הכלליים במחזור החיים של אישור:

  1. איך מתחילים את תהליך האישור כדי להתחיל בתהליך בקשת האישור, צריך להתקשר למספר start הערך של status מוגדר ל-IN_PROGRESS.

  2. בהמתנה לאישור. בזמן שהאישור בהמתנה (status מוגדר ל-IN_PROGRESS), גם יוזם הבקשה וגם הבודקים יכולים לקיים איתה אינטראקציה. הם יכולים להוסיף comment, יוזם הבקשה יכול reassign בודקים, ובודק אחד או יותר יכולים approve את הבקשה.

  3. האישור נמצא במצב 'הושלם'. תהליך האישור עובר למצב 'הושלם' (status מוגדר כ-APPROVED, CANCELLED או DECLINED) כשכל הבודקים מאשרים את הבקשה, כשיוזם הבקשה בוחר cancel את הבקשה או כשבודק כלשהו בוחר decline את הבקשה.

שימוש בפרמטר fields

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

התחלה של תהליך אישור וניהול שלו

אפשר להשתמש במשאב approvals כדי להתחיל ולנהל אישורים באמצעות Drive API. ה-methods האלה פועלות עם כל היקפי ההרשאות הקיימים של Drive API OAuth 2.0 שמאפשרים כתיבה של מטא-נתונים של קבצים. מידע נוסף זמין במאמר בחירת היקפי הרשאות של Google Drive API.

התחלת תהליך אישור

כדי להתחיל תהליך אישור חדש בקובץ, משתמשים בשיטה start במשאב approvals וכוללים את פרמטר הנתיב fileId.

גוף הבקשה מורכב משדה reviewerEmails חובה שהוא מערך של מחרוזות שמכילות את כתובות האימייל של הבודקים שהוקצו לבדיקת הקובץ. כל כתובת אימייל של בודק צריכה להיות משויכת לחשבון Google, אחרת הבקשה תיכשל. בנוסף, יש ארבעה שדות אופציונליים:

  • ‫dueTime: מועד סיום ההמתנה לאישור, בפורמט RFC 3339.
  • ‫lockFile: ערך בוליאני שמציין אם לנעול את הקובץ כשמתחילים את תהליך האישור. הפעולה הזו מונעת מהמשתמשים לשנות את הקובץ במהלך תהליך האישור. כל משתמש עם הרשאה role=writer יכול להסיר את הנעילה הזו.
  • ‫message: הודעה מותאמת אישית שנשלחת לבוחנים.
  • ‫fileContentChangeBehavior: אופן ההתנהגות של האישור כשתוכן הקובץ משתנה. הערכים הנתמכים הם:
    • ‫RESET_APPROVAL: (ברירת מחדל) מאפס את התגובה של הבודק מ-APPROVED ל-NO_RESPONSE כשתוכן משתנה בזמן שהאישור מתבצע. הקובץ ננעל כשתהליך האישור מסתיים והסטטוס שלו הוא APPROVED.
    • ‫NO_APPROVAL_ACTION: לא מאפס את התגובות של הבודקים כשתוכן משתנה, ולא נועל את הקובץ כשהאישור מסתיים.

גוף התשובה מכיל מופע של משאב approvals, והוא כולל את השדה initiator שמייצג את המשתמש שביקש את האישור. האישור Status מוגדר כ-IN_PROGRESS.

אם קיים אישור עם Status של IN_PROGRESS, השיטה start תיכשל. אפשר להתחיל תהליך אישור רק אם אין אישור קיים לקובץ או אם האישור הקיים נמצא במצב 'הושלם' (הסטטוס הוא APPROVED, CANCELLED או DECLINED).

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals:start' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "reviewerEmails": [
     "reviewer1@example.com",
     "reviewer2@example.com"
    ],
    "dueTime": "2026-04-01T15:01:23Z",
    "lockFile": true,
    "message": "Please review this file for approval.",
    "fileContentChangeBehavior": "RESET_APPROVAL"
 }'

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

  • ‫FILE_ID: המזהה של הקובץ שהבקשה לאישור שלו נשלחה.
  • ‫ACCESS_TOKEN: אסימון OAuth 2.0 של האפליקציה.

הוספת תגובה לאישור

כדי להוסיף תגובה לאישור, משתמשים בשיטה comment במשאב approvals וכוללים את פרמטרי הנתיב fileId ו-approvalId.

גוף הבקשה כולל את שדה החובה message, שהוא מחרוזת שמכילה את התגובה שרוצים להוסיף לאישור.

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

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:comment' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The required comment on the approval."
 }'

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

  • ‫FILE_ID: המזהה של הקובץ שהבקשה לאישור שלו נשלחה.
  • ‫APPROVAL_ID: מזהה האישור.
  • ‫ACCESS_TOKEN: הטוקן של האפליקציה מסוג OAuth 2.0.

הקצאה מחדש של בודקים בתהליך האישור

כדי להקצות מחדש בודקים לאישור, משתמשים ב-method ‏reassign במשאב approvals וכוללים את פרמטרי הנתיב fileId ו-approvalId.

השיטה reassign מאפשרת ליוזם האישור (או למשתמש עם ההרשאה role=writer) להוסיף בודקים או להחליף אותם באובייקט ReviewerResponse של המשאב approvals. משתמש עם הרשאת role=reader יכול להקצות מחדש רק אישור שהוקצה לו. כך המשתמש יכול להקצות מחדש בקשה למישהו אחר שיש לו יכולת טובה יותר לבדוק אותה.

אפשר להקצות מחדש בודקים רק כשהסטטוס של Status הוא IN_PROGRESS והשדה response של הבודק שמוקצה מחדש מוגדר כ-NO_RESPONSE.

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

גוף הבקשה כולל את השדות האופציונליים addReviewers ו-replaceReviewers. לכל שדה יש אובייקט חוזר ל-AddReviewer ול-ReplaceReviewer, שכל אחד מהם מכיל בודק יחיד להוספה או זוג בודקים להחלפה. אפשר גם להוסיף את השדה האופציונלי message עם התגובה שרוצים לשלוח לבודקים החדשים.

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

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:reassign' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "addReviewers": [
    {
        "addedReviewerEmail": "new_reviewer@example.com"
    }
    ],
    "replaceReviewers": [
    {
        "addedReviewerEmail": "replacement_reviewer@example.com",
        "removedReviewerEmail": "old_reviewer@example.com"
    }
    ],
    "message": "Reassigning reviewers for this approval request."
 }'

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

  • ‫FILE_ID: המזהה של הקובץ שהבקשה לאישור שלו נשלחה.
  • ‫APPROVAL_ID: מזהה האישור.
  • ‫ACCESS_TOKEN: הטוקן של OAuth 2.0 של האפליקציה.

ביטול האישור

כדי לבטל אישור, משתמשים ב-method ‏cancel במשאב approvals וכוללים את פרמטרי הנתיב fileId ו-approvalId.

אפשר לקרוא למתודה cancel רק על ידי יוזם האישור (או משתמש עם ההרשאה role=writer) בזמן שהאישור Status הוא IN_PROGRESS.

גוף הבקשה כולל שדה אופציונלי message שהוא מחרוזת שמכילה את ההודעה שמצורפת לביטול האישור.

גוף התשובה מכיל מופע של משאב approvals. ההודעה נשלחת כהתראה, והיא גם נכללת ביומן הפעילות של האישור. האישור Status מוגדר כCANCELLED והוא במצב הושלם.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:cancel' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for cancelling this approval request."
 }'

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

  • ‫FILE_ID: המזהה של הקובץ שהבקשה לאישור שלו נשלחה.
  • ‫APPROVAL_ID: מזהה האישור.
  • ‫ACCESS_TOKEN: הטוקן של האפליקציה מסוג OAuth 2.0.

דחיית האישור

כדי לדחות אישור, משתמשים בשיטה decline במשאב approvals וכוללים את פרמטרי הנתיב fileId ו-approvalId.

אפשר להפעיל את השיטה decline רק אם סטטוס האישור Status הוא IN_PROGRESS.

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

גוף התשובה מכיל מופע של משאב approvals. ההודעה נשלחת כהתראה, והיא גם נכללת ביומן הפעילות של האישור. השדה response של האובייקט ReviewerResponse של המשתמש ששולח את הבקשה מוגדר לערך DECLINED. בנוסף, האישור Status מוגדר לערך DECLINED והוא במצב 'הושלם'.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:decline' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for declining this approval request."
 }'

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

  • ‫FILE_ID: המזהה של הקובץ שהבקשה לאישור שלו נשלחה.
  • ‫APPROVAL_ID: מזהה האישור.
  • ‫ACCESS_TOKEN: הטוקן של האפליקציה מסוג OAuth 2.0.

אישור האישור

כדי לאשר בקשת אישור, משתמשים ב-method ‏approve במשאב approvals וכוללים את פרמטרי הנתיב fileId ו-approvalId.

אפשר להפעיל את השיטה approve רק אם סטטוס האישור Status הוא IN_PROGRESS.

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

גוף התשובה מכיל מופע של משאב approvals. ההודעה נשלחת כהתראה, והיא גם נכללת ביומן הפעילות של האישור. השדה response של האובייקט ReviewerResponse של המשתמש ששולח את הבקשה מוגדר לערך APPROVED. בנוסף, אם זו התשובה האחרונה שנדרשת מהבודק, מצב האישור Status משתנה לAPPROVED והבקשה עוברת למצב 'הושלם'.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:approve' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for approving this approval request."
 }'

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

  • ‫FILE_ID: המזהה של הקובץ שהבקשה לאישור שלו נשלחה.
  • ‫APPROVAL_ID: מזהה האישור.
  • ‫ACCESS_TOKEN: הטוקן של האפליקציה מסוג OAuth 2.0.

חיפוש אישורים קיימים

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

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

קבלת אישור

כדי לקבל אישור על קובץ, משתמשים בשיטה get במשאב approvals עם פרמטרי הנתיב fileId ו-approvalId. אם אתם לא יודעים מה מזהה האישור, אתם יכולים לרשום את האישורים באמצעות השיטה list.

גוף התשובה מכיל מופע של משאב approvals.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

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

  • ‫FILE_ID: המזהה של הקובץ שהבקשה לאישור שלו נשלחה.
  • ‫APPROVAL_ID: מזהה האישור.
  • ‫ACCESS_TOKEN: אסימון OAuth 2.0 של האפליקציה.

הצגת רשימת אישורים

כדי לראות את רשימת האישורים בקובץ, מפעילים את השיטה list במשאב approvals וכוללים את פרמטר הנתיב fileId.

גוף התשובה כולל רשימה של אישורים בקובץ. השדה items כולל מידע על כל אישור בצורה של משאב approvals.

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

  • ‫pageSize: המספר המקסימלי של אישורים שיוחזרו בכל דף. אם לא מגדירים את pageSize, השרת מחזיר עד 100 אישורים.

  • ‫pageToken: טוקן של דף שהתקבל מקריאה קודמת של רשימה. הטוקן הזה משמש לאחזור הדף הבא. הערך שלו צריך להיות הערך של nextPageToken מהתגובה הקודמת.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

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

  • ‫FILE_ID: המזהה של הקובץ שהבקשה לאישור שלו נשלחה.
  • ‫ACCESS_TOKEN: אסימון OAuth 2.0 של האפליקציה.