tamar-file-hub-client 0.1.7__py3-none-any.whl → 0.2.4__py3-none-any.whl

file_hub_client/rpc/protos/file_service.proto

@@ -28,6 +28,12 @@ service FileService {
     rpc GetCompressedVariants (GetVariantsRequest) returns (GetVariantsResponse);
     rpc TriggerRecompression (RecompressionRequest) returns (RecompressionResponse);
     rpc GenerateVariantDownloadUrl (VariantDownloadUrlRequest) returns (VariantDownloadUrlResponse);
+    
+    // 批量文件状态查询API
+    rpc BatchGetFileStatus (BatchFileStatusRequest) returns (BatchFileStatusResponse);
+
+    // 从GCS导入文件
+    rpc ImportFromGcs (ImportFromGcsRequest) returns (ImportFromGcsResponse);
 }
 
 // ========= 数据结构定义 =========
@@ -80,6 +86,7 @@ message UploadUrlRequest {
     optional bool is_temporary = 7;
     optional int32 expire_seconds = 8;
     optional bool keep_original_filename = 9;  // 保留原始文件名，默认false
+    optional bool forbid_overwrite = 10;  // 防止覆盖同名文件，默认false
 }
 
 message UploadCompletedRequest {
@@ -145,6 +152,16 @@ message BatchGetGcsUrlRequest {
     repeated string file_ids = 1;
 }
 
+message ImportFromGcsRequest {
+    string gcs_uri = 1;                          // GCS URI, e.g., gs://bucket/path/to/file
+    optional string folder_id = 2;               // 目标文件夹ID
+    string operation_type = 3;                   // "copy" or "move"
+    optional string file_name = 4;               // 自定义文件名（可选）
+    optional bool keep_original_filename = 5;    // 保留原始文件名，默认false
+    optional string created_by_role = 6;         // 创建者角色
+    optional string created_by = 7;              // 创建者ID
+}
+
 // ========= 响应结构 =========
 
 message UploadFileResponse {
@@ -195,6 +212,11 @@ message BatchGetGcsUrlResponse {
     repeated GcsUrlInfo gcs_urls = 1;
 }
 
+message ImportFromGcsResponse {
+    File file = 1;                               // 创建的文件信息
+    UploadFile upload_file = 2;                  // 上传文件信息
+}
+
 message GcsUrlInfo {
     string file_id = 1;
     string gcs_url = 2;
@@ -262,4 +284,83 @@ message VariantDownloadUrlResponse {
     optional CompressedVariant variant_info = 3;  // 返回变体详细信息
 }
 
+// ========= 批量文件状态查询相关结构 =========
+
+message BatchFileStatusRequest {
+    repeated string file_ids = 1;           // 批量查询的文件ID列表（最多100个）
+    optional bool include_details = 2;      // 是否返回详细信息，默认false
+}
+
+message BatchFileStatusResponse {
+    repeated FileStatusInfo statuses = 1;   // 文件状态信息（FileStatusInfo.file_id关联请求的file_id）
+    int64 timestamp = 2;                    // 查询时间戳
+    int32 cache_hit_count = 3;             // 缓存命中数量（用于性能监控）
+}
+
+message FileStatusInfo {
+    string file_id = 1;
+    
+    // 三大状态
+    FileUploadStatus upload_status = 2;      // 上传状态
+    FileCompressionStatus compression_status = 3; // 压缩状态  
+    FileSyncStatus sync_status = 4;          // 备份同步状态
+    
+    // 扩展信息（当include_details=true时返回）
+    optional FileStatusDetails details = 5;
+    
+    // 错误信息
+    optional string error_message = 6;
+}
+
+message FileStatusDetails {
+    // 上传详情
+    optional int64 file_size = 1;
+    optional string storage_type = 2;       // gcs, oss
+    optional string storage_region = 3;
+    
+    // 压缩详情  
+    optional string compression_task_id = 4;
+    optional int32 compression_variants_count = 5;
+    optional double compression_progress = 6; // 0.0-1.0
+    
+    // 同步详情
+    optional int32 sync_regions_total = 7;
+    optional int32 sync_regions_completed = 8;
+    repeated string sync_pending_regions = 9;
+}
+
+// 文件上传状态枚举
+enum FileUploadStatus {
+    UPLOAD_UNKNOWN = 0;
+    UPLOAD_PENDING = 1;           // 待上传
+    UPLOAD_PROCESSING = 2;        // 上传中
+    UPLOAD_COMPLETED = 3;         // 已完成
+    UPLOAD_FAILED = 4;           // 失败
+    UPLOAD_FILE_NOT_FOUND = 5;   // 文件不存在
+}
+
+// 文件压缩状态枚举
+enum FileCompressionStatus {
+    COMPRESSION_UNKNOWN = 0;
+    COMPRESSION_NOT_APPLICABLE = 1;  // 不需要压缩
+    COMPRESSION_PENDING = 2;         // 等待压缩
+    COMPRESSION_PROCESSING = 3;      // 压缩中
+    COMPRESSION_COMPLETED = 4;       // 已完成
+    COMPRESSION_FAILED = 5;          // 失败
+    COMPRESSION_SKIPPED = 6;         // 跳过压缩
+    COMPRESSION_FILE_NOT_FOUND = 7;  // 文件不存在
+}
+
+// 文件同步状态枚举
+enum FileSyncStatus {
+    SYNC_UNKNOWN = 0;
+    SYNC_NOT_REQUIRED = 1;          // 不需要同步
+    SYNC_PENDING = 2;               // 等待同步
+    SYNC_PROCESSING = 3;            // 同步中
+    SYNC_PARTIAL = 4;               // 部分完成
+    SYNC_COMPLETED = 5;             // 全部完成
+    SYNC_FAILED = 6;                // 同步失败
+    SYNC_FILE_NOT_FOUND = 7;        // 文件不存在
+}
+
 message Empty {}

file_hub_client/schemas/__init__.py

@@ -21,6 +21,15 @@ from .file import (
     GetVariantsResponse,
     RecompressionResponse,
     VariantDownloadUrlResponse,
+    # 文件状态相关
+    FileUploadStatus,
+    FileCompressionStatus,
+    FileSyncStatus,
+    FileStatusDetails,
+    FileStatusInfo,
+    BatchFileStatusResponse,
+    # GCS 导入
+    ImportFromGcsResponse,
 )
 from .folder import (
     FolderInfo,
@@ -83,6 +92,14 @@ __all__ = [
     "GetVariantsResponse",
     "RecompressionResponse",
     "VariantDownloadUrlResponse",
+    # 文件状态相关
+    "FileUploadStatus",
+    "FileCompressionStatus",
+    "FileSyncStatus",
+    "FileStatusDetails",
+    "FileStatusInfo",
+    "BatchFileStatusResponse",
+    "ImportFromGcsResponse",
 
     # 文件夹相关
     "FolderInfo",

file_hub_client/schemas/file.py

@@ -4,6 +4,7 @@
 from datetime import datetime
 from typing import Optional, Dict, List, Any
 from pydantic import BaseModel, Field
+from enum import Enum
 
 
 class File(BaseModel):
@@ -169,3 +170,75 @@ class VariantDownloadUrlResponse(BaseModel):
     url: str = Field(..., description="下载URL")
     error: Optional[str] = Field(None, description="错误信息")
     variant_info: Optional[CompressedVariant] = Field(None, description="变体详细信息")
+
+
+# ========= 文件状态服务相关模型 =========
+
+class FileUploadStatus(str, Enum):
+    """文件上传状态枚举"""
+    UPLOAD_UNKNOWN = "UPLOAD_UNKNOWN"
+    UPLOAD_PENDING = "UPLOAD_PENDING"
+    UPLOAD_PROCESSING = "UPLOAD_PROCESSING"
+    UPLOAD_COMPLETED = "UPLOAD_COMPLETED"
+    UPLOAD_FAILED = "UPLOAD_FAILED"
+    UPLOAD_FILE_NOT_FOUND = "UPLOAD_FILE_NOT_FOUND"
+
+
+class FileCompressionStatus(str, Enum):
+    """文件压缩状态枚举"""
+    COMPRESSION_UNKNOWN = "COMPRESSION_UNKNOWN"
+    COMPRESSION_NOT_APPLICABLE = "COMPRESSION_NOT_APPLICABLE"
+    COMPRESSION_PENDING = "COMPRESSION_PENDING"
+    COMPRESSION_PROCESSING = "COMPRESSION_PROCESSING"
+    COMPRESSION_COMPLETED = "COMPRESSION_COMPLETED"
+    COMPRESSION_FAILED = "COMPRESSION_FAILED"
+    COMPRESSION_SKIPPED = "COMPRESSION_SKIPPED"
+    COMPRESSION_FILE_NOT_FOUND = "COMPRESSION_FILE_NOT_FOUND"
+
+
+class FileSyncStatus(str, Enum):
+    """文件同步状态枚举"""
+    SYNC_UNKNOWN = "SYNC_UNKNOWN"
+    SYNC_NOT_REQUIRED = "SYNC_NOT_REQUIRED"
+    SYNC_PENDING = "SYNC_PENDING"
+    SYNC_PROCESSING = "SYNC_PROCESSING"
+    SYNC_PARTIAL = "SYNC_PARTIAL"
+    SYNC_COMPLETED = "SYNC_COMPLETED"
+    SYNC_FAILED = "SYNC_FAILED"
+    SYNC_FILE_NOT_FOUND = "SYNC_FILE_NOT_FOUND"
+
+
+class FileStatusDetails(BaseModel):
+    """文件状态详情"""
+    file_size: Optional[int] = Field(None, description="文件大小")
+    storage_type: Optional[str] = Field(None, description="存储类型")
+    storage_region: Optional[str] = Field(None, description="存储区域")
+    compression_task_id: Optional[str] = Field(None, description="压缩任务ID")
+    compression_variants_count: Optional[int] = Field(None, description="压缩变体数量")
+    compression_progress: Optional[float] = Field(None, description="压缩进度")
+    sync_regions_total: Optional[int] = Field(None, description="同步区域总数")
+    sync_regions_completed: Optional[int] = Field(None, description="已完成同步区域数")
+    sync_pending_regions: List[str] = Field(default_factory=list, description="待同步区域列表")
+
+
+class FileStatusInfo(BaseModel):
+    """文件状态信息"""
+    file_id: str = Field(..., description="文件ID")
+    upload_status: FileUploadStatus = Field(..., description="上传状态")
+    compression_status: FileCompressionStatus = Field(..., description="压缩状态")
+    sync_status: FileSyncStatus = Field(..., description="同步状态")
+    details: Optional[FileStatusDetails] = Field(None, description="状态详情")
+    error_message: Optional[str] = Field(None, description="错误信息")
+
+
+class BatchFileStatusResponse(BaseModel):
+    """批量文件状态响应"""
+    statuses: List[FileStatusInfo] = Field(default_factory=list, description="文件状态列表")
+    timestamp: int = Field(..., description="查询时间戳")
+    cache_hit_count: int = Field(..., description="缓存命中数量（用于性能监控）")
+
+
+class ImportFromGcsResponse(BaseModel):
+    """从GCS导入文件响应"""
+    file: File = Field(..., description="创建的文件信息")
+    upload_file: UploadFile = Field(..., description="上传文件信息")

file_hub_client/services/file/async_blob_service.py

@@ -11,7 +11,7 @@ from .base_file_service import BaseFileService
 from ...enums import UploadMode
 from ...errors import ValidationError
 from ...rpc import AsyncGrpcClient
-from ...schemas import FileUploadResponse, UploadUrlResponse, BatchDownloadUrlResponse, DownloadUrlInfo, GcsUrlInfo, GetGcsUrlResponse, BatchGcsUrlResponse, CompressionStatusResponse, GetVariantsResponse, RecompressionResponse, VariantDownloadUrlResponse, CompressedVariant
+from ...schemas import FileUploadResponse, UploadUrlResponse, BatchDownloadUrlResponse, DownloadUrlInfo, GcsUrlInfo, GetGcsUrlResponse, BatchGcsUrlResponse, CompressionStatusResponse, GetVariantsResponse, RecompressionResponse, VariantDownloadUrlResponse, CompressedVariant, BatchFileStatusResponse, FileStatusInfo, FileStatusDetails, FileUploadStatus, FileCompressionStatus, FileSyncStatus
 from ...utils import AsyncHttpUploader, AsyncHttpDownloader, retry_with_backoff, get_file_mime_type
 
 
@@ -118,6 +118,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary: Optional[bool] = False,
             expire_seconds: Optional[int] = None,
             keep_original_filename: Optional[bool] = False,
+            forbid_overwrite: Optional[bool] = True,
             request_id: Optional[str] = None,
             **metadata
     ) -> FileUploadResponse:
@@ -134,6 +135,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary=is_temporary,
             expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
             keep_original_filename=keep_original_filename,
+            forbid_overwrite=forbid_overwrite,
             request_id=request_id,
             **metadata
         )
@@ -151,12 +153,13 @@ class AsyncBlobService(BaseFileService):
             "Cache-Control": "public, max-age=86400"  # 24小时公共缓存
         }
 
-        # 上传文件到对象存储
+        # 上传文件到对象存储，传递forbid_overwrite参数
         await self.http_uploader.upload(
             url=upload_url_resp.upload_url,
             content=content,
             headers=headers,
             total_size=file_size,
+            forbid_overwrite=forbid_overwrite,
         )
 
         # 确认上传完成
@@ -184,6 +187,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary: Optional[bool] = False,
             expire_seconds: Optional[int] = None,
             keep_original_filename: Optional[bool] = False,
+            forbid_overwrite: Optional[bool] = False,
             request_id: Optional[str] = None,
             **metadata
     ) -> FileUploadResponse:
@@ -200,6 +204,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary=is_temporary,
             expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
             keep_original_filename=keep_original_filename,
+            forbid_overwrite=forbid_overwrite,
             request_id=request_id,
             **metadata
         )
