本頁面由 Cloud Translation API 翻譯而成。

進階用途

本文說明 Google Analytics Data API v1 的多項進階功能。如需 API 的詳細參考資料，請參閱 API 參考資料。

列出自訂定義並建立報表

Data API 可根據註冊的自訂維度和自訂指標建立報表。中繼資料 API 方法可用於列出資源註冊的自訂定義的 API 名稱。這些 API 名稱可用於向 runReport 方法傳送的報表要求。

以下各節將列舉各種類型自訂定義的範例。在這些範例中，請將 GA_PROPERTY_ID 替換為您的房源 ID。

以事件為範圍的自訂維度

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

步驟 2：找出您想從回應中建立報表的以事件為範圍的自訂維度。如果沒有這個維度，您需要註冊維度。

"dimensions": [
...
    {
      "apiName": "customEvent:achievement_id",
      "uiName": "Achievement ID",
      "description": "An event scoped custom dimension for your Analytics property."
    },
...
],

步驟 3：在報表要求中加入自訂維度。以下是對 runReport 方法提出的範例要求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

以使用者為範圍的自訂維度

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

步驟 2：找出您想從回應中建立報表的以使用者為範圍的自訂維度。如果沒有這個維度，您需要註冊維度。

"dimensions": [
...
    {
      "apiName": "customUser:last_level",
      "uiName": "Last level",
      "description": "A user property for your Analytics property."
    },
...
],

步驟 3：在報表要求中加入自訂維度。以下是對 runReport 方法提出的範例要求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

事件界定範圍自訂指標

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

步驟 2：找出您想從回應中建立報表的以事件為範圍的自訂指標。如果沒有指標，您需要註冊指標。

"metrics": [
...
    {
      "apiName": "customEvent:credits_spent",
      "uiName": "Credits Spent",
      "description": "An event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

步驟 3：在報表要求中加入自訂指標。以下是對 runReport 方法提出的範例要求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

單一重要事件的重要事件發生率指標

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

步驟 2：找出您想從回應中建立報表的單一重要事件的重要事件發生率指標。如果沒有重要事件，您需要設定重要事件。

"metrics": [
...
    {
      "apiName": "sessionKeyEventRate:add_to_cart",
      "uiName": "Session key event rate for add_to_cart",
      "description": "The percentage of sessions in which a specific key event was triggered",
    },
...
],

步驟 3：在報表要求中納入重要事件發生率指標。以下是對 runReport 方法提出的範例要求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}

以事件為範圍的自訂指標平均值

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

步驟 2：找出您想從回應中建立報表的事件範圍自訂指標平均值。如果沒有指標，您需要註冊指標。

"metrics": [
...
    {
      "apiName": "averageCustomEvent:credits_spent",
      "uiName": "Average Credits Spent",
      "description": "The average of an event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

步驟 3：在報表要求中納入自訂指標平均值。以下是對 runReport 方法提出要求的範例。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

同類群組報表範例

同類群組報表會為同類群組建立使用者留存時間序列。如需各個 API 欄位的詳細說明文件，請參閱 CohortSpec 的 REST 參考資料。

建立同類群組報表

以下是同類群組報表範例：

同類群組是指 firstSessionDate 為 2020-12-01 的使用者，這項資訊是由 cohorts 物件設定。報表回應中的維度和指標僅會以同類群組的使用者為依據。
同類群組報表會顯示三個欄，這是由維度和指標物件設定。
- 維度 cohort 是同類群組的名稱。
- 維度 cohortNthDay 是從 2020-12-01 算起的天數。
- 指標 cohortActiveUsers 是仍活躍的使用者人數。
cohortsRange 物件會指定報表應包含此同類群體從 2020-12-01 開始到 2020-12-06 結束的事件資料。
- 使用 DAILY 精細度時，建議使用 cohortNthDay 維度以保持一致性。

同類群組的報表要求如下：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "DAILY"
    }
  },
}

針對這項要求，報表回應範例如下：

{
  "dimensionHeaders": [
    { "name": "cohort" }, { "name": "cohortNthDay" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "293" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "143" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "123" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "92" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
      "metricValues": [{ "value": "86" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "83" }]
    }
  ],
  "metadata": {},
  "rowCount": 6
}

根據這份報表回應，以下是這份同類群組報表的圖表。這份報表提供的洞察指出，這個同類群組的活躍使用者在第一天和第二天之間出現最大降幅。

以視覺化方式呈現同類群組使用者隨時間變化

多個同類群組和使用者留存率分數

