REST Resource: properties.audiences

資源:Audience

代表 GA4 目標對象的資源訊息。

JSON 表示法
{
  "name": string,
  "displayName": string,
  "description": string,
  "membershipDurationDays": integer,
  "adsPersonalizationEnabled": boolean,
  "eventTrigger": {
    object (AudienceEventTrigger)
  },
  "exclusionDurationMode": enum (AudienceExclusionDurationMode),
  "filterClauses": [
    {
      object (AudienceFilterClause)
    }
  ]
}
欄位
name

string

僅供輸出。這項目標對象資源的資源名稱。格式:Properties/{propertyId}/audiences/{audienceId}

displayName

string

必要欄位。目標對象的顯示名稱。

description

string

必要欄位。目標對象的說明。

membershipDurationDays

integer

必要欄位。無法變更。使用者留在目標對像中的時間長度。不得設為超過 540 天。

adsPersonalizationEnabled

boolean

僅供輸出。如果是非個人化廣告目標對象,且被排除在廣告個人化之外,Google Analytics (分析) 會自動將這個欄位設為 false。

eventTrigger

object (AudienceEventTrigger)

選用設定。指定使用者加入目標對象時要記錄的事件。如果未設定,系統就不會在使用者加入目標對象時記錄任何事件。

exclusionDurationMode

enum (AudienceExclusionDurationMode)

無法變更。為符合排除篩選器的使用者指定排除條件的效期。系統會對所有 EXCLUDE 篩選器子句套用這項條件,一旦目標對像中沒有 EXCLUDE 篩選器子句,系統就會予以忽略。

filterClauses[]

object (AudienceFilterClause)

必要欄位。無法變更。未排序的清單。用來定義目標對象的篩選器子句。所有子句都會以 AND 結合在一起。

AudienceEventTrigger

指定使用者加入目標對象時要記錄的事件。

JSON 表示法
{
  "eventName": string,
  "logCondition": enum (LogCondition)
}
欄位
eventName

string

必要欄位。要記錄的事件名稱。

logCondition

enum (LogCondition)

必要欄位。記錄事件的時機。

LogCondition

決定記錄事件的時機。

列舉
LOG_CONDITION_UNSPECIFIED 未指定記錄條件。
AUDIENCE_JOINED 只有在使用者加入後才能記錄這個事件。
AUDIENCE_MEMBERSHIP_RENEWED 只要符合目標對象條件,系統就應該記錄這個事件,即使使用者已是目標對象成員也一樣。

AudienceExclusionDurationMode

為符合排除篩選器的使用者指定排除條件的效期。

列舉
AUDIENCE_EXCLUSION_DURATION_MODE_UNSPECIFIED 未指定。
EXCLUDE_TEMPORARILY 將符合篩選器子句的使用者從目標對像中排除。
EXCLUDE_PERMANENTLY 將曾符合篩選器子句的使用者從目標對像中排除。

AudienceFilterClause

用來定義簡單或序列篩選器的子句。篩選器可包含 (例如,符合篩選器子句的使用者將納入「目標對象」) 或排除 (舉例來說,系統會將符合篩選器子句的使用者從目標對像中排除)。

JSON 表示法
{
  "clauseType": enum (AudienceClauseType),

  // Union field filter can be only one of the following:
  "simpleFilter": {
    object (AudienceSimpleFilter)
  },
  "sequenceFilter": {
    object (AudienceSequenceFilter)
  }
  // End of list of possible types for union field filter.
}
欄位
clauseType

enum (AudienceClauseType)

必要欄位。指明這是「包含」或「排除」篩選器子句。

聯集欄位 filter

filter 只能採用下列其中一種設定:

simpleFilter

object (AudienceSimpleFilter)

使用者必須符合簡易篩選器,才能成為該目標對象的成員。

sequenceFilter

object (AudienceSequenceFilter)

使用者必須按照特定順序套用篩選器,使用者才會成為目標對象名單的成員。

AudienceSimpleFilter

定義一個簡單的篩選器,使用者必須滿足這些條件才能成為目標對象的成員。

JSON 表示法
{
  "scope": enum (AudienceFilterScope),
  "filterExpression": {
    object (AudienceFilterExpression)
  }
}
欄位
scope

enum (AudienceFilterScope)

必要欄位。無法變更。指定這個篩選器的範圍。

filterExpression

object (AudienceFilterExpression)

必要欄位。無法變更。「目標對象」維度、指標或事件篩選器的邏輯運算式。

AudienceFilterScope

指定如何評估加入目標對象的使用者。

列舉
AUDIENCE_FILTER_SCOPE_UNSPECIFIED 未指定範圍。
AUDIENCE_FILTER_SCOPE_WITHIN_SAME_EVENT 只要一個事件中符合篩選條件,使用者就會加入目標對象。
AUDIENCE_FILTER_SCOPE_WITHIN_SAME_SESSION 如果在一個工作階段內符合篩選條件,使用者就會加入目標對象。
AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS 在任何工作階段中,任何事件都符合篩選條件時,使用者才會加入目標對象。

AudienceFilterExpression

