Reports API: รายงานการใช้งานเอนทิตี
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
รายงานการใช้งานเอนทิตีจะแสดงกิจกรรมบริการของ Google Workspace ที่เกี่ยวข้องกับเอนทิตี
ที่ผู้ใช้ของบัญชีใช้ สามารถปรับแต่งและกรองรายงานเหล่านี้สำหรับการใช้งานที่เฉพาะเจาะจงได้
มีข้อมูลในช่วง 30 วันที่ผ่านมา
รายงานการใช้งานของเอนทิตีจะใช้เพื่อวัตถุประสงค์ที่ถูกต้องตามกฎหมายเท่านั้น
ตามข้อตกลงของลูกค้า รายงานเหล่านี้ยังใช้กับ
Google Workspace และ Education
ดึงข้อมูลกิจกรรมการใช้งานเอนทิตีทั้งหมด
ขณะนี้ เอนทิตีประเภทเดียวที่ API นี้รองรับคือ 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 เราขอแนะนำให้คุณ
ใช้เขตเวลาของบัญชีสำหรับการดำเนินการนี้ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับพารามิเตอร์สตริงการค้นหาและ
พร็อพเพอร์ตี้การตอบกลับ โปรดดู API
ข้อมูลอ้างอิง สำหรับข้อมูลเกี่ยวกับพารามิเตอร์รายงานการใช้งานเอนทิตี โปรดดู
พารามิเตอร์การใช้งานเอนทิตี
ข้อมูลอ้างอิง
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 คน ดูตัวอย่างการตอบกลับจาก API ได้ที่
ตัวอย่างการตอบกลับ 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 คือตัวระบุเอนทิตีที่ใช้เฉพาะสำหรับแอปพลิเคชันที่มีตัวระบุเอนทิตี
เอนทิตียังมีชีวิตอยู่ โปรดดู API
โปรดดู สำหรับรายละเอียดเกี่ยวกับวิธีขอรับ entityKey สำหรับเอนทิตีที่เฉพาะเจาะจง
สนใจ พารามิเตอร์อื่นๆ แสดงไว้ด้านบนภายใต้
ดึงข้อมูลกิจกรรมการใช้งานเอนทิตีทั้งหมด
ดูข้อมูลเพิ่มเติมเกี่ยวกับพารามิเตอร์สตริงการค้นหาและพร็อพเพอร์ตี้การตอบกลับได้ที่ข้อมูลอ้างอิง API สำหรับข้อมูล
เกี่ยวกับพารามิเตอร์รายงานการใช้งานเอนทิตี โปรดดู
พารามิเตอร์การใช้งานเอนทิตี
ข้อมูลอ้างอิง
ตัวอย่าง
ตัวอย่างต่อไปนี้ได้รับรายงานเอนทิตีสำหรับเอนทิตี 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 สำหรับรายงานเอนทิตีที่มีคำเตือน
ระบบอาจแสดงผลคำเตือนอย่างน้อย 1 รายการในการตอบกลับหากดำเนินการตามคำขอไม่ได้ ด้วยวิธีนี้
เช่น รายงานจะไม่พร้อมใช้งาน ณ เวลาที่ส่งคำขอ
{
"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: รายการคู่คีย์-ค่าที่ให้ข้อมูลคำเตือนโดยละเอียด
เนื้อหาของหน้าเว็บนี้ได้รับอนุญาตภายใต้ใบอนุญาตที่ต้องระบุที่มาของครีเอทีฟคอมมอนส์ 4.0 และตัวอย่างโค้ดได้รับอนุญาตภายใต้ใบอนุญาต Apache 2.0 เว้นแต่จะระบุไว้เป็นอย่างอื่น โปรดดูรายละเอียดที่นโยบายเว็บไซต์ Google Developers Java เป็นเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-08-29 UTC
[null,null,["อัปเดตล่าสุด 2025-08-29 UTC"],[],[],null,["# Reports API: Entities Usage Report\n\nThe entities usage report returns Google Workspace service activities related to entities\nused by your account's users. These reports can be customized and filtered for specific usage\ninformation. Data is available for the past 30 days.\n\nThe entities usage report may be used only for lawful purposes in\naccordance with your Customer Agreement. These reports also apply to\nGoogle Workspace and Education.\n\nRetrieve all entities usage activities\n--------------------------------------\n\nCurrently, the only entity type supported by this API is Google+ communities. To retrieve a\nreport of all activities related to app entities in your account, use the following\n`GET` HTTP request and include the authorization token described in the\n[authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For\nreadability, the following example is formatted with line returns: \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date\n?parameters=applicationParameters\n&filters=parameterFilters\n&maxResults=maxResults\n```\n\nThe \u003cvar translate=\"no\"\u003edate\u003c/var\u003e value is the date the usage occurred and the timestamp is in the\n[ISO 8601 format](http://en.wikipedia.org/wiki/ISO_8601), yyyy-mm-dd. We recommend you\nuse your account's time zone for this. For more information about the query string parameters and\nresponse properties, see the [API\nReference](/workspace/admin/reports/v1/reference/entityUsageReports/get). For information about the entities usage report parameters, see the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/entities).\n\n\u003cvar translate=\"no\"\u003eapplicationParameters\u003c/var\u003e is a comma-separated list of parameters you wish to retrieve.\nEach parameter is formatted as `application:parameter_name`, for example,\n`gplus:community_name`. The available parameters are documented in the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/entities). If no parameters are specified, all are returned.\n\n\u003cvar translate=\"no\"\u003eparameterFilters\u003c/var\u003e is a comma-separated list of filters to apply to the results. Each\nfilter is formatted as\n`application:parameter_name[relational_operator]parameter_value`. For example, the\nfilter `gplus:num_total_members\u003e100` filters the results to contain only results\nwhere the `gplus:num_total_members` parameter has a value greater than 100.\n\n\u003cvar translate=\"no\"\u003emaxResults\u003c/var\u003e is the maximum number of results to return in a single fetch. If the total\nnumber of results is greater than this, the response will be truncated and a\n`nextPageToken` will be included (see the\n[JSON response example](#example_response) below).\n\n### Examples\n\nThe following example gets a report containing all parameters\nfor all `gplus_communities` entities. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all\n/dates/2017-12-11\n```\n\nThe following example gets a report containing the `community_name` parameter\nfor all `gplus_communities` entities. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all\n/dates/2017-12-11?parameters=gplus:community_name\n```\n\nThe following example gets a report of `community_name` and\n`num_total_members` for each `gplus_communities` entity, filtered by\ncommunities with more than 100 members. For an example of an API response, see the\n[JSON response example](#example_response). \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11\n?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members\u003e100\n```\n\nRetrieve a report for a specific entity\n---------------------------------------\n\nTo retrieve a report for a specific entity, use the following `GET` HTTP request and\ninclude the authorization token described in the\n[authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For\nreadability, the following example is formatted with line returns. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date\n?parameters=applicationParameters\n&filters=parameterFilters\n&maxResults=maxResults\n```\n\nThe \u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e is an entity identifier which is specific to the application where the\nentity lives. See the [API\nReference](/workspace/admin/reports/v1/reference/userUsageReport/get) for details on how to obtain the \u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e for the particular entity you\nare interested in. The other parameters are documented above under\n[Retrieve all entities usage activities](#get_all_entities_usage).\n\nFor more information about the query string parameters and response properties, see the [API Reference](/workspace/admin/reports/v1/reference/userUsageReport/get). For information\nabout the entities usage report parameters, see the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/users).\n\n### Examples\n\nThe following example gets the entity report for a `gplus_community` entity with the\n\u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e \"1234\". \n\n```\nhttps://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11\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\nthe status code, the response returns a report. Some of the parameters in the response have been\nomitted for readability.\n\n#### Example JSON response for entities report\n\n```carbon\n{\n \"kind\": \"reports#usageReports\",\n \"nextPageToken\": \"NjQ1OTgwODk0MzkxNDAwNjQ0OA\",\n \"usageReports\": [\n {\n \"kind\": \"admin#reports#usageReport\",\n \"date\": \"2017-12-11\",\n \"entity\": {\n \"type\": \"OBJECT\",\n \"customerId\": \"C03az79cb\",\n \"objectType\": \"GPLUS_COMMUNITY\",\n \"objectId\": \"1234\",\n },\n \"parameters\": [\n {\n \"name\": \"gplus:community_name\",\n \"stringValue\": \"My Community\"\n },\n {\n \"name\": \"gplus:num_total_members\",\n \"intValue\": 37\n },\n {\n \"name\": \"gplus:num_7day_active_members\",\n \"intValue\": 12\n },\n {\n \"name\": \"gplus:num_30day_active_members\",\n \"intValue\": 17\n },\n ]\n }\n ]\n}\n```\n\n#### Example JSON response for entities report with warnings\n\nOne or more warnings may be returned in the response if the request cannot be fulfilled. In this example, the report is not available at the time the request is made. \n\n```scdoc\n{\n \"kind\": \"reports#usageReports\",\n \"warnings\": [\n {\n \"code\": \"PARTIAL_DATA_AVAILABLE\"\n \"message\": \"Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours.\"\n \"data\": [\n {\n \"key\": \"date\"\n \"value\": \"2017-12-11\"\n }\n ]\n }\n ],\n \"usageReports\": [],\n}\n```\nEach entry in the `warnings` array has the following parameters:\n\n- `code`: machine-readable warning code\n- `message`: human-readable warning message\n- `data`: list of key-value pairs which give detailed warning information"]]
