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

นี่คือคู่มือนักพัฒนาซอฟต์แวร์เกี่ยวกับ API การรายงานของ Analytics v4 สำหรับข้อมูลอ้างอิงโดยละเอียดของ API โปรดดูเอกสารอ้างอิง API

รายงาน

Analytics Reporting API v4 ให้เมธอด batchGet เพื่อเข้าถึงทรัพยากรรายงาน ส่วนต่อไปนี้อธิบายโครงสร้างของเนื้อหาคำขอสำหรับ batchGet และโครงสร้างของเนื้อหาการตอบกลับจาก batchGet

เนื้อความของคำขอ

หากต้องการใช้ Reporting API ของ Analytics v4 เพื่อขอข้อมูล คุณต้องสร้างออบเจ็กต์ ReportRequest ซึ่งมีข้อกำหนดขั้นต่ำดังต่อไปนี้

  • รหัสข้อมูลพร็อพเพอร์ตี้ที่ถูกต้องสําหรับช่อง viewId
  • ข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่อง dateRanges
  • ข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่องmetrics

หากต้องการหารหัสข้อมูลพร็อพเพอร์ตี้ ให้ค้นหาเมธอดสรุปบัญชีหรือใช้โปรแกรมสำรวจบัญชี หากไม่ระบุช่วงวันที่ ช่วงวันที่เริ่มต้นจะเป็น {"startDate": "7daysAgo", "endDate": "yesterday"}

ต่อไปนี้คือคำขอตัวอย่างที่มีฟิลด์ขั้นต่ำที่จำเป็น

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:users"}]
    }
  ]
}

เมธอด batchGet ยอมรับออบเจ็กต์ ReportRequest สูงสุด 5 รายการ คำขอทั้งหมดควรมี dateRange, viewId, segments, samplingLevel และ cohortGroup เหมือนกัน

เนื้อหาการตอบกลับ

เนื้อหาการตอบกลับ ของคำขอ API เป็นอาร์เรย์ของออบเจ็กต์รายงาน โครงสร้างรายงานจะกำหนดในออบเจ็กต์ ColumnHeader ซึ่งอธิบายถึงมิติข้อมูลและเมตริก และประเภทข้อมูลในรายงาน ค่าของมิติข้อมูลและเมตริกจะระบุอยู่ในช่องข้อมูล

คำตอบตัวอย่างสำหรับคำขอตัวอย่างข้างต้นมีดังนี้

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

เมตริก

เมตริกคือการวัดเชิงปริมาณ คำขอทุกรายการต้องมีออบเจ็กต์เมตริกอย่างน้อย 1 รายการ

ในตัวอย่างต่อไปนี้ จะมีการส่งเมตริก Sessions ให้กับเมธอด batchGet เพื่อหาจํานวนเซสชันทั้งหมดในช่วงวันที่ที่ระบุ

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:sessions"}]
    }
  ]
}

คุณใช้เครื่องมือสำรวจมิติข้อมูลและเมตริกหรือ API ข้อมูลเมตาเพื่อดูรายการมิติข้อมูลและเมตริกที่ใช้ได้

การกรอง

เมื่อส่งคำขอ batchGet คุณจะขอให้คำขอแสดงผลเฉพาะเมตริกที่ตรงตามเกณฑ์ที่ระบุได้ หากต้องการกรองเมตริก ในส่วนเนื้อหาของคำขอ ให้ระบุ MetricFilterClauses อย่างน้อย 1 รายการ และใน MetricFilterClause แต่ละรายการ ก็ให้กำหนด MetricFilters อย่างน้อย 1 รายการ ใน MetricFilter แต่ละรายการ ให้ระบุค่าสำหรับรายการต่อไปนี้

  • metricName
  • not
  • operator
  • comparisonValue

ให้ {metricName} แทนเมตริก {operator} operator และ {comparisonValue} comparisonValue จากนั้นตัวกรองจะทำงานดังนี้

if {metricName} {operator} {comparisonValue}
   return the metric

หากคุณระบุ true สำหรับ not ตัวกรองจะทำงานดังนี้

if {metricName} {operator} {comparisonValue}
   do not return the metric

ในตัวอย่างต่อไปนี้ batchGet จะแสดงเฉพาะการดูหน้าเว็บที่มีค่ามากกว่า 2

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

