หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

สร้างงานรายงาน

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

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

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

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

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

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

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

ส่งคำขอสร้างงานรายงาน

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

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

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

คำขอ 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 มีชื่องานของรายงานในช่อง name (เช่น properties/1234567/reportTasks/123) ซึ่งใช้ในการค้นหาครั้งต่อๆ ไปเพื่อดูสถานะของงานรายงานและดึงรายงานผลลัพธ์ได้

การตอบสนองของ 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"
    }
  }
}

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

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

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

เช่น

คำขอ HTTP

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

สถานะความพร้อมสําหรับงานรายงานจะแสดงในช่อง state ของการตอบกลับ เมื่อสร้างรายงานเสร็จแล้ว สถานะของงานรายงานจะเปลี่ยนจาก 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
  }
}

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

เรียกดูรายงานที่สร้างขึ้น

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

คำขอ HTTP

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

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

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

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

...

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