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

يشرح هذا الدليل المكونات الرئيسية للردود ضمن واجهة برمجة تطبيقات النشاط في Google Drive، ويعرض أمثلة وكيفية تفسيرها.

أغراض

• 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 الإجمالية.