พื้นฐานเกี่ยวกับงานในการรายงาน

การใช้ Report Task ช่วยให้คุณเริ่มคำขอแบบอะซิงโครนัสที่ใช้เวลานานเพื่อสร้างรายงานที่กำหนดเองของข้อมูลเหตุการณ์ Google Analytics ได้

ผู้ใช้ทุกคนที่มีสิทธิ์เข้าถึงแบบอ่านพร็อพเพอร์ตี้ Google Analytics สามารถใช้ทรัพยากร Report Task ที่สร้างขึ้นจากคำขอนี้เพื่อเข้าถึงรายงานที่กำหนดเองได้

รายงานที่กำหนดเองจะพร้อมใช้งานเป็นเวลา 72 ชั่วโมงหลังจากที่พร้อม หลังจากช่วงเวลานี้ ระบบจะลบทรัพยากร Report Task ที่เกี่ยวข้องและเนื้อหาของทรัพยากรนั้นโดยอัตโนมัติ

สร้าง Report Task

Google Analytics Data API v1 ใช้แนวทางแบบอะซิงโครนัสเพื่อสร้าง Report Task ขั้นแรก คุณต้องส่งคำขอไปยัง reportTasks.create เมธอด เพื่อสร้าง Report Task จากนั้นใช้เมธอด reportTasks.query เพื่อดึงข้อมูลรายงานที่กำหนดเองที่สร้างขึ้น

นอกจากนี้ คุณยังใช้ reportTasks.get เพื่อดึงข้อมูลเมตาของการกำหนดค่าเกี่ยวกับ Report Task ที่เฉพาะเจาะจง และใช้ reportTasks.list เพื่อแสดง Report Task ทั้งหมดสำหรับพร็อพเพอร์ตี้

เลือกเอนทิตีการรายงาน

เมธอดทั้งหมดของ Data API v1 กำหนดให้ระบุ ตัวระบุพร็อพเพอร์ตี้ Google Analytics ภายในเส้นทางคำขอ URL ในรูปแบบ properties/GA_PROPERTY_ID เช่น

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

ระบบจะสร้างรายงานตามข้อมูลเหตุการณ์ Google Analytics ที่รวบรวมในพร็อพเพอร์ตี้ Google Analytics ที่ระบุ

หากคุณใช้ไลบรารีของไคลเอ็นต์ Data API ไม่จำเป็นต้องจัดการเส้นทาง URL ของคำขอด้วยตนเอง ไคลเอ็นต์ API ส่วนใหญ่มีพารามิเตอร์ property ที่คาดหวังสตริงในรูปแบบ properties/GA_PROPERTY_ID ดูตัวอย่างการใช้ไลบรารีของไคลเอ็นต์ได้ที่คู่มือเริ่มต้นใช้งานฉบับย่อสำหรับตัวอย่าง

ส่งคำขอสร้าง Report Task

หากต้องการสร้าง Report Task ให้เรียกใช้ reportTasks.create เมธอด โดยใช้ ReportTask ออบเจ็กต์ในคำขอ พารามิเตอร์ต่อไปนี้จำเป็นต้องระบุ

  • reportDefinition ฟิลด์ซึ่งอธิบายคำจำกัดความของรายงานที่กำหนดเอง โครงสร้างของพารามิเตอร์นี้ คล้ายกับคำจำกัดความของรายงานที่ เมธอด Core Reporting ใช้

ตัวอย่างคำขอสร้าง Report Task

คำขอ HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
  "reportDefinition": {
    "dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }
}

การตอบกลับของเมธอด reportTasks.create จะมีชื่อ Report Task ในฟิลด์ name (เช่น properties/1234567/reportTasks/123) ซึ่งสามารถใช้ในการค้นหาในภายหลังเพื่อดูสถานะของ Report Task และดึงข้อมูลรายงานที่ได้

การตอบสนองของ HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
    "name": "properties/1234567/reportTasks/123",
    "reportDefinition": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ],
      "dateRanges": [
        {
          "startDate": "2024-05-01",
          "endDate": "2024-05-15"
        }
      ]
    },
    "reportMetadata": {
      "state": "CREATING",
      "beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
    }
  }
}

ดูสถานะความพร้อมของ Report Task

ระบบอาจใช้เวลาหลายนาทีในการสร้างรายงานหลังจากเรียกใช้ reportTasks.create คุณดูสถานะความพร้อมของ Report Task ได้โดยเรียกใช้ reportTasks.get เมธอด

ใช้ชื่อ Report Task (เช่น properties/1234567/reportTasks/123) ที่คุณได้รับจากการตอบกลับ reportTasks.create เพื่อระบุ Report Task

ตัวอย่าง

คำขอ HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

ระบบจะแสดงสถานะความพร้อมของ Report Task ใน state ฟิลด์ของการตอบกลับ เมื่อการสร้างรายงานเสร็จสมบูรณ์แล้ว สถานะของ Report Task จะเปลี่ยนจาก CREATING เป็น ACTIVE

ฟิลด์ reportMetadata จะมีข้อมูลระดับสูงเกี่ยวกับรายงานที่สร้างขึ้น เช่น จำนวนแถวและจำนวนโทเค็นโควต้าที่เรียกเก็บ

การตอบสนองของ HTTP

{
  "reportDefinition": {
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ]
  },
  "reportMetadata": {
    "state": "ACTIVE",
    "beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
    "creationQuotaTokensCharged": 6,
    "taskRowCount": 167,
    "errorMessage": "",
    "totalRowCount": 167
  }
}

คุณดูสถานะของ Report Task ทั้งหมดได้โดยเรียกใช้ reportTasks.list เมธอด

ดึงข้อมูลรายงานที่สร้างขึ้น

เมื่อสร้าง Report Task โดยใช้ reportTasks.create แล้ว ให้เรียกใช้ reportTasks.query และระบุชื่อ Report Task (เช่น properties/1234567/reportTasks/123)

คำขอ HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

หาก Report Task พร้อมแล้ว ระบบจะแสดงการตอบกลับที่มีรายงานที่สร้างขึ้น

การตอบสนองของ HTTP

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}