מודל נתונים ב-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 יכולות להתייחס לאחת מהן, כמו תיקיית הבסיס של כונן או מסמך ההורה שמכיל תגובה לקובץ.

• 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 אחד. בדוגמה הזו, 2 פעולות דומות מקובצות: סוג פעולה אחד מסוג 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, בלי לבחון את הפעולות בנפרד. התשובה מציינת ששני משתמשים ערכו קובץ נתון במשך פרק זמן מסוים.

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

בדוגמה הזו, אסטרטגיית האיחוד קיבצה שתי פעולות 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.