Reports API: รายงานการใช้งานเอนทิตี

รายงานการใช้งานเอนทิตีจะแสดงกิจกรรมบริการของ Google Workspace ที่เกี่ยวข้องกับเอนทิตีที่ผู้ใช้บัญชีของคุณใช้ รายงานเหล่านี้สามารถ ปรับแต่งและกรองเพื่อดูข้อมูลการใช้งานที่เฉพาะเจาะจงได้ ข้อมูลพร้อมใช้งานในช่วง 30 วันที่ผ่านมา

คุณใช้รายงานการใช้งานเอนทิตีได้เพื่อวัตถุประสงค์ที่ชอบด้วยกฎหมายเท่านั้น ตามข้อตกลงลูกค้า รายงานเหล่านี้มีผลกับ Google Workspace และ Education ด้วย

ดึงข้อมูลกิจกรรมการใช้งานเอนทิตีทั้งหมด

เอนทิตีประเภทเดียวที่ API นี้รองรับคือชุมชน Google+ หากต้องการดึงข้อมูลรายงานกิจกรรมทั้งหมดที่เกี่ยวข้องกับเอนทิตีแอปในบัญชี ให้ใช้ GET คำขอ HTTP ต่อไปนี้และรวมโทเค็นการให้สิทธิ์ที่อธิบายไว้ใน เอกสารประกอบการให้สิทธิ์ ตัวอย่างต่อไปนี้มีการจัดรูปแบบด้วยการขึ้นบรรทัดใหม่เพื่อให้ง่ายต่อการอ่าน

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