@@ -224,12 +229,13 @@ class AsyncBlobService(BaseFileService):
             mime_type=mime_type,
         )
 
-        # 上传文件到对象存储
+        # 上传文件到对象存储，传递forbid_overwrite参数
         await self.http_uploader.upload(
             url=upload_url,
             content=content,
             headers=headers,
             total_size=file_size,
+            forbid_overwrite=forbid_overwrite,
         )
 
         # 确认上传完成
@@ -277,6 +283,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary: Optional[bool] = False,
             expire_seconds: Optional[int] = None,
             keep_original_filename: Optional[bool] = False,
+            forbid_overwrite: Optional[bool] = False,
             request_id: Optional[str] = None,
             **metadata
     ) -> UploadUrlResponse:
@@ -293,6 +300,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary: 是否为临时文件
             expire_seconds: 过期秒数
             keep_original_filename: 是否保留原始文件名（默认False）
+            forbid_overwrite: 防止覆盖同名文件（默认False）
             request_id: 请求ID（可选，如果不提供则自动生成）
             **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
 
@@ -312,6 +320,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary=is_temporary,
             expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
             keep_original_filename=keep_original_filename,
+            forbid_overwrite=forbid_overwrite,
         )
 
         if folder_id:
@@ -339,6 +348,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary: Optional[bool] = False,
             expire_seconds: Optional[int] = None,
             keep_original_filename: Optional[bool] = False,
