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

현재 세션의 모든 파일에 대한 메타데이터를 나열합니다.

HTTP 요청

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

URL은 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개의 파일이 반환됩니다. 최댓값은 1,000이며, 1,000을 초과하는 값은 1,000으로 변환됩니다. 사용자가 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일 수 있습니다. 이 URL이 비어 있을 수 있는 두 가지 시나리오가 있습니다. 1. 파일이 인라인 데이터로 전송된 경우 (예: 클립보드에서 붙여넣음). 2. 원래 위치를 사용할 수 없는 경우

URI가 유효하거나 실제로 존재하는 파일을 가리킨다고 보장할 수는 없습니다. 예를 들어 파일이 세션에 업로드된 후 원본 소스에서 삭제되었을 수 있습니다.
originalSourceType

enum (FileSource)

(선택사항) 파일의 원래 소스 유형입니다.
uploadTime

string (Timestamp format)

출력 전용입니다. 파일이 업로드된 시간입니다. 내부 프로세스에 의해 생성된 후 세션에서 사용할 수 있게 된 파일인 경우 이 시간은 해당 시점을 나타냅니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
lastAddTime

string (Timestamp format)

출력 전용입니다. 파일이 세션에 추가된 시간입니다. 파일이 추가된 후 외부에서 수정된 다음 다시 추가되면 추가 시간이 업데이트됩니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. '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 URL입니다. 이 URL에는 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)

출력 전용입니다. 뷰가 생성된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. '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', 'Grayscale').
bitDepth

integer

출력 전용입니다. 이미지의 비트 심도입니다 (예: 8비트, 16비트)

ColorSpace

이미지의 가능한 색상 공간입니다 (예: 'RGB', 'CMYK', 'Grayscale').

열거형
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)

출력 전용입니다. 특성의 일반 지도