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

列出当前会话中所有文件的元数据。

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数
parent

string

必需。会话的资源名称。格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session} 文件所属会话资源的名称。

查询参数

参数
filter

string

可选。过滤器语法使用一种表达式语言，可根据要过滤文件的一个或多个字段构建过滤条件。过滤表达式区分大小写。

目前支持的字段名称包括：

  • upload_time
  • last_add_time
  • last_use_time
  • file_name
  • mime_type

以下是一些过滤条件示例：

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

如需详细了解过滤条件格式，请参阅 https://google.aip.dev/160。
pageSize

integer

可选。要返回的文件数量上限。服务返回的值可能小于此值。如果未指定，则最多返回 100 个文件。最大值为 1000；大于 1000 的值会强制转换为 1000。如果用户指定的值小于或等于 0，系统会拒绝相应请求，并返回 INVALID_ARGUMENT 错误。
pageToken

string

可选。从之前的 files.list 调用接收的页面令牌。利用其进行后续页面检索。

进行分页时，提供给 files.list 的所有其他参数必须与提供页面令牌的调用匹配（pageSize 除外，该参数可能会有所不同）。
orderBy

string

可选。指定返回文件的顺序。

该值是以英文逗号分隔的要排序的字段字符串。

对于升序，只需使用字段名称。对于降序，字段名称的后缀为 desc。排序是稳定的，并且会根据字符串中提供的字段顺序依次应用。

支持排序的字段：

  • upload_time：文件上传时间。
  • file_name：文件的名称。
  • mime_type：文件的 MIME 类型。
  • session_name：相应文件所属会话的名称。

默认行为：

如果未指定 orderBy 字段，系统将按创建时间降序返回文件。

示例：

  1. 按文件名升序排序：file_name

  2. 按上传时间降序排序：upload_time desc

  3. 按文件名（升序）、内容类型 (MIME 类型)（降序）和上传时间（升序）排序：file_name, mime_type desc, upload_time

请求正文

请求正文必须为空。

响应正文

SessionService.ListFiles 方法的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "files": [
    {
      object (FileMetadata)
    }
  ],
  "nextPageToken": string
}
字段
files[]

object (FileMetadata)

FileMetadata。
nextPageToken

string

用于检索下一页结果的令牌。在后续对 files.list 方法的调用中，将此值传入 ListFilesRequest.page_token 字段，以检索下一页结果。

授权范围

需要以下 OAuth 范围之一：

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

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

IAM 权限

需要拥有 parent 资源的以下 IAM 权限：

  • discoveryengine.sessions.listSessionFileMetadata

如需了解详情，请参阅 IAM 文档。

FileMetadata 类中的方法

表示附加到会话的文件（上下文文件）

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)
    },
    ...
  }
}
字段
fileId

string

仅限输出。文件的 ID。
name

string

仅限输出。已上传文件的名称。
mimeType

string

文件的内容类型，请参阅 https://www.iana.org/assignments/media-types/media-types.xhtml。
byteSize

string (int64 format)

仅限输出。上下文文件的大小（以字节为单位）。
originalUri

string

可选。文件的原始位置。它可以是本地文件路径，也可以是允许访问外部系统中文件的任何其他 URI。在以下两种情况下，此网址可能为空：1. 如果文件是以内嵌数据的形式发送的（例如从剪贴板粘贴）。2. 如果原始位置不可用。

请注意，无法保证 URI 会指向有效或实际存在的文件。例如，某个文件可能已上传到会话，然后从原始来源中删除。
originalSourceType

enum (FileSource)

可选。文件的原始来源的类型。
uploadTime

string (Timestamp format)

仅限输出。文件上传时间（如果文件是由内部进程生成，然后提供给会话，则表示生成时间）。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
lastAddTime

string (Timestamp format)

仅限输出。文件添加到会话的时间。请注意，如果某个文件先被添加，然后在外部被修改，之后又被重新添加，那么添加时间将会更新。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"
metadata

map (key: string, value: string)

可选。表示与文件相关的元数据，可满足特定使用情形。前缀“google.”已预留给 Google 使用，但其他前缀可以随意使用。
downloadUri