「目標對象」維度、指標或事件篩選器的邏輯運算式。

JSON 表示法
{

  // Union field expr can be only one of the following:
  "andGroup": {
    object (AudienceFilterExpressionList)
  },
  "orGroup": {
    object (AudienceFilterExpressionList)
  },
  "notExpression": {
    object (AudienceFilterExpression)
  },
  "dimensionOrMetricFilter": {
    object (AudienceDimensionOrMetricFilter)
  },
  "eventFilter": {
    object (AudienceEventFilter)
  }
  // End of list of possible types for union field expr.
}
欄位
聯集欄位 expr。套用至篩選器的運算式。expr 只能是下列其中一項:
andGroup

object (AudienceFilterExpressionList)

要合併 AND 的運算式清單。只能包含設有 orGroup 的 AudienceFilterExpressions。必須為頂層 AudienceFilterExpression 設定這個值。

orGroup

object (AudienceFilterExpressionList)

要用 OR 結合的運算式清單。且不得包含帶有 andGroup 或 orGroup 的 AudienceFilterExpressions。

notExpression

object (AudienceFilterExpression)

要「不用」的篩選器運算式 (例如反轉或互補)。只能包含維度或指標篩選器。無法在頂層 AudienceFilterExpression 上設定這個運算式。

dimensionOrMetricFilter

object (AudienceDimensionOrMetricFilter)

單一維度或指標的篩選器。無法在頂層 AudienceFilterExpression 上設定這個運算式。

eventFilter

object (AudienceEventFilter)

建立與特定事件相符的篩選器。無法在頂層 AudienceFilterExpression 上設定這個運算式。

AudienceFilterExpressionList

目標對象篩選運算式清單。

JSON 表示法
{
  "filterExpressions": [
    {
      object (AudienceFilterExpression)
    }
  ]
}
欄位
filterExpressions[]

object (AudienceFilterExpression)

目標對象篩選運算式清單。

AudienceDimensionOrMetricFilter

單一維度或指標的專用篩選器。

JSON 表示法
{
  "fieldName": string,
  "atAnyPointInTime": boolean,
  "inAnyNDayPeriod": integer,

  // Union field one_filter can be only one of the following:
  "stringFilter": {
    object (StringFilter)
  },
  "inListFilter": {
    object (InListFilter)
  },
  "numericFilter": {
    object (NumericFilter)
  },
  "betweenFilter": {
    object (BetweenFilter)
  }
  // End of list of possible types for union field one_filter.
}
欄位
fieldName

string

必要欄位。無法變更。要篩選的維度名稱或指標名稱。如果欄位名稱參照自訂維度或指標,範圍前置字元會加到自訂維度或指標名稱的前面。如要進一步瞭解範圍前置字元或自訂維度/指標,請參閱 Google Analytics (分析) Data API 說明文件

atAnyPointInTime

boolean

選用設定。指出這個篩選器是否需要動態評估。如果設為 True,只要使用者符合條件,就會加入目標對象 (靜態評估)。如果未設定或設為 False,目標對象的使用者評估功能會動態進行;當使用者符合條件時,系統就會將他們加入目標對像中,不再符合條件時就會移除。

只有在目標對象範圍為 ACROSS_ALL_SESSIONS 時,才能設定此屬性。

inAnyNDayPeriod

integer

選用設定。設定後,指定要評估資料的時間範圍 (以天數為單位)。如未設定,系統會使用生命週期資料 (例如無限時間範圍) 評估目標對象資料。

舉例來說,如果設為 1 天,系統只會評估當天的資料。參照點是 atAnyPointInTime 未設定或 false 的當天。

只有目標對象範圍是 ACROSS_ALL_SESSIONS 且不得超過 60 天時才能設定目標對象。

聯集欄位 one_filter。其中一個篩選器。one_filter 只能是下列其中一項:
stringFilter

object (StringFilter)

符合特定模式的字串類型維度的篩選器。

inListFilter

object (InListFilter)

符合特定選項清單的字串維度篩選器。

numericFilter

object (NumericFilter)

維度或指標中的數字或日期值篩選器。

betweenFilter

object (BetweenFilter)

這個篩選器可篩選出維度或指標中特定值的數字或日期值。

StringFilter

符合特定模式的字串類型維度的篩選器。

JSON 表示法
{
  "matchType": enum (MatchType),
  "value": string,
  "caseSensitive": boolean
}
欄位
matchType

enum (MatchType)

必要欄位。字串篩選器的比對類型。

value

string

必要欄位。要比對的字串值。

caseSensitive

boolean

選用設定。如為 true,比對會區分大小寫。如為 false,比對時不區分大小寫。

MatchType

字串篩選器的比對類型。

列舉
MATCH_TYPE_UNSPECIFIED 未指定
EXACT 字串值完全比對。
BEGINS_WITH 開頭為字串值。
ENDS_WITH 此結尾為字串值。
CONTAINS 包含字串值。
FULL_REGEXP 完整規則運算式與字串值相符。

InListFilter

符合特定選項清單的字串維度篩選器。

JSON 表示法
{
  "values": [
    string
  ],
  "caseSensitive": boolean
}
欄位
values[]

