Method: projects.sources.findings.group

Filtra as descobertas de uma organização ou fonte e as agrupa por propriedades especificadas.

Para agrupar todas as fontes, forneça um - como o ID da fonte. Exemplo: /v1/organizations/{organization_id}/sources/-/findings, /v1/folders/{folder_id}/sources/-/findings, /v1/projects/{projectId}/sources/-/findings

Solicitação HTTP


Os URLs usam a sintaxe de Transcodificação gRPC.

Parâmetros de caminho

Parâmetros
parent

string

Obrigatório. Nome da origem a ser usada como groupBy. O formato é organizations/[organization_id]/sources/[source_id], folders/[folder_id]/sources/[source_id] ou projects/[projectId]/sources/[source_id]. Para agrupar por todas as fontes, forneça um source_id de -. Por exemplo: organizations/{organization_id}/sources/-, folders/{folder_id}/sources/- ou projects/{projectId}/sources/-

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "filter": string,
  "groupBy": string,
  "readTime": string,
  "compareDuration": string,
  "pageToken": string,
  "pageSize": integer
}
Campos
filter

string

Expressão que define o filtro a ser aplicado às descobertas. A expressão é uma lista de uma ou mais restrições combinadas pelos operadores lógicos AND e OR. Os parênteses são aceitos, e OR tem precedência maior que AND.

As restrições têm a forma <field> <operator> <value> e podem ter um caractere - na frente para indicar a negação. Por exemplo:

  • nome
  • sourceProperties.a_property
  • securityMarks.marks.marka

Os operadores compatíveis são:

  • = para todos os tipos de valor.
  • >, <, >=, <= para valores inteiros.
  • :, que significa correspondência de substring, para strings.

Os tipos de valor aceitos são:

  • literais de string entre aspas.
  • literais inteiros sem aspas.
  • literais booleanos true e false sem aspas;

As seguintes combinações de campos e operadores são compatíveis:

  • nome: =
  • pai: =, :
  • resourceName: =, :
  • state: =, :
  • categoria: =, :
  • externalUri: =, :
  • eventTime: =, >, <, >=, <=

Uso: milissegundos desde a época ou uma string RFC3339. Exemplos: eventTime = "2019-06-10T16:07:18-07:00" eventTime = 1560208038000

  • gravidade: =, :
  • workflowState: =, :
  • securityMarks.marks: =, :
  • sourceProperties: =, :, >, <, >=, <=

Por exemplo, sourceProperties.size = 100 é uma string de filtro válida.

Use uma correspondência parcial na string vazia para filtrar com base em uma propriedade existente: sourceProperties.my_property : ""

Use uma correspondência parcial negada na string vazia para filtrar com base em uma propriedade que não existe: -sourceProperties.my_property : ""

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

string

Obrigatório. Expressão que define quais campos de recursos usar para agrupamento (incluindo stateChange). O valor da string precisa seguir a sintaxe SQL: lista de campos separados por vírgulas. Por exemplo: "parent,resourceName".

Os seguintes campos são aceitos quando compareDuration é definido:

  • stateChange
readTime
(deprecated)

string (Timestamp format)

Tempo usado como ponto de referência ao filtrar descobertas. O filtro é limitado às descobertas existentes no momento fornecido, e os valores são aqueles no momento específico. A ausência desse campo vai usar a versão da API do NOW.

Usa o RFC 3339, em que a saída gerada é sempre normalizada em Z e usa dígitos fracionários 0, 3, 6 ou 9. Deslocamentos diferentes de "Z" também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
compareDuration
(deprecated)

string (Duration format)

Quando o compareDuration é definido, o atributo "stateChange" do GroupResult é atualizado para indicar se o estado da descoberta mudou, se o estado da descoberta permaneceu o mesmo ou se a descoberta foi adicionada durante o período de compareDuration que precede o readTime. Esse é o tempo entre (readTime - compareDuration) e readTime.

O valor de stateChange é derivado com base na presença e no estado da descoberta nos dois pontos no tempo. As mudanças de estado intermediárias entre os dois momentos não afetam o resultado. Por exemplo, os resultados não são afetados se a descoberta for inativada e ativada novamente.

Valores possíveis de "stateChange" quando compareDuration é especificado:

  • "CHANGED": indica que a descoberta estava presente e correspondia ao filtro fornecido no início de compareDuration, mas mudou de estado em readTime.
  • "UNCHANGED": indica que a descoberta estava presente e correspondia ao filtro fornecido no início de compareDuration e não mudou de estado em readTime.
  • "ADDED": indica que a descoberta não corresponde ao filtro fornecido ou não estava presente no início de compareDuration, mas estava presente em readTime.
  • "REMOVED": indica que a descoberta estava presente e correspondia ao filtro no início de compareDuration, mas não correspondia ao filtro em readTime.

Se compareDuration não for especificado, o único stateChange possível será "UNUSED", que será o stateChange definido para todas as descobertas presentes em readTime.

Se esse campo for definido, stateChange precisará ser um campo especificado em groupBy.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
pageToken

string

O valor retornado pelo último GroupFindingsResponse indica que esta é uma continuação de uma chamada findings.group anterior e que o sistema precisa retornar a próxima página de dados.
pageSize

integer

O número máximo de resultados a serem retornados em uma única resposta. O padrão é 10, o mínimo é 1 e o máximo é 1.000.

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de GroupFindingsResponse.

Escopos de autorização

Requer o seguinte escopo OAuth:

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

Para mais informações, consulte Authentication Overview.