+            forbid_overwrite: Optional[bool] = True,
             request_id: Optional[str] = None,
             **metadata
     ) -> UploadUrlResponse:
@@ -355,6 +365,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary: 是否为临时文件
             expire_seconds: 过期秒数
             keep_original_filename: 是否保留原始文件名（默认False）
+            forbid_overwrite: 防止覆盖同名文件（默认False）
             request_id: 请求ID（可选，如果不提供则自动生成）
             **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
 
@@ -376,6 +387,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary=is_temporary,
             expire_seconds=expire_seconds if is_temporary and expire_seconds else None,
             keep_original_filename=keep_original_filename,
+            forbid_overwrite=forbid_overwrite,
         )
 
         if folder_id:
@@ -401,6 +413,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary: Optional[bool] = False,
             expire_seconds: Optional[int] = None,
             keep_original_filename: Optional[bool] = False,
+            forbid_overwrite: Optional[bool] = True,
             url: Optional[str] = None,
             file_name: Optional[str] = None,
             mime_type: Optional[str] = None,
@@ -417,6 +430,7 @@ class AsyncBlobService(BaseFileService):
             is_temporary: 是否为临时文件
             expire_seconds: 过期秒数
             keep_original_filename: 是否保留原始文件名（默认False）
+            forbid_overwrite: 防止覆盖同名文件（默认False）
             url: 要下载并上传的URL（可选）
             file_name: 当使用url参数时指定的文件名（可选）
             mime_type: MIME类型（可选，用于推断文件扩展名，特别适用于AI生成的字节数据）
