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

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

รายงาน

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

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

หากต้องการใช้ Analytics Reporting API 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"
        }
      ]
    }
  ]
}

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

หากคุณขอมิติข้อมูลที่เกี่ยวข้องกับวันที่และเวลา ออบเจ็กต์ 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 กัน