Back to Details

fxapi-file-upload

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

文件上传技能

File Upload Skill

fx-api-cli
是提供的命令行程序，所有操作通过执行 
fx-api-cli
命令完成。
通过 
fx-api-cli file <接口名> '<json入参>'
与文件上传系统交互。
fx-api-cli
is the provided command-line program, all operations are completed by executing the 
fx-api-cli
command.
Interact with the file upload system through 
fx-api-cli file <interface name> '<json input parameters>'
.

接口列表

Interface List

app.entry.file.get_upload_token — 获取文件上传凭证和上传地址接口

app.entry.file.get_upload_token — Interface for obtaining file upload credentials and upload address

bash
fx-api-cli file get_upload_token '{"app_id": "app_id_1", "entry_id": "entry_id_1", "transaction_id": "transaction_id_1"}'
获取文件上传凭证和上传地址。每次请求会获取 100 个文件上传凭证和上传地址，上传的文件会与 transaction_id 绑定，只有相同 transaction_id 的创建或修改请求才能使用该文件。参见 API 详情。
bash
fx-api-cli file get_upload_token '{"app_id": "app_id_1", "entry_id": "entry_id_1", "transaction_id": "transaction_id_1"}'
Obtain file upload credentials and upload addresses. Each request will get 100 file upload credentials and upload addresses. The uploaded files will be bound to transaction_id, and only create or modify requests with the same transaction_id can use the file. See API Details.

file.upload — 文件上传接口

file.upload — File Upload Interface

bash
fx-api-cli file upload '{"url": "upload_url", "token": "upload_token", "file": "/path/to/file"}'
上传文件到指定地址。使用获取到的上传地址和凭证，返回文件 key，用于创建和修改接口填写在附件或图片控件值中。参见 API 详情。
bash
fx-api-cli file upload '{"url": "upload_url", "token": "upload_token", "file": "/path/to/file"}'
Upload files to the specified address. Use the obtained upload address and credentials, return the file key, which is used to fill in the value of the attachment or image control in the create and modify interfaces. See API Details.

核心规则

Core Rules

文件上传流程

File Upload Process

  1. 获取上传凭证：调用 
    app.entry.file.get_upload_token
    获取上传地址和凭证
  2. 上传文件：使用获取到的地址和凭证调用 
    file.upload
    上传文件
  3. 获取文件 key：上传成功后获取文件 key，用于后续的创建或修改操作
  1. Obtain upload credentials: Call 
    app.entry.file.get_upload_token
    to get the upload address and credentials
  2. Upload file: Call 
    file.upload
    to upload the file using the obtained address and credentials
  3. Obtain file key: Get the file key after successful upload, which is used for subsequent create or modify operations

事务 ID 规则

Transaction ID Rules

  • 事务 ID：用户自己生成，推荐使用 UUID 格式
  • 有效期：transaction_id 和 token 的有效时间均为 1 小时
  • 格式限制：transaction_id 中不允许包含 ${var}、$(var)、$(var}、${var) 模式的文本
  • Transaction ID: Generated by the user, UUID format is recommended
  • Validity period: The valid time of both transaction_id and token is 1 hour
  • Format restriction: Text in patterns such as ${var}, $(var), $(var}, ${var) are not allowed in transaction_id

文件 key 规则

File Key Rules

  • 文件 key：文件上传后返回的唯一标识符
  • 多个文件：支持一次查询多个文件的上传信息，最多不超过 100 个
  • File key: The unique identifier returned after the file is uploaded
  • Multiple files: Support querying upload information of multiple files at one time, up to 100 files

典型工作流

Typical Workflow

上传文件

Upload File

用户query示例：
  • "帮我上传文件"
  • "上传文件到表单"
执行流程：
  1. 收集用户提供的应用 ID、表单 ID 和文件路径
  2. 生成 transaction_id（UUID 格式）
  3. 调用 
    app.entry.file.get_upload_token
    获取上传地址和凭证
  4. 调用 
    file.upload
    上传文件
  5. 展示上传结果，包括文件 key
  6. 告知用户文件 key 可用于后续的创建或修改操作
User Query Examples:
  • "Help me upload a file"
  • "Upload file to the form"
Execution Process:
  1. Collect the app ID, form ID and file path provided by the user
  2. Generate transaction_id (UUID format)
  3. Call 
    app.entry.file.get_upload_token
    to obtain the upload address and credentials
  4. Call 
    file.upload
    to upload the file
  5. Display the upload result, including the file key
  6. Inform the user that the file key can be used for subsequent create or modify operations

查询文件上传信息

Query File Upload Information

用户query示例：
  • "帮我查询文件上传信息"
  • "查看文件上传状态"
执行流程：
  1. 收集用户提供的文件 key 列表
  2. 调用 
    file.upload_info_list
    获取文件上传信息
  3. 展示每个文件的上传状态、文件大小、文件类型等信息
  4. 若存在上传失败的文件，展示失败原因
User Query Examples:
  • "Help me query file upload information"
  • "Check file upload status"
Execution Process:
  1. Collect the list of file keys provided by the user
  2. Call 
    file.upload_info_list
    to obtain file upload information
  3. Display the upload status, file size, file type and other information of each file
  4. If there are files that failed to upload, display the failure reason

错误处理

Error Handling

  • 事务 ID 格式错误：明确告知用户事务 ID 格式不符合要求
  • 上传凭证过期：告知用户上传凭证已过期，需要重新获取
  • 文件 key 无效：明确告知用户无效的文件 key
  • API错误：展示具体错误信息，必要时重试
  • 网络问题：HTTP错误时主动重试最多3次
  • Transaction ID format error: Clearly inform the user that the transaction ID format does not meet the requirements
  • Upload credential expired: Inform the user that the upload credential has expired and needs to be obtained again
  • Invalid file key: Clearly inform the user of the invalid file key
  • API error: Display specific error information, retry if necessary
  • Network problem: Actively retry up to 3 times when HTTP error occurs