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

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

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

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

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

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

היכולת הבוליאנית canStartApproval היא false אם:
- הגדרות האדמין מגבילות את הגישה לתכונה.
- המהדורה של Google Workspace לא עומדת בדרישות.
- הקובץ בבעלות של משתמש מחוץ לדומיין.
- למשתמש אין הרשאה role=writer בקובץ.
חשוב לשתף ידנית את קובץ היעד עם הבודקים. מערכת Drive לא עושה את זה באופן אוטומטי. אם בודק לא קיבל גישה לקובץ, בקשת האישור תאושר, אבל הוא לא יקבל התראות ולא יוכל לראות את הקובץ.

מושגים

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

סטטוס אישור

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

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

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

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

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

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

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

איך מתחילים את תהליך האישור כדי להתחיל בתהליך בקשת האישור, צריך להתקשר למספר start. הערך של status מוגדר ל-IN_PROGRESS.
בהמתנה לאישור. בזמן שהאישור בהמתנה (status מוגדר לערך IN_PROGRESS), גם יוזם הבקשה וגם הבודקים יכולים לקיים איתה אינטראקציה. הם יכולים להוסיף comment, יוזם הבקשה יכול reassign בודקים, ובודק אחד או יותר יכולים approve את הבקשה.
האישור נמצא במצב 'הושלם'. בקשת אישור עוברת למצב 'הושלם' (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: הודעה מותאמת אישית שנשלחת לבוחנים.

גוף התשובה מכיל מופע של משאב 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."
 }'

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

‫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 של האפליקציה.

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

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

מושגים

סטטוס אישור

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

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

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

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

cURL

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

cURL

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

cURL

ביטול האישור

cURL

דחיית האישור

cURL

אישור האישור

cURL

איפה אפשר למצוא אישורים קיימים

קבלת אישור

cURL

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

cURL

נושאים קשורים

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