นิพจน์

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

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

การเรียงลำดับ

วิธีจัดเรียงผลลัพธ์ตามค่าเมตริก

  • ระบุชื่อหรือชื่อแทนในช่อง fieldName
  • ระบุลำดับการจัดเรียง (ASCENDING หรือ DESCENDING) ผ่านช่อง sortOrder

ในตัวอย่างต่อไปนี้ batchGet จะแสดงเมตริกที่จัดเรียงก่อนตามเซสชัน จากนั้นจะแสดงตามการดูหน้าเว็บจากมากไปน้อย

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

ขนาด

มิติข้อมูลจะอธิบายลักษณะของผู้ใช้ เซสชันและการทำงานของผู้ใช้ ตัวอย่างเช่น มิติข้อมูลเมืองจะอธิบายลักษณะของเซสชันและระบุเมือง ("ปารีส" หรือ "นิวยอร์ก") ซึ่งเป็นที่มาของแต่ละเซสชัน ในคำขอ batchGet คุณสามารถระบุออบเจ็กต์มิติข้อมูลตั้งแต่ 0 รายการขึ้นไป เช่น

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics":
      [
        {"expression": "ga:users"}
      ],
      "dimensions":
      [
        {"name": "ga:city"}
      ]
    }
  ]
}

การกรอง

เมื่อส่งคำขอ batchGet คุณจะขอให้คำขอแสดงผลเฉพาะมิติข้อมูลที่ตรงตามเกณฑ์ที่ระบุได้ หากต้องการกรองมิติข้อมูล ในส่วนเนื้อหาของคำขอ ให้ระบุ DimensionsFilterClauses อย่างน้อย 1 รายการ และใน DimensionsFilterClause แต่ละรายการ ให้กำหนดDimensionsFiltersอย่างน้อย 1 รายการ ใน DimensionsFilters แต่ละรายการ ให้ระบุค่าสำหรับรายการต่อไปนี้

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

ให้ {dimensionName} แสดงถึงมิติข้อมูล {operator} operator และ {expressions} expressions จากนั้นตัวกรองจะทำงานดังนี้

if {dimensionName} {operator} {expressions}
    return the dimension

หากคุณระบุ true สำหรับ not ตัวกรองจะทำงานดังนี้

if {dimensionName} {operator} {expressions}
    do not return the dimension

ในตัวอย่างต่อไปนี้ batchGet จะแสดงผลการดูหน้าเว็บและเซสชันในเบราว์เซอร์ Chrome

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

การเรียงลำดับ

วิธีจัดเรียงผลลัพธ์ตามค่ามิติข้อมูล

  • ระบุชื่อผ่านทางช่อง fieldName
  • ระบุลำดับการจัดเรียง (ASCENDING หรือ DESCENDING) ผ่านช่อง sortOrder

ตัวอย่างเช่น batchGet ต่อไปนี้จะแสดงมิติข้อมูลที่จัดเรียงตามประเทศ แล้วแสดงผลตามเบราว์เซอร์

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

ที่เก็บข้อมูลฮิสโตแกรม

สำหรับมิติข้อมูลที่มีค่าจำนวนเต็ม คุณจะทำความเข้าใจลักษณะเฉพาะของมิติข้อมูลได้ง่ายขึ้นโดยการจัดเก็บค่าไว้เป็นช่วง ใช้ช่อง histogramBuckets เพื่อกำหนดช่วงสำหรับที่เก็บข้อมูลผลลัพธ์และระบุ HISTOGRAM_BUCKET เป็นประเภทลำดับ เช่น

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

หลายช่วงวันที่

Google Analytics Reporting API v4 ช่วยให้คุณได้รับข้อมูลในช่วงวันที่หลายช่วงในคำขอเดียว ไม่ว่าคำขอของคุณจะระบุช่วงวันที่ 1 หรือ 2 ช่วง ระบบจะแสดงผลข้อมูลในออบเจ็กต์ dateRangeValue ตัวอย่างเช่น

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

การสั่งซื้อแบบเดลต้า