@@ -511,8 +525,16 @@ class AsyncBlobService(BaseFileService):
             hundred_mb = 1024 * 1024 * 100
             if file_size >= ten_mb and file_size < hundred_mb:  # 10MB
                 mode = UploadMode.STREAM  # 大文件自动使用流式上传模式
+            # 暂时屏蔽 RESUMABLE 模式，因为OSS断点续传尚未完成开发
+            # elif file_size > hundred_mb:
+            #     mode = UploadMode.RESUMABLE  # 特大文件自动使用断点续传模式
             elif file_size > hundred_mb:
-                mode = UploadMode.RESUMABLE  # 特大文件自动使用断点续传模式
+                mode = UploadMode.STREAM  # 暂时使用流式上传代替断点续传
+
+        # OSS断点续传尚未完成，将RESUMABLE模式自动转为STREAM模式
+        if mode == UploadMode.RESUMABLE:
+            mode = UploadMode.STREAM
+            # TODO: 当OSS断点续传功能完成后，移除此转换逻辑
 
         # 根据上传模式执行不同的上传逻辑
         if mode == UploadMode.NORMAL:
@@ -543,6 +565,7 @@ class AsyncBlobService(BaseFileService):
                 is_temporary=is_temporary,
                 expire_seconds=expire_seconds,
                 keep_original_filename=keep_original_filename,
