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

يشرح هذا الدليل المكونات الرئيسية للردّ في Google Drive Activity API، مع توضيح أمثلة لهذه الردود وكيفية تفسيرها.

أغراض

• DriveActivity: هذا هو المورد الأساسي الذي تؤديه طلبات البحث إلى واجهة برمجة تطبيقات Drive Activity. وهي تصف ممثلًا واحدًا أو أكثر ينفذ إجراءً واحدًا أو أكثر يؤثر في هدف واحد أو أكثر.

• 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 بشكل عام.