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 เป็นตัวระบุเอนทิตีที่ใช้เฉพาะกับแอปพลิเคชันที่เอนทิตีอยู่ ดูรายละเอียดเกี่ยวกับวิธีรับ entityKey สำหรับเอนทิตีที่คุณสนใจได้ที่ข้อมูลอ้างอิง API พารามิเตอร์อื่นๆ จะบันทึกไว้ด้านบนในส่วน ดึงข้อมูลกิจกรรมการใช้งานเอนทิตีทั้งหมด

ดูข้อมูลเพิ่มเติมเกี่ยวกับพารามิเตอร์สตริงการค้นหาและพร็อพเพอร์ตี้การตอบกลับได้ที่ข้อมูลอ้างอิง 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: รายการคู่คีย์-ค่าที่ให้ข้อมูลคำเตือนโดยละเอียด