+                forbid_overwrite=forbid_overwrite,
                 request_id=request_id,
                 **metadata
             )
@@ -560,6 +583,7 @@ class AsyncBlobService(BaseFileService):
                 is_temporary=is_temporary,
                 expire_seconds=expire_seconds,
                 keep_original_filename=keep_original_filename,
+                forbid_overwrite=forbid_overwrite,
                 request_id=request_id,
                 **metadata
             )
@@ -995,3 +1019,115 @@ class AsyncBlobService(BaseFileService):
             error=response.error if response.error else None,
             variant_info=variant_info
         )
+
+    async def batch_get_file_status(
+        self,
+        file_ids: List[str],
+        *,
+        include_details: Optional[bool] = False,
+        request_id: Optional[str] = None,
+        **metadata
+    ) -> BatchFileStatusResponse:
+        """
+        批量获取文件状态（异步版本）
+        
+        Args:
+            file_ids: 文件ID列表（最多100个）
+            include_details: 是否包含详细状态信息（默认False）
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            BatchFileStatusResponse: 批量文件状态响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.BatchFileStatusRequest(
+            file_ids=file_ids,
+            include_details=include_details if include_details is not None else False
+        )
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.BatchGetFileStatus(request, metadata=grpc_metadata)
+        
+        # 转换文件状态信息
+        statuses = []
+        for status_info in response.statuses:
+            # 转换状态详情（如果存在）
+            details = None
+            if status_info.HasField('details'):
+                details = FileStatusDetails(
+                    file_size=status_info.details.file_size if status_info.details.HasField('file_size') else None,
+                    storage_type=status_info.details.storage_type if status_info.details.HasField('storage_type') else None,
+                    storage_region=status_info.details.storage_region if status_info.details.HasField('storage_region') else None,
+                    compression_task_id=status_info.details.compression_task_id if status_info.details.HasField('compression_task_id') else None,
+                    compression_variants_count=status_info.details.compression_variants_count if status_info.details.HasField('compression_variants_count') else None,
+                    compression_progress=status_info.details.compression_progress if status_info.details.HasField('compression_progress') else None,
+                    sync_regions_total=status_info.details.sync_regions_total if status_info.details.HasField('sync_regions_total') else None,
+                    sync_regions_completed=status_info.details.sync_regions_completed if status_info.details.HasField('sync_regions_completed') else None,
+                    sync_pending_regions=list(status_info.details.sync_pending_regions)
+                )
+            
+            # 转换枚举值
+            upload_status = self._convert_upload_status(status_info.upload_status)
+            compression_status = self._convert_compression_status(status_info.compression_status)
+            sync_status = self._convert_sync_status(status_info.sync_status)
+            
+            statuses.append(FileStatusInfo(
+                file_id=status_info.file_id,
+                upload_status=upload_status,
+                compression_status=compression_status,
+                sync_status=sync_status,
+                details=details,
+                error_message=status_info.error_message if status_info.HasField('error_message') else None
+            ))
+        
+        return BatchFileStatusResponse(
+            statuses=statuses,
+            timestamp=response.timestamp,
+            cache_hit_count=response.cache_hit_count
+        )
+
+    def _convert_upload_status(self, proto_status: int) -> FileUploadStatus:
+        """转换上传状态枚举"""
+        status_map = {
+            0: FileUploadStatus.UPLOAD_UNKNOWN,
+            1: FileUploadStatus.UPLOAD_PENDING,
+            2: FileUploadStatus.UPLOAD_PROCESSING,
+            3: FileUploadStatus.UPLOAD_COMPLETED,
+            4: FileUploadStatus.UPLOAD_FAILED,
+            5: FileUploadStatus.UPLOAD_FILE_NOT_FOUND,
+        }
+        return status_map.get(proto_status, FileUploadStatus.UPLOAD_UNKNOWN)
+
+    def _convert_compression_status(self, proto_status: int) -> FileCompressionStatus:
+        """转换压缩状态枚举"""
+        status_map = {
+            0: FileCompressionStatus.COMPRESSION_UNKNOWN,
+            1: FileCompressionStatus.COMPRESSION_NOT_APPLICABLE,
+            2: FileCompressionStatus.COMPRESSION_PENDING,
+            3: FileCompressionStatus.COMPRESSION_PROCESSING,
+            4: FileCompressionStatus.COMPRESSION_COMPLETED,
+            5: FileCompressionStatus.COMPRESSION_FAILED,
+            6: FileCompressionStatus.COMPRESSION_SKIPPED,
+            7: FileCompressionStatus.COMPRESSION_FILE_NOT_FOUND,
+        }
+        return status_map.get(proto_status, FileCompressionStatus.COMPRESSION_UNKNOWN)
+
+    def _convert_sync_status(self, proto_status: int) -> FileSyncStatus:
+        """转换同步状态枚举"""
+        status_map = {
+            0: FileSyncStatus.SYNC_UNKNOWN,
+            1: FileSyncStatus.SYNC_NOT_REQUIRED,
+            2: FileSyncStatus.SYNC_PENDING,
+            3: FileSyncStatus.SYNC_PROCESSING,
+            4: FileSyncStatus.SYNC_PARTIAL,
+            5: FileSyncStatus.SYNC_COMPLETED,
+            6: FileSyncStatus.SYNC_FAILED,
+            7: FileSyncStatus.SYNC_FILE_NOT_FOUND,
+        }
+        return status_map.get(proto_status, FileSyncStatus.SYNC_UNKNOWN)

file_hub_client/services/file/async_file_service.py

@@ -492,3 +492,69 @@ class AsyncFileService(BaseFileService):
             error=response.error if response.error else None,
             variant_info=variant_info
         )
+
+    async def import_from_gcs(
+            self,
+            gcs_uri: str,
+            operation_type: str,
+            *,
+            folder_id: Optional[str] = None,
+            file_name: Optional[str] = None,
+            keep_original_filename: bool = False,
+            created_by_role: Optional[str] = None,
+            created_by: Optional[str] = None,
+            request_id: Optional[str] = None,
+            **metadata
+    ) -> 'ImportFromGcsResponse':
+        """
+        从GCS导入文件
+        
+        Args:
+            gcs_uri: GCS URI, 例如 gs://bucket/path/to/file
+            operation_type: 操作类型，"copy" 或 "move"
+            folder_id: 目标文件夹ID（可选）
+            file_name: 自定义文件名（可选）
+            keep_original_filename: 保留原始文件名，默认False
+            created_by_role: 创建者角色（可选）
+            created_by: 创建者ID（可选）
+            request_id: 请求ID，用于追踪
+            **metadata: 额外的gRPC元数据
+            
+        Returns:
+            ImportFromGcsResponse: 导入响应，包含文件信息和上传文件信息
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        from ...schemas import ImportFromGcsResponse
+        
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+        
+        request = file_service_pb2.ImportFromGcsRequest(
+            gcs_uri=gcs_uri,
+            operation_type=operation_type,
+            keep_original_filename=keep_original_filename
+        )
+        
+        if folder_id:
+            request.folder_id = folder_id
+        if file_name:
+            request.file_name = file_name
+        if created_by_role:
+            request.created_by_role = created_by_role
+        if created_by:
+            request.created_by = created_by
+        
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(request_id=request_id, **metadata)
+        
+        response = await stub.ImportFromGcs(request, metadata=grpc_metadata)
+        
+        # 转换文件信息
+        file_info = self._convert_file_info(response.file)
+        
+        # 转换上传文件信息
+        upload_file_info = self._convert_upload_file_info(response.upload_file)
+        
+        return ImportFromGcsResponse(
+            file=file_info,
+            upload_file=upload_file_info
+        )