نموذج بيانات واجهة برمجة تطبيقات النشاط في 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. على سبيل المثال، يحتوي detail الخاص بإجراء Move على موقعَي المصدر والوجهة، ويحدِّد PermissionChange من يمكنه الآن الوصول إلى مستند وما هي الامتيازات التي يحصل عليها.

أمثلة للردود

راجِع ما يلي للاطّلاع على نماذج الردود.

عدَّل مستخدم ملفًا في Drive

قد يتضمّن مورد DriveActivity إجراءً واحدًا فقط، مثل مستخدمٍ يعدِّل ملفًا واحدًا.

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "driveItem":{ "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.

عدّل مستخدمان الملف نفسه في أوقات مشابهة

عند استخدام ConsolidationStrategy ، يتم تجميع الإجراءات ذات الصلة في DriveActivity مجمع واحد. في هذا المثال، تم تجميع إجراءَين مشابهَين: نوع إجراء Edit واحد من مستخدمَين مختلفَين.

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "timeRange":{
    "startTime":{ "seconds":"1541089823", "nanos":712000000 },
    "endTime":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } },
      "timestamp":{ "seconds":"1541089823", "nanos":712000000 }
    }
  ]
}]

تتضمّن هذه النتائج القيم التالية:

• ‫ACCOUNT_ID_1: رقم تعريف المستخدم الأول. ويمكن استخدامه مع People API للحصول على مزيد من المعلومات.
• ‫ACCOUNT_ID_2: رقم تعريف المستخدم الثاني
• ‫ITEM_ID: رقم تعريف ملف Drive
• ‫TITLE: عنوان ملف Drive

يُرجى العِلم أنّ عنصر Action في هذا الردّ لا يتضمّن Target لأنّه مطابق للعنصر DriveActivity العام.

يوضّح المثال أيضًا كيف يمكن للتطبيقات استخدام المعلومات التلخيصية فقط في DriveActivity، بدون الاطّلاع على الإجراءات الفردية. يشير الردّ إلى أنّ مستخدمَين عدّلا ملفًا معيّنًا على مدار فترة زمنية.

نقل مستخدم ملفَّين إلى دليل جديد.

في هذا المثال، جمعت عملية ConsolidationStrategy إجراءَي Move مرتبطَين لأنّه تم نقل الملفات من المصدر نفسه إلى الوجهة نفسها في الوقت نفسه.

"activities":[{
  "primaryActionDetail":{
    "move":{
      "addedParents":[ { ... } ]
      "removedParents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "driveItem":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "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 الثاني

يُرجى العلم أنّ عنصر Action في هذه الاستجابة لا يتضمّن Actor أو timestamp لأنّهما متطابقان مع DriveActivity العام.