REST Resource: properties.audiences

资源:受众群体

表示 GA4 受众群体的资源消息。

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

string

仅限输出。此受众群体资源的资源名称。格式:property/{propertyId}/audiences/{audienceId}

displayName

string

必需。受众群体的显示名称。

description

string

必需。对受众群体的说明。

membershipDurationDays

integer

必需。不可变。用户在受众群体中应保留的时长。并且不能超过 540 天。

adsPersonalizationEnabled

boolean

仅限输出。如果是非个性化广告 (NPA) 受众群体,且不受广告个性化的影响,则 Google Analytics 会自动将该值设为 false。

eventTrigger

object (AudienceEventTrigger)

可选。指定在用户加入受众群体时要记录的事件。如果未设置,则当用户加入受众群体时,系统不会记录任何事件。

exclusionDurationMode

enum (AudienceExclusionDurationMode)

不可变。针对符合排除过滤条件的用户,指定排除项的有效期。它会应用于所有 EXCLUDE 过滤条件子句,并会在受众群体中没有 EXCLUDE 过滤条件子句时忽略。

filterClauses[]

object (AudienceFilterClause)

必需。不可变。无序列表。用于定义受众群体的过滤子句。所有子句都将以 AND 关系结合在一起。

createTime

string (Timestamp format)

仅限输出。受众群体的创建时间。

时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

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 的 AudienceFilter 表达式。必须为顶级 AudienceFilter 表达式设置此表达式。

orGroup

object (AudienceFilterExpressionList)

通过 OR 连接在一起的表达式列表。它不能包含 AudienceFilter 表达式与 andGroup 或 orGroup。

notExpression

object (AudienceFilterExpression)

要进行 NOT 运算(例如反转、补码)的过滤器表达式。它只能包含自定义维度 OrMetricFilter。无法在顶级 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(例如,不支持嵌套事件过滤条件)。这应该是一个 andGroup 包含 dimensionOrMetricFilter 或 not 表达式;不支持 OR 的 AND。此外,如果包含“eventCount”的过滤条件,则系统只会考虑该过滤条件;所有其他过滤条件都会被忽略

AudienceSequenceFilter

定义过滤器必须按特定顺序执行,用户才能成为受众群体成员。

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

enum (AudienceFilterScope)

必需。不可变。指定此过滤器的范围。

sequenceMaximumDuration

string (Duration format)

可选。指定整个序列必须在多长时间内完成。

该时长以秒为单位,最多包含九个小数位,以“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)内满足。如果未设置,则没有时长要求(实际上时长没有限制)。系统在第一步中会忽略此属性。

该时长以秒为单位,最多包含九个小数位,以“s”结尾。示例:"3.5s"

filterExpression

object (AudienceFilterExpression)

必需。不可变。每个步骤中“受众群体”维度、指标或事件过滤条件的逻辑表达式。

AudienceClauseType

指定这是包含过滤器子句还是排除过滤器子句。

枚举
AUDIENCE_CLAUSE_TYPE_UNSPECIFIED 未指定的子句类型。
INCLUDE 如果满足过滤条件子句,则用户会被添加到受众群体中。
EXCLUDE 如果满足过滤条件子句,则系统会从受众群体中排除用户。

方法

archive

将媒体资源的受众群体归档。

create

创建受众群体。

get

查找单个受众群体。

list

列出媒体资源上的受众群体。

patch

更新媒体资源的受众群体。