เมื่อขอค่าเมตริกในช่วงวันที่ 2 ช่วง คุณสามารถเรียงลำดับผลลัพธ์ตามค่าต่างระหว่างค่าเมตริกในช่วงวันที่ดังกล่าว เช่น

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

ลักษณะการทำงานของมิติข้อมูลวันที่

หากคุณขอมิติข้อมูลที่เกี่ยวข้องกับ date or time ออบเจ็กต์ DateRangeValue จะเก็บเฉพาะค่าของวันที่ที่อยู่ภายในช่วงที่เกี่ยวข้อง ค่าอื่นๆ ทั้งหมดที่ไม่ได้อยู่ในช่วงวันที่ที่ระบุจะเป็น 0

ตัวอย่างเช่น ลองพิจารณาคำขอมิติข้อมูล ga:date และเมตริก ga:sessions ในช่วงวันที่ 2 ช่วง ได้แก่ มกราคมและกุมภาพันธ์ ในการตอบกลับสำหรับข้อมูลที่ขอในเดือนมกราคม ค่าในเดือนกุมภาพันธ์จะเป็น 0 และในการตอบกลับสำหรับข้อมูลที่ขอในเดือนกุมภาพันธ์ ค่าของเดือนมกราคมจะเป็น 0

รายงานเดือนมกราคม

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

รายงานเดือนกุมภาพันธ์

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

กลุ่ม

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

เมื่อส่งคำขอโดยใช้กลุ่ม โปรดตรวจสอบดังนี้

  • ReportRequest ทั้งหมดภายในเมธอด batchGet ต้องมีการกำหนดกลุ่มที่เหมือนกัน
  • คุณเพิ่ม ga:segment ลงในรายการมิติข้อมูล

เช่น

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

ดูตัวอย่างสำหรับตัวอย่างคำขอเพิ่มเติมที่มีกลุ่ม

รหัสกลุ่ม

ใช้ช่อง segmentId เพื่อขอกลุ่ม คุณใช้ทั้ง segmentId และ dynamicSegment เพื่อขอกลุ่มไม่ได้

เช่น

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

ทดสอบผลิตภัณฑ์

การสุ่มตัวอย่างอาจส่งผลต่อผลลัพธ์ของข้อมูล และเป็นสาเหตุที่พบบ่อยซึ่งทำให้ค่าที่แสดงผลจาก API ไม่ตรงกับอินเทอร์เฟซเว็บ ใช้ช่อง samplingLevel เพื่อกำหนดขนาดตัวอย่างที่ต้องการ

  • กำหนดค่าเป็น SMALL เพื่อการตอบสนองอย่างรวดเร็วโดยมีการสุ่มตัวอย่างขนาดเล็กลง
  • ตั้งค่าเป็น LARGE เพื่อการตอบสนองที่แม่นยำมากขึ้นแต่ช้าลง
  • ตั้งค่าเป็น DEFAULT สำหรับการตอบสนองที่รักษาสมดุลระหว่างความเร็วกับความแม่นยำ

เช่น

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

หากรายงาน มีข้อมูลจากการสุ่มตัวอย่าง Analytics Reporting API v4 จะแสดงช่อง samplesReadCounts และ samplingSpaceSizes หากไม่ได้สุ่มตัวอย่างผลลัพธ์ ช่องเหล่านี้จะไม่กำหนด

ด้านล่างคือตัวอย่างการตอบกลับซึ่งมีข้อมูลที่สุ่มตัวอย่างจากคำขอที่มีช่วงวันที่ 2 ช่วง ผลลัพธ์คำนวณจากเกือบ ตัวอย่าง 500,000 ตัวอย่าง จากพื้นที่การสุ่มตัวอย่างประมาณ 15 ล้านเซสชัน:

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

การใส่เลขหน้า

Analytics Reporting API v4 ใช้ช่อง pageToken และ pageSize เพื่อใส่เลขหน้าผ่านผลลัพธ์การตอบสนองที่ครอบคลุมหลายหน้า คุณได้ pageToken จากพารามิเตอร์ nextPageToken ในการตอบสนองต่อคำขอ reports.batchGet:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

ขั้นตอนถัดไป

เมื่อคุณได้เรียนรู้พื้นฐานในการสร้างรายงานแล้ว ต่อไปมาดูฟีเจอร์ขั้นสูงของ API v4 กัน