تقديم طلبات في 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 مع عامل التشغيل "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"
}