Method: projects.locations.collections.engines.sessions.files.list

Lista os metadados de todos os ficheiros na sessão atual.

Pedido HTTP

GET https://discoveryengine.googleapis.com/v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*}/files

O URL usa a sintaxe de transcodificação de gRPC.

Parâmetros de caminho

Parâmetros
parent

string

Obrigatório. O nome do recurso da sessão. Formato: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session} nome do recurso de sessão ao qual o ficheiro pertence.

Parâmetros de consulta

Parâmetros
filter

string

Opcional. A sintaxe do filtro consiste numa linguagem de expressão para criar um predicado a partir de um ou mais campos dos ficheiros que estão a ser filtrados. A expressão de filtro é sensível a maiúsculas e minúsculas.

Os nomes de campos atualmente suportados são:

  • upload_time
  • last_add_time
  • last_use_time
  • file_name
  • mime_type

Alguns exemplos de filtros:

  • "file_name = 'file_1'"
  • "file_name = 'file_1' AND mime_type = 'text/plain'"
  • "last_use_time > '2025-06-14T12:00:00Z'"

Para uma descrição completa do formato do filtro, consulte https://google.aip.dev/160.
pageSize

integer

Opcional. O número máximo de ficheiros a devolver. O serviço pode devolver um número inferior a este valor. Se não for especificado, são devolvidos, no máximo, 100 ficheiros. O valor máximo é 1000. Os valores superiores a 1000 são convertidos para 1000. Se o utilizador especificar um valor igual ou inferior a 0, o pedido é rejeitado com um erro INVALID_ARGUMENT.
pageToken

string

Opcional. Um token de página recebido de uma chamada files.list anterior. Faculte este valor para obter a página seguinte.

Ao paginar, todos os outros parâmetros fornecidos a files.list têm de corresponder à chamada que forneceu o token de página (exceto pageSize, que pode ser diferente).
orderBy

string

Opcional. Especifica a ordem pela qual os ficheiros são devolvidos.

O valor é uma string separada por vírgulas de campos pelos quais ordenar.

Para a ordem ascendente, apenas é usado o nome do campo. Para a ordem descendente, o nome do campo tem o sufixo desc. A ordenação é estável e aplicada sequencialmente de acordo com a ordem dos campos fornecidos na string.

Campos suportados para a ordenação:

  • upload_time: a hora em que o ficheiro foi carregado.
  • file_name: o nome do ficheiro.
  • mime_type: o tipo MIME do ficheiro.
  • session_name: o nome da sessão à qual o ficheiro pertence.

Comportamento predefinido:

Se o campo orderBy não for especificado, os ficheiros são devolvidos ordenados por hora de criação por ordem descendente.

Exemplos:

  1. Ordenar por nome do ficheiro por ordem ascendente: file_name

  2. Ordenar por hora de carregamento por ordem descendente: upload_time desc

  3. Ordene por nome do ficheiro (por ordem ascendente), depois por tipo de conteúdo (tipo MIME) (por ordem descendente) e, finalmente, por hora de carregamento (por ordem ascendente): file_name, mime_type desc, upload_time

Corpo do pedido

O corpo do pedido tem de estar vazio.

Corpo da resposta

Mensagem de resposta para o método SessionService.ListFiles.

Se for bem-sucedido, o corpo da resposta contém dados com a seguinte estrutura:

Representação JSON 
{
  "files": [
    {
      object (FileMetadata)
    }
  ],
  "nextPageToken": string
}
Campos
files[]

object (FileMetadata)

Os anos FileMetadata.
nextPageToken

string

Um token para obter a página seguinte de resultados. Transmita este valor no campo ListFilesRequest.page_token na chamada subsequente ao método files.list para obter a página seguinte de resultados.

Âmbitos de autorização

Requer um dos seguintes âmbitos do OAuth:

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

Para mais informações, consulte o Authentication Overview.

Autorizações de IAM

Requer a seguinte autorização de IAM no recurso parent:

  • discoveryengine.sessions.listSessionFileMetadata

Para mais informações, consulte a documentação do IAM.