獲客和留客是網站或應用程式成長的關鍵。同類群組報表則著重於使用者留存。在這個範例中，報表顯示這個資源在兩週內，4 天使用者留存率提升了 10%。

為建立這份報表，我們指定了三個同類群組：第一個同類群組的 firstSessionDate 為 2020-11-02，第二個同類群組的 firstSessionDate 為 2020-11-09，第三個同類群組的 firstSessionDate 為 2020-11-16。由於資源的使用者人數會在這三天內有所不同，我們會比較 cohortActiveUsers/cohortTotalUsers 同類群組的使用者留存比率指標，而非使用直接 cohortActiveUsers 指標。

這些同類群組的報表要求如下：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metrics": [
    {
      "name": "cohortRetentionFraction",
      "expression": "cohortActiveUsers/cohortTotalUsers"
    }
  ],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
      }
    ],
    "cohortsRange": {
      "endOffset": 4,
      "granularity": "DAILY"
    }
  },
}

針對這項要求，報表回應範例如下：

{
  "dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metricHeaders": [{
      "name": "cohortRetentionFraction",
      "type": "TYPE_FLOAT"
    }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.308" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.272" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.257" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.248" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.235" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.211" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.198" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.172" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.167" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.155" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.141" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.118" }]
    }
  ],
  "metadata": {},
  "rowCount": 15
}

根據這份報表回應，以下是這份同類群組報表的圖表。這份報表提供的洞察指出，4 天使用者回訪率在兩週內增加了 10%。2020-11-16 的 firstSessionDate 較高，因此後者留存率高於 2020-11-02 的 firstSessionDate。

多個同類群組留存率的圖表

單週同類群組和搭配其他 API 功能使用同類群組

如要排除使用者行為的每日差異，請使用每週同類群組。在每週的同類群組報表中，所有在同一週有 firstSessionDate 的使用者都會歸入同類群組。一週以星期日開始，星期六結束。在本報表中，我們也將同類群組切片，比較在俄羅斯活動的使用者，以及在墨西哥活動的使用者。這項切片使用 country 維度和 dimensionFilter，只考量兩個國家/地區。

這些同類群組的報表要求如下：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "country",
      "inListFilter": {
        "values": [ "Russia", "Mexico" ]
      }
    }
  },
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": {
          "startDate": "2020-10-04",
          "endDate": "2020-10-10"
        }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "WEEKLY"
    }
  },
}

針對這項要求，報表回應範例如下：

{
  "dimensionHeaders": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "105" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "98" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "35" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "24" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "23" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "17" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "3" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    }
  ],
  "metadata": {},
  "rowCount": 11
}

根據這份報表回應，以下是這份同類群組報表的圖表。根據這份報告，這個房源在留住墨西哥活動使用者的表現，優於留住俄羅斯活動使用者的表現。

國家/地區比較同類群組的圖表

比較項目

您可以使用比較功能來對照評估不同的資料子集。您可以在報表定義中指定 comparisons 欄位，藉此定義比較條件。Data API 的比較功能與 Google Analytics 前端的比較功能類似。

如需各個 API 欄位的詳細說明文件，請參閱比較 REST 參考資料。

建立比較項目

您可以為每個要比較的資料集分別建立比較項目。舉例來說，如要比較應用程式與網站資料，您可以為 Android 和 iOS 資料建立一個比較項目，並為網站資料建立另一個比較項目。

以下是範例報表，其中定義了兩項比較項目，並依國家/地區分類顯示活躍使用者。

第一個名為「應用程式流量」的比較項目使用 inListFilter 比對 platform 維度，其中的值為「iOS」和「Android」。第二個比較項目名為「網路流量」，使用 stringFilter 將 platform 維度與「網路」進行比對。

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
  {
    "comparisons": [
      {
        "name": "App traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "inListFilter": {
              "values": [
                "iOS",
                "Android"
              ]
            }
          }
        }
      },
      {
        "name": "Web traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "stringFilter": {
              "matchType": "EXACT",
              "value": "web"
            }
          }
        }
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ],
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ]
  }

對於使用比較功能的所有要求，系統會自動將 comparison 欄位新增至產生的報表。這個欄位包含要求中提供的對照項目名稱。

以下是包含比較項目的回應程式碼片段範例：

{
  "dimensionHeaders": [
    {
      "name": "comparison"
    },
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "638572"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "Japan"
        }
      ],
      "metricValues": [
        {
          "value": "376578"
        }
      ]
    },
  {
      "dimensionValues": [
        {
          "value": "App traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "79527"
        }
      ]
    },

    ...

  ],

...

}