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: รายการคู่คีย์-ค่าที่ให้ข้อมูลคำเตือนโดยละเอียด