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

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

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

รายงาน

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

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

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

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

หากต้องการค้นหารหัสข้อมูลพร็อพเพอร์ตี้ ให้ค้นหาเมธอดข้อมูลสรุปบัญชี หรือใช้ Account Explorer หากไม่มีการระบุช่วงวันที่ ช่วงวันที่เริ่มต้นคือ {"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"}]
    }
  ]
}

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

การกรอง

เมื่อส่งคําขอ batchGet คุณอาจขอให้คําขอแสดงเฉพาะเมตริกที่ตรงกับเกณฑ์ที่ระบุเท่านั้น หากต้องการกรองเมตริก ในส่วนคําขอ ให้ระบุ MetricFilterClauses และ MetricFilterClause แต่ละรายการอย่างน้อย 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"}
      ]
    }
  ]
}

ขนาด

มิติข้อมูลจะอธิบายลักษณะของผู้ใช้ เซสชันและการทำงานของผู้ใช้ ตัวอย่างเช่น มิติข้อมูลเมืองจะอธิบายลักษณะของเซสชันและระบุเมือง ("Paris" หรือ "New York") ที่แต่ละเซสชันเกิดขึ้น ในคําขอ 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 คุณอาจขอให้แอปแสดงเฉพาะมิติข้อมูลที่ตรงตามเกณฑ์ที่ระบุเท่านั้น หากต้องการกรองมิติข้อมูล ในเนื้อหาคําขอ ให้ระบุอย่างน้อย 1 รายการ มิติข้อมูลตัวกรองตัวกรอง และในแต่ละ DimensionsFilterClause กําหนดหนึ่งตัวกรองขึ้นไป ตัวกรองตัวกรอง ในแต่ละ 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"
        }
      ]
    }
  ]
}

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

API การรายงาน Google Analytics 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 หรือ 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"
    }
  ]
}

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

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

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

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

Analytics Reporting API เวอร์ชัน 4 ใช้ช่อง 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&#39