מודל נתונים ב-Drive Activity API

במדריך הזה מוסבר מהם הרכיבים העיקריים של תגובה ב-Google Drive Activity API, ומופיעות דוגמאות והסברים על האופן שבו צריך לפרש אותן.

אובייקטים

• DriveActivity – זהו המשאב הראשי שמוחזר על ידי שאילתות ל-Drive Activity API. הוא מתאר גורם אחד או יותר שמבצע פעולה אחת או יותר שמשפיעה על יעד אחד או יותר.

• Timestamp ו-TimeRange – השדות האלה מתארים, בהתאמה, נקודה בודדת בזמן שבה התרחשה הפעילות, או את תחילת הפעילות ואת סופה במהלך פרק זמן.

• Actor – בדרך כלל, Actor הוא משתמש קצה. עם זאת, לפעמים אירוע מערכת יכול להפעיל Action כשאדמין פועל בתור משתמש או בתור עצמו, או כשהפעולה מתבצעת על ידי אדם לא מזוהה. ההודעה Actor מכילה את כל המקרים האלה.

• Target – Target הוא האובייקט של הפעילות, כמו קובץ, תיקייה, אחסון שיתופי או תגובה לקובץ. חשוב לזכור שסוגי פעולות רבים תומכים ביותר מסוג אחד של יעד. לדוגמה, הקיצור Edit רלוונטי בדרך כלל לקבצים ב-Drive, אבל פעולות אחרות כמו Rename ו-Create יכולות לחול גם על תיקיות ב-Drive ועל אחסונים משותפים. מטרות שלא הן פריטים ב-Drive עדיין יכולות להפנות לפריט ב-Drive, כמו תיקיית השורש של אחסון או המסמך ההורה שמכיל תגובה לקובץ.

• Action – לכל משאב DriveActivity יש פעולה אחת או יותר שקשורה אליו. ה-Action הוא עצמאי, כמו אירוע, בכך שהוא כולל לא רק את הסוג המפורט ואת המידע על הפעולה, אלא גם Actor,‏ Target ו-Timestamp או TimeRange. כדי למנוע חזרות מיותרות, Action לא מאכלס שדות Target,‏ Actor או זמן משלו כשהם זהים לשדות הDriveActivity הכוללים.

• ActionDetail – זהו הסוג הספציפי והמידע המפורט על Action. לדוגמה, פרטי הפעולה Move כוללים מיקום מקור ומיקום יעד, ופרטים של PermissionChange מציינים מי יכול לגשת עכשיו למסמך ואילו הרשאות יש לו.

תגובות לדוגמה

משתמש ערך קובץ ב-Drive:

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

"activities":[{
  "primary_action_detail":{ "edit":{} },
  "actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "drive_item":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } } ],
  "timestamp":{ "seconds":"1536794657", "nanos":791000000 },
  "actions":[ { "detail":{ "edit":{} } } ]
}]

הפלט הזה כולל את הערכים הבאים:

• ACCOUNT_ID: המזהה של המשתמש. אפשר להשתמש בו עם People API כדי לקבל מידע נוסף.
• ITEM_ID: המזהה של הפריט ב-Drive.
• TITLE: השם של הפריט ב-Drive.

חשוב לדעת שהערך של Action בתגובה הזו לא כולל את הערכים של Actor,‏ Target ו-TimeStamp כי הם זהים לערך הכולל של DriveActivity.

שני משתמשים ערכו את אותו קובץ בזמנים דומים:

כשהאיחוד מופעל, פעולות קשורות מקובצות ל-DriveActivity אחד. בדוגמה הזו, שתי פעולות דומות מקובצות: סוג פעולה אחד מסוג Edit מ-2 משתמשים שונים.

"activities":[{
  "primary_action_detail":{ "edit":{} },
  "actors":[
    { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
    { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "drive_item":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "time_range":{
    "start_time":{ "seconds":"1541089823", "nanos":712000000 },
    "end_time":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_2" } } },
      "timestamp":{ "seconds":"1541089823", "nanos":712000000 }
    }
  ]
}]

הפלט הזה כולל את הערכים הבאים:

• ACCOUNT_ID_1: המזהה של המשתמש הראשון. אפשר להשתמש בו עם People API כדי לקבל מידע נוסף.
• ACCOUNT_ID_2: המזהה של המשתמש השני.
• ITEM_ID: המזהה של הפריט ב-Drive.
• TITLE: השם של הפריט ב-Drive.

חשוב לזכור שהפעולות בתגובה הזו לא כוללות את Target כי היא זהה ל-DriveActivity הכולל.

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

משתמש העביר 2 קבצים לספרייה חדשה:

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

"activities":[{
  "primary_action_detail":{
    "move":{
      "added_parents":[ { ... } ]
      "removed_parents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
      "target":{ "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
      "target":{ "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
    }
  ]
}]

הפלט הזה כולל את הערכים הבאים:

• ACCOUNT_ID: המזהה של המשתמש. אפשר להשתמש בו עם People API כדי לקבל מידע נוסף.
• ITEM_ID_1: המזהה של הפריט הראשון ב-Drive.
• ITEM_ID_2: המזהה של הפריט השני ב-Drive.
• TITLE_1: השם של הפריט הראשון ב-Drive.
• TITLE_2: השם של הפריט השני ב-Drive.

לתשומת ליבכם: הפעולות בתגובה הזו לא כוללות את Actor או TimeStamp כי הן זהות ל-DriveActivity הכולל.