FileMetadata

Representa um ficheiro anexado a uma sessão (ficheiro de contexto)

Representação JSON 
{
  "fileId": string,
  "name": string,
  "mimeType": string,
  "byteSize": string,
  "originalUri": string,
  "originalSourceType": enum (FileSource),
  "uploadTime": string,
  "lastAddTime": string,
  "metadata": {
    string: string,
    ...
  },
  "downloadUri": string,
  "fileOriginType": enum (FileOriginType),
  "views": {
    string: {
      object (FileView)
    },
    ...
  }
}
Campos
fileId

string

Apenas saída. O ID do ficheiro.
name

string

Apenas saída. O nome do ficheiro carregado.
mimeType

string

O tipo de conteúdo do ficheiro. Consulte https://www.iana.org/assignments/media-types/media-types.xhtml.
byteSize

string (int64 format)

Apenas saída. O tamanho do ficheiro de contexto em bytes.
originalUri

string

Opcional. A localização original do ficheiro. Pode ser um caminho de ficheiro local ou qualquer outro URI que permita aceder ao ficheiro num sistema externo. Existem dois cenários em que este URL pode estar vazio: 1. Se o ficheiro foi enviado como dados inline (por exemplo, colado a partir da área de transferência). 2. Se a localização original não estiver disponível.

Tenha em atenção que não existem garantias de que o URI esteja a apontar para um ficheiro válido ou realmente existente. Por exemplo, um ficheiro pode ter sido carregado para a sessão e, em seguida, eliminado da origem original.
originalSourceType

enum (FileSource)

Opcional. O tipo de fonte original do ficheiro.
uploadTime

string (Timestamp format)

Apenas saída. A hora em que o ficheiro foi carregado (se for um ficheiro gerado por um processo interno e, em seguida, disponibilizado à sessão, isto indica o momento em que ocorreu).

Usa RFC 3339, em que o resultado gerado é sempre normalizado em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Também são aceites desvios diferentes de "Z". Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
lastAddTime

string (Timestamp format)

Apenas saída. A hora em que o ficheiro foi adicionado à sessão. Tenha em atenção que, se um ficheiro for adicionado, modificado externamente e, em seguida, adicionado novamente, a hora de adição é atualizada.

Usa RFC 3339, em que o resultado gerado é sempre normalizado em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Também são aceites desvios diferentes de "Z". Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
metadata

map (key: string, value: string)

Opcional. Representa metadados relacionados com o ficheiro que podem adequar-se a exemplos de utilização específicos. O prefixo "google." está reservado para a chave para utilização pela Google, mas outros prefixos podem ser utilizados livremente.
downloadUri

string

Apenas saída. O AssistantService.DownloadSessionFile URL para transferir o ficheiro. Este URL precisa das mesmas credenciais que o método AssistantService.ListSessionFileMetadata e fornece o recurso.
fileOriginType

enum (FileOriginType)

Opcional. A origem do ficheiro.
views

map (key: string, value: object (FileView))

Apenas saída. Vistas alternativas deste objeto de ficheiro. Cada visualização de ficheiro está associada a uma função específica. Exemplos de chaves possíveis: - "thumbnail" - "mobile_thumbnail" - "clip" - "summary" - "translation"

FileOriginType

A origem do ficheiro.

Enumerações
FILE_ORIGIN_TYPE_UNSPECIFIED Valor predefinido.
USER_PROVIDED O ficheiro foi fornecido pelo utilizador.
AI_GENERATED O ficheiro foi gerado por um modelo de IA.
INTERNALLY_GENERATED O ficheiro foi gerado a partir de outros ficheiros por um processo interno.

FileView

Representa uma versão ou uma "vista" alternativa específica de um objeto de ficheiro, como um resumo, uma miniatura, uma versão traduzida, etc.

Representação JSON 
{
  "viewId": string,
  "uri": string,
  "mimeType": string,
  "byteSize": string,
  "createTime": string,

  // Union field characteristics can be only one of the following:
  "imageCharacteristics": {
    object (ImageCharacteristics)
  },
  "videoCharacteristics": {
    object (VideoCharacteristics)
  },
  "fileCharacteristics": {
    object (FileCharacteristics)
  }
  // End of list of possible types for union field characteristics.
}
Campos
viewId

