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

進階用途

本文件將介紹 Google Analytics 的幾項進階功能 Data API v1。如需 API 的詳細參考資料，請參閱 API 參考資料。

列出自訂定義及製作報表

Data API 可針對已註冊的「自訂」維度和自訂指標。中繼資料 API Method 可用來列出 API 資源的已註冊自訂定義名稱。這些 API 名稱可以是用來向 runReport 方法。

以下各節說明每種自訂定義適用的範例。於請將這些範例中的 GA_PROPERTY_ID 換成您的資源 ID。

以事件為範圍的自訂維度

步驟 1：查詢 Metadata API 方法換成您的資源 ID。

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：查詢 Metadata API 方法換成您的資源 ID。

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：查詢 Metadata API 方法換成您的資源 ID。

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：查詢 Metadata API 方法改為資源 ID。

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：查詢 Metadata API 方法換成您的資源 ID。

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 欄位的詳細說明，請參閱 REST 參考資料： CohortSpec。

建立同類群組報表

以下是同類群組報表的範例，其中：

同類群組是指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 天使用者留存率相較於大約 2 週firstSessionDate為 2020-11-16 的後期同類群組早期同類群組的留存率已超越「firstSessionDate」 (共 2020-11-02 個)。

多個同類群組留存率圖表

按週同類群組和將同類群組與其他 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 的「Comparisons」功能類似與 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"
        }
      ]
    },

    ...

  ],

...

}