שליחת בקשות ב-Google Drive Activity API

במדריך הזה נסביר איך לשלוח בקשות ל-Google Drive Activity API באמצעות השיטה activity.query.

מפתח השאילתה

יש 2 דרכים לבקש פעילות: לפי פריט ב-Google Drive או לכל הפריטים בתוך היררכיית תיקיות.

• itemName: הפורמט של המפתח הזה הוא 'items/ITEM_ID'. בדרך כלל זהו קובץ ב-Drive. אם מציינים תיקייה למפתח הזה, יוצגו נתוני הפעילות בתיקייה, למשל מתי היא נוצרה או שמו שלה השתנה.

• ancestorName: הפורמט של המפתח הזה הוא 'items/ITEM_ID', והתגובה כוללת פעילות בכל הפריטים ב-subtree שמתחת לתיקייה הזו.

אם לא מגדירים מפתח, ברירת המחדל היא שימוש ב-ancestorName של 'items/root', ומוצגת פעילות של כל הפריטים ב-Drive.

חלוקה לדפים

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

גודל הדפים מוגבל. אם באפליקציה שלכם יש צורך בהרבה פעילויות, כדאי לשלוח כמה בקשות באמצעות חלוקה לדפים במקום להגדיר ערך גדול ל-pageSize. באופן ספציפי, אם יכול להיות שיש יותר פעילות לאחזור ממה שמופיע בתגובה, התשובה תכלול גם nextPageToken. כדי לאחזר תוצאות נוספות, צריך לחזור על אותה בקשה אבל להוסיף שדה pageToken עם הערך של nextPageToken מהתגובה הקודמת.

קונסולידציה

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

אפשר גם לציין בבקשה את הערך ConsolidationStrategy (שנקרא לפעמים 'צבירה' או 'אוסף'). כך אפשר ליצור קיבוצים אחרים של אובייקטים קשורים מסוג Action, כמו כמה משתמשים שעורכים פריט אחד, או Actor אחד שנעביר כמה קבצים לתיקייה חדשה ב-Drive.

ל-Action בודד יש Actor אחד ו-Target אחד, אבל אחרי הקיבוץ, ל-DriveActivity שנוצר יכולים להיות כמה גורמים ומספר יעדים. עם זאת, גם אחרי הקיבוץ, תמיד יש פעולה 'ראשית' שמייצגת את כל הפעולות במשאב DriveActivity או את הפעולה החשובה ביותר, בהתאם לשיטת האיחוד המבוקשת.

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

מסננים

כדי להגביל את הפעולות שעשויות להוחזר במשאב DriveActivity, אפשר ליצור מחרוזת filter בבקשה activity.query. יש 2 שדות נתמכים: time ו-detail.action_detail_case.

סינון לפי שעה

כדי להגביל פעולות לפי טווח זמן, מציינים את שם השדה time עם אופרטורים מספריים על ערכי תאריכים, שמקושרים באמצעות "AND" אופציונלי. להשתמש באלפיות השנייה מ-1 בינואר 1970 או בפורמט RFC 3339, למשל:

• time > 1452409200000 AND time <= 1492812924310
• time >= "2016-01-10T01:02:03-05:00"

סינון לפי סוג

כדי להגביל לפי סוג פעולה, מחילים את שם השדה detail.action_detail_case עם האופרטור 'has' (:). משתמשים בערך יחיד או ברשימת סוגי הפעולות המותרים שמוקפים בסוגריים מרובעים, מופרדים בפסיקים. כדי למצוא רשימה של סוגי פעולות, אפשר לעיין באובייקטים מסוג ActionDetail.

כדי להחריג סוג פעולה מהתגובה, מוסיפים מקף (-) בתחילת מחרוזת המסנן.

ריכזנו כאן כמה דוגמאות לסוגים של פעולות:

• detail.action_detail_case:RENAME
• detail.action_detail_case:(CREATE RESTORE)
• -detail.action_detail_case:MOVE

שילובים

אפשר לשלב את תנאי הסינון האלה במחרוזת filter אחת, למשל:

• detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000

דוגמאות לבקשות

בקשה לקבלת 10 הפעילויות האחרונות של פריט ב-Drive:

{
  "itemName": "items/ITEM_ID",
  "pageSize": 10
}

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

{
  "ancestorName": "items/ITEM_ID",
  "consolidationStrategy": {
    "legacy": {}
  }
}

לבקש את כל הפעולות של MOVE ושל RENAME בפריט ב-Drive:

{
  "itemName": "items/ITEM_ID",
  "filter": "detail.action_detail_case:(MOVE RENAME)"
}

בקשה לכל הפעילות מ-1 בינואר 2018 (שעון החוף המזרחי):

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-01-01T00:00:00-05:00\""
}

בקשה לכל הפעילות, מלבד פעולות EDIT, במהלך יוני 2017 לפי שעון UTC:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}