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

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

מפתח שאילתה

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

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

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

אם לא הוגדר מפתח, ברירת המחדל היא שימוש ב-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 (אזור זמן EST):

{
  "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"
}