تقديم طلبات في Google Drive Activity API

يشرح هذا الدليل كيفية تقديم الطلبات في Google Drive Activity API باستخدام activity.query.

مفتاح طلب البحث

هناك طريقتان لطلب النشاط: حسب العنصر في Google Drive أو لجميع المستخدمين. أسفل التسلسل الهرمي للمجلدات.

• itemName: تنسيق هذا المفتاح هو "items/ITEM_ID". عادةً ما تكون هذه ملف في Drive. إذا حدَّدت مجلدًا لهذا المفتاح، سيتم عرض نشاط. للمجلد، مثل وقت إنشائه أو إعادة تسميته.

• ancestorName: تنسيق هذا المفتاح هو "items/ITEM_ID"، يتضمن الرد النشاط في جميع العناصر في الشجرة الفرعية أسفل هذه المجلد.

في حال عدم ضبط أي مفتاح، يتم ضبط القيمة التلقائية على استخدام ancestorName من "items/root". أو تعرض النشاط لجميع العناصر في Drive.

تقسيم النتائج على عدّة صفحات

يتيح لك الحقل pageSize طلب عدد تقريبي من الأنشطة. التي يجب إرجاعها في كل إجابة. سيختلف العدد الفعلي للأنشطة التي تم إرجاعها، لذلك، يجب أن يتعامل تطبيقك مع الكميات العشوائية في الردّ.

أحجام الصفحات محدودة. إذا كان تطبيقك يحتاج إلى العديد من الأنشطة، يمكنك إجراء طلبات باستخدام التقسيم على صفحات بدلاً من ضبط قيمة كبيرة في pageSize. على وجه التحديد، إذا كان هناك نشاط للجلب أكثر من ما تم تضمينه في الرد، سيحتوي الرد أيضًا على nextPageToken. لاسترداد نتائج أكثر، كرر الطلب نفسه ولكن أضف حقل pageToken بالقيمة من nextPageToken من الرد السابق.

الدمج

غالبًا ما يتم تجميع عناصر Action وعرضها في عنصر واحد. مرجع DriveActivity تحدث بعض مجموعات Action بشكل تلقائي، مثل نقل عنصر إلى مجلد مشترك مما يؤدي إلى تغيير الإذن.

يمكنك أيضًا تحديد ConsolidationStrategy (يُسمّى أحيانًا التجميع أو التجميع) في الطلب. وهذا يمكّن مجموعات أخرى من عناصر Action ذات الصلة، مثل عدة ممثلين يعدّلون أحد العناصر أو ملف Actor واحد ينقل عدة ملفات إلى مجلد جديد على Drive.

في حين أن الفرد Action لديه واحد Actor وواحد Target، بعد التجميع، يمكن أن يضم DriveActivity الناتج عدة ممثلين واستهدافات متعددة. ومع ذلك، حتى بعد التجميع، يوجد دائمًا خطأ "أساسي" الإجراء الذي إما تمثيلية أو الأكثر أهمية لجميع الإجراءات في DriveActivity مورد، استنادًا إلى استراتيجية الدمج المطلوبة.

نتيجة لذلك، سواء كان الدمج مفعَّلاً أم لا، قد يكون كافيًا لعرض محتوى المستوى الأعلى فقط لمورد DriveActivity (مثل والجهات المعنية الجماعية والأهداف ضمن primaryActionDetail) وتجاهُل الإجراءات التفصيلية في الرد.

الفلاتر

يمكنك حظر الإجراءات التي يمكن عرضها في DriveActivity. عن طريق إنشاء سلسلة filter في طلب activity.query. هناك هناك حقلان متوافقان: time وdetail.action_detail_case.

الفلترة حسب الوقت

لتقييد الإجراءات حسب النطاق الزمني، حدِّد اسم الحقل time مع إدراج عددي عوامل التشغيل على قيم التاريخ، ويربطها بحرف "AND" اختياري. استخدم المللي ثانية منذ 1 يناير 1970 أو تنسيق RFC 3339، مثل:

• time > 1452409200000 AND time <= 1492812924310
• time >= "2016-01-10T01:02:03-05:00"

تصفية حسب النوع

للتقييد حسب نوع الإجراء، طبِّق اسم الحقل detail.action_detail_case مع "ها" (:). استخدِم قيمة فردية أو قائمة إجراءات مسموح بها. بين قوسين ومفصولة بمسافة. للعثور على قائمة الإجراءات أنواع العناصر، راجِع كائنات ActionDetail.

لاستبعاد نوع إجراء من الردّ، اتّبِع الخطوات التالية: إضافة واصلة (-) في بداية سلسلة الفلتر

في ما يلي بعض الأمثلة على أنواع الإجراءات:

• detail.action_detail_case:RENAME
• detail.action_detail_case:(CREATE RESTORE)
• -detail.action_detail_case:MOVE

النُسخ

يمكن دمج شروط الفلترة هذه ضمن سلسلة filter واحدة، مثل:

• detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000

أمثلة على الطلبات

اطلب أحدث 10 أنشطة لعنصر Drive:

{
  "itemName": "items/ITEM_ID",
  "pageSize": 10
}

يمكنك طلب أنشطة مدمجة لكل عنصر في Drive ضمن مجلد أصل:

{
  "ancestorName": "items/ITEM_ID",
  "consolidationStrategy": {
    "legacy": {}
  }
}

طلب كل إجراءات MOVE وRENAME على عنصر في Drive:

{
  "itemName": "items/ITEM_ID",
  "filter": "detail.action_detail_case:(MOVE RENAME)"
}

اطلب كل الأنشطة منذ 1 كانون الثاني (يناير) 2018 بالتوقيت الرسمي الشرقي:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-01-01T00:00:00-05:00\""
}

يمكنك طلب كل الأنشطة، باستثناء EDIT إجراء، خلال حزيران (يونيو) 2017 بالتوقيت العالمي المنسق (UTC):

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}