واجهة برمجة التطبيقات Reports API: تقرير استخدام المستخدمين
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يعرض تقرير استخدام المستخدم معلومات استخدام خدمة Google Workspace لمستخدم معيّن في نطاقك.
يمكن تخصيص هذه التقارير وفلترتها لعرض معلومات استخدام محدَّدة.
الفترة الزمنية التلقائية والحد الأقصى لكل تقرير هي آخر 450 يومًا.
لا يمكن استخدام تقرير استخدام المستخدم هذا إلا لأغراض قانونية وفقًا لاتفاقية العملاء. وتنطبق هذه التقارير أيضًا على Google Workspace وEducation.
استرداد جميع أنشطة استخدام المستخدم
لاسترداد تقرير عن جميع أنشطة المستخدمين في حسابك، استخدِم طلب HTTP التالي من GET وأدرِج الرمز المميّز للتفويض الموضّح في مستندات التفويض. لتسهيل القراءة، يتم تنسيق المثال التالي باستخدام إرجاع الأسطر:
GET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/yyyy-mm-dd date
?parameters=application: user usage parameter,...
&filters=application: user usage parameter relational operator usage parameter's value,...
&maxResults=number of events listed on each page of the report
تشير القيمة dates إلى تاريخ حدوث الاستخدام، ويظهر الطابع الزمني بتنسيق ISO 8601، yyyy-mm-dd. لمزيد من المعلومات عن معلَمات سلسلة طلب البحث وخصائص الاستجابة، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات. للحصول على معلومات عن مَعلمات تقرير استخدام المستخدِم، اطّلِع على مرجع مَعلمات استخدام المستخدِم.
يحصل المثال التالي على تقرير عن جميع أنشطة المستخدمين للحساب.
GET https://admin.googleapis.com/admin/reports/v1/usage/users/all
/dates/2013-03-03?maxResults=2
يحصل المثال التالي على تقرير عن جميع أنشطة المستخدمين لحساب عميل معيّن.
GET https://admin.googleapis.com/admin/reports/v1/usage/users/all
/dates/2013-03-03?customerId=C03az79cb
يحصل المثال التالي على تقرير عن الطوابع الزمنية الأخيرة لتسجيل الدخول للمستخدمين في الحساب. للحصول على مثال على استجابة واجهة برمجة التطبيقات، يمكنك الاطّلاع على مثال على استجابة JSON.
GET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/2013-03-03
?parameters=accounts:last_login_time&maxResults=2
يحصل المثال التالي على تقرير عن الطوابع الزمنية الأخيرة لتسجيل الدخول للمستخدمين في الحساب، وتتم فلترته حسب المستخدمين الذين سجّلوا الدخول بعد وقت محدّد. للحصول على مثال على استجابة واجهة برمجة التطبيقات، يمكنك الاطّلاع على مثال على استجابة JSON.
GET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/2013-03-03
?parameters=accounts:last_login_time&filters=accounts:last_login_time
>2010-10-28T10:26:35.000Z"
يحصل المثال التالي على تقرير عن الطوابع الزمنية الأخيرة لتسجيل الدخول وحالة تعليق المستخدمين في الحساب. للحصول على مثال على استجابة واجهة برمجة التطبيقات، يمكنك الاطّلاع على مثال على استجابة JSON.
GET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/2013-03-03
?parameters=accounts:last_login_time,accounts:is_disabled"
استرداد أنشطة الاستخدام لمستخدم معين
لاسترداد تقرير عن أنشطة مستخدم معيّن في حسابك، يمكنك استخدام طلب HTTP التالي GET وتضمين الرمز المميز للتفويض الموضح في مستندات التفويض. لتسهيل القراءة، يتم تنسيق المثال التالي باستخدام إرجاع الأسطر.
GET https://admin.googleapis.com/admin/reports/v1/usage/users/userKey/dates/yyyy-mm-dd date
?parameters=application: user usage parameter,...
&filters=application: user usage parameter relational operator usage parameter's value,...
&maxResults=number of events listed on each page of the report
يمكن أن يكون userKey إما عنوان البريد الإلكتروني الرئيسي للمستخدم الوارد في التقرير أو عنوان البريد الإلكتروني الفريد للمستخدم في Google Workspace profileId. تشير القيمة dates إلى تاريخ حدوث الاستخدام، ويظهر الطابع الزمني بتنسيق ISO 8601، yyyy-mm-dd. لمزيد من المعلومات عن معلَمات سلسلة طلب البحث وخصائص الاستجابة، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات. للحصول على معلومات عن مَعلمات تقرير استخدام المستخدِم، اطّلِع على مرجع مَعلمات استخدام المستخدِم.
يحصل المثال التالي على تقرير الاستخدام لـ john@example.com.
https://admin.googleapis.com/admin/reports/v1/usage/users/john@example.com/dates/2013-03-03
مثال على استجابة JSON في تقرير الاستخدام
عند الاستجابة الناجحة، يتم عرض رمز الحالة HTTP 200. بالإضافة إلى رمز الحالة، يعرض الرد تقريرًا.
استجابة JSON لتقرير المستخدم
{
"kind": "reports#usageReports",
"warnings": [
{
"code": warning machine-readable code,
"message": warning human-readable message,
"data": [
{
"key": key for key-value pair that gives detailed warning information,
"value": value for key-value pair giving detailed warning information
}
]
}
],
"nextPageToken": "N:NNN:NNN:N:C03az79cb",
"usageReports": [
{
"kind": "usageReport",
"date": "2013-03-03",
"entity": {
"type": "USER",
"customerId": "C03az79cb",
"userEmail": "liz@example.com",
"profileId": "user's unique Google Workspace ID"
},
"parameters": [
{
"name": "accounts:is_disabled",
"boolValue": false
},
{
"name": "accounts:disabled_reason",
"stringValue": "reason description"
},
{
"name": "accounts:first_name",
"stringValue": "Liz"
},
{
"name": "accounts:is_2sv_enforced",
"boolValue": false
},
{
"name": "accounts:is_2sv_enrolled",
"boolValue": false
},
{
"name": "accounts:last_name",
"stringValue": "Smith"
},
{
"name": "accounts:creation_time",
"datetimeValue": "2010-10-28T10:26:35.000Z"
},
{
"name": "accounts:last_login_time",
"datetimeValue": "1970-01-01T00:00:00.000Z"
},
{
"name": "accounts:last_sso_time",
"datetimeValue": "1970-01-01T00:00:00.000Z"
}
]
}
]
}
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Reports API: Users Usage Report\n\nThe user usage report returns Google Workspace service usage information for a particular user in your domain.\nThese reports can be customized and filtered for specific usage information.\nThe default and maximum time period for each report is the last 450 days.\n\nThese user usage report may be used only for lawful purposes in accordance with your Customer Agreement. And, these reports apply to Google Workspace and Education.\n\nRetrieve all user usage activities\n----------------------------------\n\nTo retrieve a report of all user activities in your account use the following `GET` HTTP request and include the authorization token described in the [authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For readability, the following example is formatted with line returns: \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/yyyy-mm-dd date\n?parameters=application: user usage parameter,...\n&filters=application: user usage parameter relational operator usage parameter's value,...\n&maxResults=number of events listed on each page of the report\n```\n\nThe `dates` value is the date the usage occurred and the timestamp is in the [ISO 8601 format](http://en.wikipedia.org/wiki/ISO_8601), yyyy-mm-dd. For more information about the query string parameters and response properties, see the [API Reference](/workspace/admin/reports/v1/reference/userUsageReport/get). For information about the user usage report parameters, see the [User Usage Parameters reference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/users).\n\nThe following example gets a report on all user activities for the account. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/users/all\n/dates/2013-03-03?maxResults=2\n```\n\nThe following example gets a report on all user activities for a specific customer account. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/users/all\n/dates/2013-03-03?customerId=C03az79cb\n```\n\nThe following example gets a report on the last login timestamps of the users in the account. For an example of an API response, see the [JSON response example](#example_response). \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/2013-03-03\n?parameters=accounts:last_login_time&maxResults=2\n```\n\nThe following example gets a report on the last login timestamps of the users in the account, filtered by users who logged in after a specific time. For an example of an API response, see the [JSON response example](#example_response). \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/2013-03-03\n?parameters=accounts:last_login_time&filters=accounts:last_login_time\n\u003e2010-10-28T10:26:35.000Z\"\n```\n\nThe following example gets a report on the last login timestamps and suspended status of the users in the account. For an example of an API response, see the [JSON response example](#example_response). \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/2013-03-03\n?parameters=accounts:last_login_time,accounts:is_disabled\"\n```\n\nRetrieve a specific user's usage activities\n-------------------------------------------\n\nTo retrieve a report of a specific user's activities in your account use the following `GET` HTTP request and include the authorization token described in the [authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For readability, the following example is formatted with line returns. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/users/userKey/dates/yyyy-mm-dd date\n?parameters=application: user usage parameter,...\n&filters=application: user usage parameter relational operator usage parameter's value,...\n&maxResults=number of events listed on each page of the report\n```\n\nThe `userKey` can be either the primary email address of the user in the report or the user's unique Google Workspace `profileId`. The `dates` value is the date the usage occurred and the timestamp is in the [ISO 8601 format](http://en.wikipedia.org/wiki/ISO_8601), yyyy-mm-dd. For more information about the query string parameters and response properties, see the [API Reference](/workspace/admin/reports/v1/reference/userUsageReport/get). For information about the user usage report parameters, see the [User Usage Parameters reference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/users).\n\nThe following example gets the usage report for john@example.com. \n\n```\nhttps://admin.googleapis.com/admin/reports/v1/usage/users/john@example.com/dates/2013-03-03\n```\n\nUsage report example JSON response\n----------------------------------\n\nA successful response returns an [HTTP 200 status code](http://wikipedia.org/wiki/List_of_HTTP_status_codes). Along with the status code, the response returns a report.\n\n#### JSON response for user report\n\n```carbon\n{\n \"kind\": \"reports#usageReports\",\n \"warnings\": [\n {\n \"code\": warning machine-readable code,\n \"message\": warning human-readable message,\n \"data\": [\n {\n \"key\": key for key-value pair that gives detailed warning information,\n \"value\": value for key-value pair giving detailed warning information\n }\n ]\n }\n ],\n \"nextPageToken\": \"N:NNN:NNN:N:C03az79cb\",\n \"usageReports\": [\n{\n \"kind\": \"usageReport\",\n \"date\": \"2013-03-03\",\n \"entity\": {\n \"type\": \"USER\",\n \"customerId\": \"C03az79cb\",\n \"userEmail\": \"liz@example.com\",\n \"profileId\": \"user's unique Google Workspace ID\"\n },\n \"parameters\": [\n {\n \"name\": \"accounts:is_disabled\",\n \"boolValue\": false\n },\n {\n \"name\": \"accounts:disabled_reason\",\n \"stringValue\": \"reason description\"\n },\n {\n \"name\": \"accounts:first_name\",\n \"stringValue\": \"Liz\"\n },\n {\n \"name\": \"accounts:is_2sv_enforced\",\n \"boolValue\": false\n },\n {\n \"name\": \"accounts:is_2sv_enrolled\",\n \"boolValue\": false\n },\n {\n \"name\": \"accounts:last_name\",\n \"stringValue\": \"Smith\"\n },\n {\n \"name\": \"accounts:creation_time\",\n \"datetimeValue\": \"2010-10-28T10:26:35.000Z\"\n },\n {\n \"name\": \"accounts:last_login_time\",\n \"datetimeValue\": \"1970-01-01T00:00:00.000Z\"\n },\n {\n \"name\": \"accounts:last_sso_time\",\n \"datetimeValue\": \"1970-01-01T00:00:00.000Z\"\n }\n ]\n }\n ]\n}\n```"]]
