Reports API: گزارش استفاده کاربران
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
گزارش استفاده کاربر، اطلاعات استفاده از سرویس Google Workspace را برای یک کاربر خاص در دامنه شما برمی‌گرداند. این گزارش ها را می توان برای اطلاعات استفاده خاص سفارشی و فیلتر کرد. دوره زمانی پیش‌فرض و حداکثر برای هر گزارش 450 روز گذشته است.
این گزارش استفاده از کاربر ممکن است فقط برای اهداف قانونی مطابق با توافق نامه مشتری شما استفاده شود. و این گزارش‌ها برای Google Workspace و Education اعمال می‌شود.
بازیابی تمام فعالیت های استفاده از کاربر
برای بازیابی گزارشی از تمام فعالیت‌های کاربر در حساب خود، از درخواست GET HTTP زیر استفاده کنید و کد مجوز شرح داده شده در اسناد مجوز را اضافه کنید. برای خوانایی، مثال زیر با بازگشت خط فرمت شده است:
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 است. برای اطلاعات بیشتر در مورد پارامترهای رشته پرس و جو و خواص پاسخ، به مرجع API مراجعه کنید. برای اطلاعات در مورد پارامترهای گزارش استفاده کاربر، به مرجع پارامترهای استفاده کاربر مراجعه کنید.
مثال زیر گزارشی از تمام فعالیت های کاربر برای حساب دریافت می کند.
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
مثال زیر گزارشی از آخرین مهرهای زمانی ورود به سیستم کاربران در حساب دریافت می کند. برای مثالی از پاسخ API، به مثال پاسخ JSON مراجعه کنید.
GET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/2013-03-03
?parameters=accounts:last_login_time&maxResults=2
مثال زیر گزارشی از آخرین مهرهای زمانی ورود کاربران در حساب دریافت می‌کند که توسط کاربرانی که پس از یک زمان خاص وارد شده‌اند فیلتر شده است. برای مثالی از پاسخ API، به مثال پاسخ 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"
مثال زیر گزارشی از آخرین مهرهای زمانی ورود به سیستم و وضعیت تعلیق کاربران در حساب دریافت می‌کند. برای مثالی از پاسخ API، به مثال پاسخ JSON مراجعه کنید.
GET https://admin.googleapis.com/admin/reports/v1/usage/users/all/dates/2013-03-03
?parameters=accounts:last_login_time,accounts:is_disabled"
بازیابی فعالیت های استفاده از یک کاربر خاص
برای بازیابی گزارشی از فعالیت های یک کاربر خاص در حساب خود، از درخواست GET HTTP زیر استفاده کنید و کد مجوز شرح داده شده در مستندات مجوز را اضافه کنید. برای خوانایی، مثال زیر با بازگشت خط فرمت شده است.
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 می‌تواند آدرس ایمیل اصلی کاربر در گزارش یا profileId Google Workspace منحصر به فرد کاربر باشد. مقدار dates ، تاریخ استفاده است و مهر زمانی در قالب ISO 8601 ، yyyy-mm-dd است. برای اطلاعات بیشتر در مورد پارامترهای رشته پرس و جو و خواص پاسخ، به مرجع API مراجعه کنید. برای اطلاعات در مورد پارامترهای گزارش استفاده کاربر، به مرجع پارامترهای استفاده کاربر مراجعه کنید.
مثال زیر گزارش استفاده را برای 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 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده 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```"]]