string

Apenas saída. ID global exclusivo desta vista específica.
uri

string

Apenas saída. O URI para aceder a esta visualização de conteúdo multimédia.
mimeType

string

Apenas saída. Tipo MIME (por exemplo, "image/jpeg", "image/png", "text/plain", "video/mp4")
byteSize

string (int64 format)

Apenas saída. O tamanho da vista em bytes.
createTime

string (Timestamp format)

Apenas saída. A hora em que a visualização foi criada.

Usa RFC 3339, em que o resultado gerado é sempre normalizado em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Também são aceites desvios diferentes de "Z". Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
Campo de união characteristics. Caraterísticas da vista de multimédia, que permitem extensões flexíveis. Os metadados são sempre gerados internamente pelo processo que cria a vista. characteristics só pode ser uma das seguintes opções:
imageCharacteristics

object (ImageCharacteristics)

Apenas saída. Caraterísticas de uma vista de multimédia de imagem.
videoCharacteristics

object (VideoCharacteristics)

Apenas saída. Características de uma visualização de conteúdo multimédia de vídeo.
fileCharacteristics

object (FileCharacteristics)

Apenas saída. Caraterísticas de outros tipos de ficheiros.

ImageCharacteristics

Caraterísticas padrão de uma visualização de conteúdo multimédia de imagem.

Representação JSON 
{
  "width": integer,
  "height": integer,
  "colorSpace": enum (ColorSpace),
  "bitDepth": integer
}
Campos
width

integer

Apenas saída. Largura da imagem em píxeis.
height

integer

Apenas saída. Altura da imagem em píxeis.
colorSpace

enum (ColorSpace)

Apenas saída. Espaço da cor da imagem (por exemplo, "RGB", "CMYK", "Grayscale").
bitDepth

integer

Apenas saída. Profundidade de bits da imagem (por exemplo, 8 bits, 16 bits).

ColorSpace

Possíveis espaços de cores de uma imagem (por exemplo, "RGB", "CMYK", "Grayscale").

Enumerações
COLOR_SPACE_UNSPECIFIED Valor predefinido. Espaço de cores desconhecido.
RGB Espaço de cores vermelho, verde e azul.
CMYK Espaço de cores ciano, magenta, amarelo e preto.
GRAYSCALE Espaço da cor em escala de cinzentos.
YUV Espaço de cores YUV.
OTHER_COLOR_SPACE Outro espaço de cores.

VideoCharacteristics

Características padrão de uma visualização de conteúdo multimédia de vídeo.

Representação JSON 
{
  "width": integer,
  "height": integer,
  "duration": string,
  "frameRate": number,
  "audioCodecs": [
    string
  ],
  "videoCodecs": [
    string
  ],
  "videoBitrateKbps": integer,
  "audioBitrateKbps": integer
}
Campos
width

integer

Apenas saída. Largura do vídeo em píxeis.
height

integer

Apenas saída. Altura do vídeo em píxeis.
duration

string (Duration format)

Apenas saída. Duração do vídeo.

Uma duração em segundos com até nove dígitos fracionários, que termina com "s". Exemplo: "3.5s".
frameRate

number

Apenas saída. Velocidade de frames (frames por segundo).
audioCodecs[]

string

Apenas saída. Codecs de áudio usados no vídeo.
videoCodecs[]

string

Apenas saída. Codecs de vídeo usados no vídeo.
videoBitrateKbps

integer

Apenas saída. Taxa de bits do vídeo em kbps.
audioBitrateKbps

integer

Apenas saída. Taxa de bits do áudio em kbps.

FileCharacteristics

Características de outros tipos de ficheiros.

Representação JSON 
{
  "characteristics": {
    string: string,
    ...
  }
}
Campos
characteristics

map (key: string, value: string)

Apenas saída. Mapa genérico de caraterísticas.