Method: projects.sources.findings.group

过滤组织或来源的发现结果，并按其指定的属性进行分组。

如需跨所有来源进行分组，请将 - 作为来源 ID 提供。示例：/v1/organizations/{organization_id}/sources/-/findings、/v1/folders/{folder_id}/sources/-/findings、/v1/projects/{projectId}/sources/-/findings

HTTP 请求

：


网址使用 gRPC 转码语法。

路径参数

参数
parent

string

必需。要按其进行分组的来源的名称。其格式为 organizations/[organization_id]/sources/[source_id]、folders/[folder_id]/sources/[source_id] 或 projects/[projectId]/sources/[source_id]。如需跨所有来源进行分组，请提供 - 的 source_id。例如：organizations/{organization_id}/sources/-, folders/{folder_id}/sources/- 或 projects/{projectId}/sources/-

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "filter": string,
  "groupBy": string,
  "readTime": string,
  "compareDuration": string,
  "pageToken": string,
  "pageSize": integer
}
字段
filter

string

用于定义要应用于发现结果的过滤条件的表达式。该表达式是通过逻辑运算符 AND 和 OR 组合的一个或多个限制条件的列表。支持括号，并且 OR 的优先级高于 AND。

限制的形式为 <field> <operator> <value>，并且可能在前面带有 - 字符以表示否定。例如：

  • name
  • sourceProperties.a_property
  • securityMarks.marks.marka

支持的运算符包括：

  • =（适用于所有值类型）。
  • >、<、>=、<=，表示整数值。
  • :，表示字符串的子字符串匹配。

支持的值类型包括：

  • 字符串字面量用引号括起来。
  • 不带引号的整数字面量。
  • 不带引号的布尔值字面量 true 和 false。

支持以下字段和运算符组合：

  • 名称：=
  • 父级：=、:
  • resourceName：=、:
  • 状态：=、:
  • 类别：=、:
  • externalUri：=、:
  • eventTime：=、>、<、>=、<=

用法：此值应为从公元纪年起算的毫秒数，或 RFC3339 字符串。示例：eventTime = "2019-06-10T16:07:18-07:00" eventTime = 1560208038000

  • 严重程度：=、:
  • workflowState：=、:
  • securityMarks.marks：=、:
  • sourceProperties：=、:、>、<、>=、<=

例如，sourceProperties.size = 100 是一个有效的过滤器字符串。

对空字符串使用部分匹配，以便根据属性“existing”进行过滤：sourceProperties.my_property : ""

对空字符串使用否定部分匹配，以便根据不存在的属性进行过滤：-sourceProperties.my_property : ""

  • resource:
  • resource.name：=、:
  • resource.parent_name: =、:
  • resource.parent_display_name: =, :
  • resource.project_name：=、:
  • resource.project_display_name：=、:
  • resource.type：=、:
groupBy

string

必需。用于定义要用于分组的素材资源字段（包括 stateChange）的表达式。字符串值应遵循 SQL 语法：逗号分隔的字段列表。例如：“parent,resourceName”。

设置 compareDuration 时，支持以下字段：

  • stateChange
readTime
(deprecated)

string (Timestamp format)

过滤发现结果时用作参考点的时间。此过滤条件仅限于在所提供时间存在的发现结果，其值为该特定时间的值。如果未指定此字段，则默认使用 API 的 NOW 版本。

采用 RFC 3339 标准，生成的输出将始终在末尾带 Z，并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
compareDuration
(deprecated)

string (Duration format)

设置 compareDuration 后，GroupResult 的“stateChange”属性会更新，以指明相应发现的状态是否发生了变化、相应发现的状态是否保持不变，或者相应发现是在 readTime 之前的 compareDuration 时间段内添加的。这是介于 (readTime - compareDuration) 和 readTime 之间的时间。

stateChange 值是根据相应发现结果在这两个时间点的存在性和状态派生得出的。这两次时间点之间的中间状态变化不会影响结果。例如，如果发现结果先设为非活跃状态，然后再设为活跃状态，则结果不会受到影响。

指定 compareDuration 时可能的“stateChange”值：

  • “CHANGED”：表示在 compareDuration 开始时，相应发现存在且与给定过滤条件匹配，但在 readTime 时更改了状态。
  • “UNCHANGED”：表示相应发现在 compareDuration 开始时存在且与给定过滤条件匹配，并且在 readTime 时未更改状态。
  • “ADDED”：表示发现结果与给定过滤条件不匹配，或者在 compareDuration 开始时不存在，但在 readTime 时存在。
  • “已移除”：表示相应发现结果在 compareDuration 开始时存在且与过滤条件匹配，但在 readTime 时不匹配过滤条件。

如果未指定 compareDuration，则唯一可能的 stateChange 是“UNUSED”，系统会将该 stateChange 设置为 readTime 时存在的所有发现。

如果设置此字段，则 stateChange 必须是 groupBy 中的指定字段。

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

string

最后一个 GroupFindingsResponse 返回的值；该参数表示这是之前的 findings.group 调用的延续，并且系统应返回下一页的数据。
pageSize

integer

单个响应中返回的结果数上限。默认值为 10，最小值为 1，最大值为 1000。

响应正文

如果成功，则响应正文包含一个 GroupFindingsResponse 实例。

授权范围

需要以下 OAuth 范围：

  • https://www.googleapis.com/auth/cloud-platform

如需了解详情，请参阅 Authentication Overview。