يعرض تقرير استخدام الكيانات أنشطة خدمات Google Workspace المرتبطة بالكيانات التي يستخدمها مستخدمو حسابك. يمكن تخصيص هذه التقارير وفلترتها للحصول على معلومات استخدام معيّنة. وتتوفّر البيانات لآخر 30 يومًا.
لا يجوز استخدام تقرير استخدام الكيانات إلا لأغراض قانونية بما يتوافق مع "اتفاقية العملاء". تنطبق هذه التقارير أيضًا على Google Workspace وEducation.
استرداد كل أنشطة استخدام الكيانات
إن نوع الكيان الوحيد الذي تدعمه واجهة برمجة التطبيقات هذه في الوقت الحالي هو منتديات +Google. لاسترداد تقرير
بجميع الأنشطة ذات الصلة بكيانات التطبيق في حسابك، استخدِم طلب HTTP GET
التالي وأدرِج رمز التفويض المميز الموضّح في
مستندات التفويض. لتسهيل القراءة، يتم تنسيق المثال التالي بإرجاع الأسطر:
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date ?parameters=applicationParameters &filters=parameterFilters &maxResults=maxResults
تمثّل القيمة date تاريخ حدوث الاستخدام ويكون الطابع الزمني بتنسيق ISO 8601، yyyy-mm-dd. ننصحك باستخدام المنطقة الزمنية لحسابك في هذا الشأن. لمزيد من المعلومات عن معلَمات سلسلة طلب البحث وخصائص الاستجابة، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات. للحصول على معلومات عن مَعلمات تقرير استخدام الكيانات، اطّلِع على مرجع مَعلمات استخدام الكيانات.
applicationParameters هي قائمة مفصولة بفواصل تضمّ المَعلمات التي تريد استردادها.
ويتم تنسيق كل مَعلمة على النحو التالي: application:parameter_name
، على سبيل المثال،
gplus:community_name
. ويتم توثيق المَعلمات المتاحة في مرجع مَعلمات استخدام الكيانات. إذا لم يتم تحديد أي معلَمات، سيتم عرض كل المَعلمات.
"parameterFilters" هي قائمة من الفلاتر المفصولة بفواصل ليتم تطبيقها على النتائج. يتم تنسيق كل فلتر على النحو التالي:
application:parameter_name[relational_operator]parameter_value
. على سبيل المثال، يؤدّي الفلتر gplus:num_total_members>100
إلى فلترة النتائج لكي لا تتضمّن سوى النتائج التي تكون فيها قيمة المعلَمة gplus:num_total_members
أكبر من 100.
maxResults هو الحد الأقصى لعدد النتائج المراد عرضها في عملية جلب واحدة. إذا كان إجمالي عدد النتائج أكبر من هذا الحد، سيتم اقتطاع الاستجابة وسيتم تضمين nextPageToken
(يمكنك الاطّلاع على مثال استجابة JSON أدناه).
أمثلة
يحصل المثال التالي على تقرير يحتوي على جميع المَعلمات لجميع كيانات gplus_communities
.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11
يحصل المثال التالي على تقرير يحتوي على المَعلمة community_name
لجميع كيانات gplus_communities
.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11?parameters=gplus:community_name
يتضمّن المثال التالي تقريرًا عن community_name
وnum_total_members
لكل كيان gplus_communities
، وتتم فلترته حسب المنتديات التي تضمّ أكثر من 100 عضو. للاطّلاع على مثال لاستجابة واجهة برمجة التطبيقات، راجِع مثال استجابة JSON.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11 ?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members>100
استرداد تقرير لكيان محدّد
لاسترداد تقرير لكيان محدّد، استخدِم طلب HTTP GET
التالي وضمِّن الرمز المميز للتفويض الموضّح في مستندات التفويض. لتسهيل القراءة، يتم تنسيق المثال التالي بإرجاع الأسطر.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date ?parameters=applicationParameters &filters=parameterFilters &maxResults=maxResults
entityKey هو معرّف كيان خاص بالتطبيق الذي يوجد فيه الكيان. يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات لمزيد من التفاصيل حول كيفية الحصول على entityKey الخاصة بالكيان المحدّد الذي يهمّك. تم توثيق المَعلمات الأخرى أعلاه ضمن استرداد جميع أنشطة استخدام الكيانات.
للمزيد من المعلومات عن معلَمات سلسلة طلب البحث وخصائص الاستجابة، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات. للحصول على معلومات حول معلَمات تقرير استخدام الكيانات، يمكنك الاطّلاع على مرجع معلَمات استخدام الكيانات.
أمثلة
يحصل المثال التالي على تقرير الكيانات الخاص بكيان gplus_community
الذي يحمل
entityKey "1234".
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
مثال على استجابة JSON في تقرير الاستخدام
تعرض الاستجابة الناجحة رمز حالة HTTP 200. وإلى جانب رمز الحالة، يتم عرض تقرير للاستجابة. تم حذف بعض المعلَمات في الرد لتسهيل قراءتها.
مثال على استجابة JSON لتقرير الكيانات
{ "kind": "reports#usageReports", "nextPageToken": "NjQ1OTgwODk0MzkxNDAwNjQ0OA", "usageReports": [ { "kind": "admin#reports#usageReport", "date": "2017-12-11", "entity": { "type": "OBJECT", "customerId": "C03az79cb", "objectType": "GPLUS_COMMUNITY", "objectId": "1234", }, "parameters": [ { "name": "gplus:community_name", "stringValue": "My Community" }, { "name": "gplus:num_total_members", "intValue": 37 }, { "name": "gplus:num_7day_active_members", "intValue": 12 }, { "name": "gplus:num_30day_active_members", "intValue": 17 }, ] } ] }
مثال على استجابة JSON لتقرير الكيانات الذي يتضمّن تحذيرات
وقد يظهر تحذير واحد أو أكثر في الردّ في حال تعذّر تلبية الطلب. في هذا المثال، لا يكون التقرير متاحًا في وقت تقديم الطلب.{ "kind": "reports#usageReports", "warnings": [ { "code": "PARTIAL_DATA_AVAILABLE" "message": "Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours." "data": [ { "key": "date" "value": "2017-12-11" } ] } ], "usageReports": [], }يحتوي كل إدخال في صفيف
warnings
على المعلَمات التالية:
code
: رمز تحذير يمكن للآلة قراءتهmessage
: رسالة تحذير يمكن لشخص عادي قراءتهاdata
: قائمة بأزواج المفتاح/القيمة التي تقدّم معلومات تحذيرية مفصّلة