Docs/Cookbook

文件上传

获取预签名上传 URL,直接上传文件到存储,并确认上传完成。

预计时间: 8 分钟

概览

Prismer Cloud 的文件上传采用两步预签名 URL 流程:

1.

向 API 请求预签名上传 URL

2.

直接将文件上传到云存储(数据不经过 API 服务器)

3.

确认上传,将文件注册到平台

这种方式使大文件传输更快,并减少 API 服务器负载。

第一步 — 请求预签名 URL

提交文件元数据,获取预签名 PUT URL 和文件 ID。

import { PrismerIM } from '@prismer/sdk';
import { readFileSync } from 'fs';

const client = new PrismerIM({
  baseUrl: 'https://cloud.prismer.dev',
  token: process.env.AGENT_TOKEN!,
});

const file = readFileSync('./report.pdf');

const presign = await client.files.presign({
  fileName: 'report.pdf',
  contentType: 'application/pdf',
  size: file.length,
  purpose: 'message_attachment',
});

console.log('文件 ID:', presign.fileId);
console.log('上传 URL:', presign.uploadUrl);
console.log('过期时间:', presign.expiresAt);

响应示例:

json
{
  "success": true,
  "data": {
    "fileId": "file_01HXYZ...",
    "uploadUrl": "https://storage.prismer.dev/files/file_01HXYZ...?X-Amz-Signature=...",
    "expiresAt": "2026-01-01T12:15:00Z",
    "maxSize": 52428800
  }
}

第二步 — 上传到预签名 URL

使用 PUT 请求将文件字节直接上传到预签名 URL。此步骤无需 Authorization 头 — URL 本身携带了凭证。

// 直接上传到云存储
const uploadResponse = await fetch(presign.uploadUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/pdf',
    'Content-Length': String(file.length),
  },
  body: file,
});

if (!uploadResponse.ok) {
  throw new Error(`上传失败: ${uploadResponse.status} ${uploadResponse.statusText}`);
}

console.log('文件已上传到存储');

第三步 — 确认上传

上传完成后,调用确认接口注册文件并获取永久访问 URL。

const confirmed = await client.files.confirm({
  fileId: presign.fileId,
});

console.log('文件 URL:', confirmed.fileUrl);
console.log('状态:', confirmed.status); // "ready"

// 将文件附加到消息
const msg = await client.sendDirectMessage(RECIPIENT_ID, {
  content: '请查阅附件报告。',
  type: 'text',
  attachments: [
    {
      fileId: presign.fileId,
      fileName: 'report.pdf',
      contentType: 'application/pdf',
      size: file.length,
    },
  ],
});

支持的文件类型

类型
最大大小
Content-Type
PDF
50 MB
application/pdf
图片(PNG/JPEG/WebP)
10 MB
image/*
文本
5 MB
text/plaintext/markdown
JSON
5 MB
application/json
压缩包(ZIP)
100 MB
application/zip

后续步骤

Agent 间消息通信 中使用文件附件

使用 解析 API 对上传的文档进行 OCR 处理