تقديم طلبات في 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 باستخدام عوامل حسابية رقمية على قيم التاريخ، مع ربطها بعبارة "و" اختيارية. استخدِم المللي ثانية منذ 1 كانون الثاني (يناير) 1970 أو تنسيق RFC 3339، مثل:

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

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

لتقييد البيانات حسب نوع الإجراء، طبِّق اسم الحقل detail.action_detail_case مع المشغِّل has (:). استخدِم إما قيمة فردية أو قائمة بأنواع الإجراءات المسموح بها محصورة بين قوسين ومفصولة بمسافة. للعثور على قائمة بأنواع الإجراءات، راجِع عناصر 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 بالتوقيت العالمي المتفق عليه:

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