Method: properties.audienceLists.query

擷取使用者的目標對象名單。建立目標對象後，使用者就無法立即取得商店資訊。首先，您必須向 audienceLists.create 要求建立使用者目標對象名單，然後需要使用這個方法來擷取目標對象名單中的使用者。

如需目標對象名單的簡介和範例，請參閱建立目標對象名單一文。

Google Analytics 4 中的目標對像功能可讓您根據自家業務的需求區隔使用者。詳情請參閱：https://support.google.com/analytics/answer/9267572。

此方法適用於 Beta 版穩定性，網址為 audienceExports.query。如要針對這個 API 提供意見回饋，請填寫 Google Analytics Audience Export API 意見回饋表單。

HTTP 要求

POST https://analyticsdata.googleapis.com/v1alpha/{name=properties/*/audienceLists/*}:query

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
name

string

必要欄位。要擷取使用者的目標對象名單名稱。格式：properties/{property}/audienceLists/{audienceList}

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "offset": string,
  "limit": string
}
欄位
offset

string (int64 format)

選用設定。起始資料列的列數。第一列會計為第 0 列。

分頁時，第一個要求不會指定位移；或同等規則，將偏移值設為 0；第一個要求會傳回前 limit 列。第二個要求將偏移值設為第一個要求的 limit；第二個要求會傳回第二列的 limit 列。

如要進一步瞭解這個分頁參數，請參閱「分頁」。
limit

string (int64 format)

選用設定。要傳回的列數。如未指定，系統會傳回 10,000 列。無論您要求多少列，API 在每個要求最多只能傳回 250,000 列。limit必須為正數。

如果維度值數量不如 limit，API 也可以傳回少於要求的 limit 列。

如要進一步瞭解這個分頁參數，請參閱「分頁」。

回應主體

目標對象名單中的使用者名單。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "audienceRows": [
    {
      object (AudienceRow)
    }
  ],
  "audienceList": {
    object (AudienceList)
  },
  "rowCount": integer
}
欄位
audienceRows[]

object (AudienceRow)

目標對象名單中每位使用者的資料列。這個回應中的列數會小於或等於要求的頁面大小。
audienceList

object (AudienceList)

所查詢目標對象名單的設定資料。返回協助解讀這則回覆中的目標對象資料列。舉例來說，此 AudienceList 中的維度會與 AudienceRows 中的資料欄對應。
rowCount

integer

AudienceList 結果中的資料列總數。rowCount 與回應中傳回的資料列數量、limit 要求參數和 offset 要求參數無關。舉例來說，如果查詢傳回 175 列，並在 API 要求中包含 50 列的 limit，回應會包含 175 列的 rowCount，但只有 50 列。

如要進一步瞭解這個分頁參數，請參閱「分頁」。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

AudienceRow

目標對象使用者列的維度值屬性。

JSON 表示法 
{
  "dimensionValues": [
    {
      object (AudienceDimensionValue)
    }
  ]
}
欄位
dimensionValues[]

object (AudienceDimensionValue)

目標對象使用者的每個維度值屬性。每個要求的維度欄都會新增一個維度值。

AudienceDimensionValue

維度的值。

JSON 表示法 
{

  // Union field one_value can be only one of the following:
  "value": string
  // End of list of possible types for union field one_value.
}
欄位
聯集欄位 one_value。其中一種維度值，one_value 只能是下列其中一項：
value

string

如果維度類型是字串，則做為字串的值。