string

仅限输出。用于下载文件的 AssistantService.DownloadSessionFile 网址。此网址将需要与 AssistantService.ListSessionFileMetadata 方法相同的凭据，并提供资源。
fileOriginType

enum (FileOriginType)

可选。文件的来源。
views

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

仅限输出。相应文件对象的替代视图。每个文件视图都与特定角色相关联。可能的示例键： - "thumbnail" - "mobile_thumbnail" - "clip" - "summary" - "translation"

FileOriginType

文件的来源。

枚举
FILE_ORIGIN_TYPE_UNSPECIFIED 默认值。
USER_PROVIDED 文件由用户提供。
AI_GENERATED 该文件是由 AI 模型生成的。
INTERNALLY_GENERATED 该文件是通过内部流程从其他文件生成的。

FileView

表示文件对象的特定替代版本或“视图”，例如摘要、缩略图、翻译版本等。

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.
}
字段
viewId

string

仅限输出。相应特定视图的全局唯一 ID。
uri

string

仅限输出。用于访问相应媒体视图的 URI。
mimeType

string

仅限输出。MIME 类型（例如，"image/jpeg"、"image/png"、"text/plain"、"video/mp4")
byteSize

string (int64 format)

仅限输出。视图的大小（以字节为单位）。
createTime

string (Timestamp format)

仅限输出。视图的创建时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
联合字段 characteristics。媒体视图的特征，可实现灵活的扩展。元数据始终由创建视图的进程在内部生成。characteristics 只能是下列其中一项：
imageCharacteristics

object (ImageCharacteristics)

仅限输出。图片媒体视图的特征。
videoCharacteristics

object (VideoCharacteristics)

仅限输出。视频媒体观看的特征。
fileCharacteristics

object (FileCharacteristics)

仅限输出。其他文件类型的特征。

ImageCharacteristics

图片媒体视图的标准特征。

JSON 表示法 
{
  "width": integer,
  "height": integer,
  "colorSpace": enum (ColorSpace),
  "bitDepth": integer
}
字段
width

integer

仅限输出。图片宽度（以像素为单位）。
height

integer

仅限输出。图片高度（以像素为单位）。
colorSpace

enum (ColorSpace)

仅限输出。图片的颜色空间（例如，“RGB”“CMYK”“灰度模式”）。
bitDepth

integer

仅限输出。图片的位深（例如 8 位、16 位）。

ColorSpace

图片的可能色彩空间（例如 “RGB”“CMYK”“灰度模式”）。

枚举
COLOR_SPACE_UNSPECIFIED 默认值。未知颜色空间。
RGB 红色、绿色、蓝色色彩空间。
CMYK 青色、品红色、黄色和黑色色彩空间。
GRAYSCALE 灰度模式色彩空间。
YUV YUV 色彩空间。
OTHER_COLOR_SPACE 其他色彩空间。

VideoCharacteristics

视频媒体观看的标准特征。

JSON 表示法 
{
  "width": integer,
  "height": integer,
  "duration": string,
  "frameRate": number,
  "audioCodecs": [
    string
  ],
  "videoCodecs": [
    string
  ],
  "videoBitrateKbps": integer,
  "audioBitrateKbps": integer
}
字段
width

integer

仅限输出。视频宽度（以像素为单位）。
height

integer

仅限输出。视频高度（以像素为单位）。
duration

string (Duration format)

仅限输出。视频时长。

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

number

仅限输出。帧速率（每秒帧数）。
audioCodecs[]

string

仅限输出。视频中使用的音频编解码器。
videoCodecs[]

string

仅限输出。视频中使用的视频编解码器。
videoBitrateKbps

integer

仅限输出。视频的比特率（以 kbps 为单位）。
audioBitrateKbps

integer

仅限输出。音频的比特率（以 kbps 为单位）。

FileCharacteristics

其他文件类型的特征。

JSON 表示法 
{
  "characteristics": {
    string: string,
    ...
  }
}
字段
characteristics

map (key: string, value: string)

仅限输出。特征的一般地图。