نموذج بيانات واجهة برمجة تطبيقات النشاط في Drive

يوضّح هذا الدليل المكوّنات الرئيسية للاستجابة في 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. في هذا المثال، تم تجميع إجراءَين مشابهَين: نوع إجراء Edit واحد من مستخدمَين مختلفَين.

"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 العام.