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。如果使用者指定的值小於或等於 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 標準化，並使用 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 標準化，並使用 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 標準化，並使用 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)

僅供輸出。影片長度。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「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)

僅供輸出。特徵的一般地圖。