หลักการพื้นฐานของรายงาน

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

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

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

สร้างฟังก์ชันงานรายงาน

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

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

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

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

ส่งคำขอสร้างฟังก์ชันงานรายงาน

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

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

ตัวอย่างคำขอสร้างฟังก์ชันงานรายงาน

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 จะมีชื่อฟังก์ชันงานรายงานในฟิลด์ name (เช่น properties/1234567/reportTasks/123) ซึ่งสามารถใช้ในคําค้นหาในภายหลังเพื่อดูสถานะของฟังก์ชันงานรายงานและดึงข้อมูลรายงานที่ได้

{
  "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"
    }
  }
}

ดูสถานะความพร้อมของฟังก์ชันงานรายงาน

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

ใช้ชื่อฟังก์ชันงานรายงาน (เช่น properties/1234567/reportTasks/123) ที่ได้รับจากการตอบสนอง reportTasks.create เพื่อระบุฟังก์ชันงานรายงาน

ตัวอย่าง

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

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

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

{
  "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
  }
}

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

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

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

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

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

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

...

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