string

必要欄位。要比對的可能字串值清單。不得空白。

caseSensitive

boolean

選用設定。如為 true,比對會區分大小寫。如為 false,比對時不區分大小寫。

NumericFilter

維度或指標中的數字或日期值篩選器。

JSON 表示法
{
  "operation": enum (Operation),
  "value": {
    object (NumericValue)
  }
}
欄位
operation

enum (Operation)

必要欄位。套用至數字篩選器的作業。

value

object (NumericValue)

必要欄位。要比對的數值或日期值。

作業

套用至數字篩選器的作業。

列舉
OPERATION_UNSPECIFIED 未指明
EQUAL 等於。
LESS_THAN 小於。
GREATER_THAN 大於。

NumericValue

表示數字。

JSON 表示法
{

  // Union field one_value can be only one of the following:
  "int64Value": string,
  "doubleValue": number
  // End of list of possible types for union field one_value.
}
欄位
聯集欄位 one_value。其中一個數值。one_value 只能是下列其中一項:
int64Value

string (int64 format)

整數值。

doubleValue

number

雙精度浮點值。

BetweenFilter

這個篩選器可篩選出維度或指標中特定值的數字或日期值。

JSON 表示法
{
  "fromValue": {
    object (NumericValue)
  },
  "toValue": {
    object (NumericValue)
  }
}
欄位
fromValue

object (NumericValue)

必要欄位。以此數字開頭 (含此數字)。

toValue

object (NumericValue)

必要欄位。以此數字結尾 (含此數字)。

AudienceEventFilter

用來比對單一事件名稱事件的篩選器。如果指定事件參數,則只有符合單一事件名稱和參數篩選運算式的事件子集相符。

JSON 表示法
{
  "eventName": string,
  "eventParameterFilterExpression": {
    object (AudienceFilterExpression)
  }
}
欄位
eventName

string

必要欄位。無法變更。要比對的事件名稱。

eventParameterFilterExpression

object (AudienceFilterExpression)

選用設定。如果指定,這個篩選器會比對同時符合單一事件名稱和參數篩選運算式的事件。無法設定參數篩選運算式中的 AudienceEventFilter (例如不支援巢狀事件篩選器)。請使用維度 OrMetricFilter 或 notExpression 的單一和群組;不支援 OR 的 AND。此外,如果篩選器包含「eventCount」的篩選器,系統只會將其中一個列入考量,並忽略所有其他篩選器。

AudienceSequenceFilter

定義使用者必須按照特定順序執行,才能成為目標對象的成員。

JSON 表示法
{
  "scope": enum (AudienceFilterScope),
  "sequenceMaximumDuration": string,
  "sequenceSteps": [
    {
      object (AudienceSequenceStep)
    }
  ]
}
欄位
scope

enum (AudienceFilterScope)

必要欄位。無法變更。指定這個篩選器的範圍。

sequenceMaximumDuration

string (Duration format)

選用設定。定義整個序列必須發生的時間範圍。

持續時間以秒為單位,最多 9 個小數位數,結尾為「s」,例如:"3.5s"

sequenceSteps[]

object (AudienceSequenceStep)

必要欄位。已排序的步驟序列。使用者必須完成每個步驟,才能加入序列篩選器。

AudienceSequenceStep

這個條件必須在指定步驟順序中發生,才能讓這位使用者比對序列。

JSON 表示法
{
  "scope": enum (AudienceFilterScope),
  "immediatelyFollows": boolean,
  "constraintDuration": string,
  "filterExpression": {
    object (AudienceFilterExpression)
  }
}
欄位
scope

enum (AudienceFilterScope)

必要欄位。無法變更。指定這個步驟的範圍。

immediatelyFollows

boolean

選用設定。如果為 true,則完成這個步驟的事件必須是事件達成最後一個步驟後的下一個事件。如未設定或設為 False,這個步驟會間接遵循上一個步驟;舉例來說,上一個步驟與這個步驟之間可能會出現事件。第一個步驟會忽略此屬性。

constraintDuration

string (Duration format)

選用設定。設定之後,這個步驟必須在前一個步驟的 constraintDuration 內滿足 (例如 t[i] - t[i-1] <= constraintDuration)。如未設定,表示沒有時間長度限制 (有效期間沒有時間長度限制)。第一個步驟會忽略此屬性。

持續時間以秒為單位,最多 9 個小數位數,結尾為「s」,例如:"3.5s"

filterExpression

object (AudienceFilterExpression)

必要欄位。無法變更。每個步驟包含「目標對象維度」、「指標」或「事件篩選器」的邏輯運算式。

AudienceClauseType

指明這是「包含」或「排除」篩選器子句。

列舉
AUDIENCE_CLAUSE_TYPE_UNSPECIFIED 未指定的子句類型。
INCLUDE 如果符合篩選器子句,使用者就會納入目標對象。
EXCLUDE 如果符合篩選器子句,使用者就會從目標對像中排除。

方法

archive

封存資源中的目標對象。

create

建立目標對象。

get

查詢單一目標對象。

list

列出資源中的目標對象。

patch

更新資源中的目標對象。