managing-file-storage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing File Storage

管理文件存储

Celigo Storage is file storage built into integrator.io: files and folders an account keeps next to its integrations, with no S3 bucket or SFTP host of its own. Four kinds of consumer share it:

Flows read and write storage folders through file steps on a Celigo APIs connection
MCP servers publish a stored file as a read-only resource
Trading partners log in to the Celigo-hosted SFTP file server; each partner account is rooted in a storage folder
People upload, download, and organize files

Two add-ons sit on top: Storage Query runs one read-only SQL

SELECT

over stored files (references/storage-query.md), and the file server gives partners SFTP logins into storage folders (references/file-server.md).

Celigo Storage 是内置于 integrator.io 的文件存储：账户会在其 integration 旁保留文件和文件夹，本身不提供 S3 bucket 或 SFTP host。四类使用者共享该存储：

Flows 通过 Celigo APIs connection 上的 file step 读写 storage folder
MCP servers 将存储的 file 发布为 read-only resource
交易伙伴登录 Celigo 托管的 SFTP file server；每个 partner account 都以某个 storage folder 为根目录
人员上传、下载和整理文件

在此基础上还有两个附加功能：Storage Query 对存储文件运行一条只读 SQL

SELECT

（references/storage-query.md），file server 则允许合作伙伴通过 SFTP 登录 storage folder（references/file-server.md）。

How to Run the Steps

如何运行各个步骤

This skill names each step by what it reads or changes; the exact calls depend on how you reach the account. Read the one reference that matches your tools -- both follow the step numbers of How to Manage Stored Files below:

Celigo MCP tools (

list_storage_items

upsert_storage_item

restore_storage_item

get_storage_file_download_url

cancel_storage_upload

delete_resource

) -- references/mcp.md

The
celigo
CLI (

celigo storage

celigo recycle-bin

celigo file-server

) -- references/cli.md

Storage Query and the file server have no MCP tools: use the CLI or the REST API.

Listing, searching, reading metadata, downloading, reading the quota, and running a Storage Query only read. Uploading, replacing content, creating folders, renaming, moving, copying, merging, deleting, restoring, and purging write to the account. A purge can't be undone, and neither can a content replace once it finalizes.

此 skill 按每个步骤读取或更改的对象来命名；具体调用取决于访问账户的方式。请阅读与所用工具匹配的参考文档——两者都遵循下文“How to Manage Stored Files”的步骤编号：

Celigo MCP tools（

list_storage_items

、

upsert_storage_item

、

restore_storage_item

、

get_storage_file_download_url

、

cancel_storage_upload

、

delete_resource

）——references/mcp.md

celigo
CLI（

celigo storage

、

celigo recycle-bin

、

celigo file-server

）——references/cli.md

Storage Query 和 file server 没有 MCP tools：请使用 CLI 或 REST API。

列出、搜索、读取 metadata、下载、读取 quota 和运行 Storage Query 都属于只读操作。上传、替换 content、创建 folder、重命名、移动、复制、合并、删除、恢复和永久清除会向账户写入数据。Purge 无法撤销；content replace 在完成后同样无法撤销。

The Storage Model

存储模型

Items are addressed by id, not by path

Item 通过 id 寻址，而不是 path

Every file and folder has an

_id

; files and folders share one id space. Everything that points at storage pins that id: a flow step's folder, an MCP server's

resources[]._fileId

, a partner account's

_homeFolderId

Rename, move, and content replace keep the
_id
, so references keep working. A restore from the recycle bin keeps it too.
Copy creates a new
_id
. So does deleting a file and uploading a new one with the same name: old references don't follow it. To change a referenced file, replace its content.
Names are unique among the live items of one folder -- files and folders share the namespace, matching is case-sensitive, and a pending upload already holds its name. A duplicate is refused with 409
```
STORAGE_ITEM_ALREADY_EXISTS
```
. A deleted item releases its name.
Paths are names. A path such as
```
/Order to cash/inbound/orders.csv
```
is built from folder names. Storage Query, path-scoped API tokens, and the
```
custom
```
scope of a Celigo APIs connection match paths, so renaming or moving a folder changes what those paths reach.

每个文件和文件夹都有一个

_id

；文件和文件夹共享同一个 id space。所有指向 storage 的引用都会固定该 id：flow step 的 folder、MCP server 的

resources[]._fileId

、partner account 的

_homeFolderId

。

重命名、移动和替换 content 会保留
_id
，因此引用仍然有效。从 recycle bin 恢复时也会保留该 id。
复制会创建新的
_id
。删除文件后以相同名称重新上传也一样：旧引用不会指向新文件。要更改被引用的文件，请替换其 content。
同一 folder 中未删除的 item 之间名称唯一——文件和文件夹共享 namespace，匹配区分大小写，并且 pending upload 已经占用其名称。重复名称会返回 409
```
STORAGE_ITEM_ALREADY_EXISTS
```
。删除 item 后，其名称即可重新使用。
Path 就是名称。
```
/Order to cash/inbound/orders.csv
```
之类的 path 由 folder 名称构成。Storage Query、限定 path 范围的 API token，以及 Celigo APIs connection 的
```
custom
```
scope 都按 path 匹配，因此重命名或移动 folder 会改变这些 path 所指向的位置。

Integration (system) folders

Integration（系统）文件夹

Creating an integration creates a folder at the storage root named after it, with

isSystem: true

, the integration's

_integrationId

, and

integrationName

The folder itself is protected. Renaming, moving, copying, deleting or purging it is refused with 403
```
STORAGE_SYSTEM_ITEM_PROTECTED
```
("System items cannot be modified or deleted").
Everything inside it is ordinary. Folders and files created in it carry its
```
_integrationId
```
; moving an item in or out sets or clears it.
It follows the integration. Deleting the integration sends the folder and everything in it to the recycle bin, and purging the integration from the bin purges the folder too. Before deleting an integration, move out any files that must outlive it.

创建 integration 会在 storage root 下创建一个以该 integration 命名的 folder，其中包含

isSystem: true

、integration 的

_integrationId

和

integrationName

。

该 folder 本身受保护。 重命名、移动、复制、删除或永久清除它都会返回 403
```
STORAGE_SYSTEM_ITEM_PROTECTED
```
（"System items cannot be modified or deleted"）。
其中的所有内容都是普通 item。 在其中创建的 folder 和 file 会携带该
```
_integrationId
```
；将 item 移入或移出则会设置或清除该值。
它会随 integration 一起处理。 删除 integration 会将其 folder 及全部内容送入 recycle bin；从 bin 中永久清除 integration 时，也会永久清除该 folder。删除 integration 前，请将需要在 integration 结束后继续保留的文件移出。

Content, environment, and quota

Content、environment 和 quota

Stored files belong to the environment they were created in, and nothing crosses environments (getting-started > Sandbox vs Production). The quota is one figure for the whole account:

Field	Meaning
`activeUsage`	Bytes of active and pending files
`recycleBinUsage`	Bytes of deleted files still in the recycle bin
`totalUsage`	The two together -- the figure checked when anything is uploaded
`maxAllowedUsage`	The licensed allowance
`hardLimit`	Allowance plus the licensed overage buffer (the allowance itself when overage is disabled). At it, uploads fail with `STORAGE_QUOTA_EXCEEDED`
`isOverage` , `overage`	Whether, and by how many bytes, `totalUsage` is past the allowance

Folders cost nothing. A copy costs its size. Moves and renames change nothing. A delete changes nothing either: the bytes move from

activeUsage

recycleBinUsage

and still count until the item is purged (or the 30 days run out). The usage is also reported per environment.

存储的 file 归属于创建时所在的 environment，不同 environment 之间不会互通（getting-started > Sandbox vs Production）。Quota 是整个账户共用的一个数值：

字段	含义
`activeUsage`	active 和 pending file 的字节数
`recycleBinUsage`	已删除但仍在 recycle bin 中的 file 字节数
`totalUsage`	两者之和——上传任何内容时都会检查该数值
`maxAllowedUsage`	许可额度
`hardLimit`	许可额度加上许可的 overage buffer（禁用 overage 时就是额度本身）。达到该值时，上传会因 `STORAGE_QUOTA_EXCEEDED` 失败
`isOverage` , `overage`	`totalUsage` 是否超出额度，以及超出的字节数

Folder 不占用空间。复制会占用与源文件相同的空间。移动和重命名不会改变用量。删除本身也不会减少总用量：字节会从

activeUsage

转移到

recycleBinUsage

，在 item 被永久清除（或 30 天留存期结束）前仍会计入用量。用量也会按 environment 分别报告。

Uploads and the pending state

Upload 和 pending 状态

Bytes never pass through the API: an upload or replace returns short-lived presigned S3 URLs, and the bytes go straight to them -- one PUT for up to 5 GB, a multipart upload beyond that. A file starts

pending

and turns

active

once its bytes land, usually within seconds. While it's pending it can't be downloaded, moved, copied, renamed, or queried, and it holds its name and reserved quota. A multipart upload of a new file that's abandoned stays pending until it's cancelled.

字节数据绝不经过 API：upload 或 replace 会返回短时效的 presigned S3 URL，字节数据会直接发送到这些 URL——5 GB 及以内使用单次 PUT，超过时使用 multipart upload。File 初始为

pending

，字节数据到达后通常会在数秒内变为

active

。在 pending 期间，它不能被下载、移动、复制、重命名或查询，并且会占用其名称和预留 quota。新 file 的 multipart upload 如果被中止，会一直保持 pending，直至将其取消。

Access

访问权限

Access is checked per item: an item the caller can't reach answers 403, and a merge, for example, needs delete access on the source folder and write access on the destination. Two credentials can be confined to folder paths:

A service API token, with
```
_fileStoragePaths
```
-- up to seven paths, each starting and ending with
```
/
```
, each granting that folder and everything beneath it. It's exclusive with full access (managing-api-tokens).
A Celigo APIs connection with
```
accessScope.type: "custom"
```
and
```
accessScope._fileStoragePaths
```
-- prefixes, with
```
/
```
granting everything and no wildcards. A
```
custom
```
scope with no paths has no storage access.

Both match folder names, so renaming a granted folder breaks the grant.

访问权限按 item 检查：调用者无法访问的 item 会返回 403；例如，merge 要求对 source folder 具有 delete access，并对 destination 具有 write access。可以使用两种凭据将访问范围限制在特定 folder path：

Service API token，通过
```
_fileStoragePaths
```
配置——最多可设置七个 path，每个 path 都以
```
/
```
开头和结尾，并授予对该 folder 及其全部下级内容的访问权限。它与 full access 互斥（managing-api-tokens）。
Celigo APIs connection，通过
```
accessScope.type: "custom"
```
和
```
accessScope._fileStoragePaths
```
配置——这些值为 path 前缀，其中
```
/
```
授予全部访问权限，且不支持通配符。没有 path 的
```
custom
```
scope 对 storage 没有任何访问权限。

两者都按 folder 名称匹配，因此重命名已授权的 folder 会导致授权失效。

Quick Reference

快速参考

Which Operation

操作选择

You want to	Operation	`_id`	Notes
Change a file's bytes and keep every reference	Replace content	kept	No undo once it finalizes; the previous content stays downloadable until then
Rename or describe	Rename	kept	Only `name` and `description` are editable
Put an item in another folder	Move	kept	A folder's contents re-anchor asynchronously; quota unchanged
Get a second, independent file	Copy	new	Files only; default name `Clone - <name>` ; costs its size
Fold one folder into another	Merge	kept, unless the name collides	Folders only; runs as a background job. A same-name file overwrites the destination's file, and the source file's `_id` is lost; the source folder is removed, not sent to the bin
Remove, recoverably	Delete	--	30 days in the recycle bin; still counts toward the quota
Undo a delete	Restore	original	409 when the name was taken meanwhile: restore under a new name
Free the space for good	Purge	--	Irreversible; a folder's subtree goes with it

目标	操作	`_id`	说明
更改 file 的字节数据并保留所有引用	Replace content	保留	完成后无法撤销；完成前仍可下载旧 content
重命名或修改描述	Rename	保留	仅 `name` 和 `description` 可编辑
将 item 放入另一个 folder	Move	保留	Folder 的内容会异步重新挂载；quota 不变
获取第二个彼此独立的 file	Copy	新建	仅适用于 file；默认名称为 `Clone - <name>` ；会占用同等空间
将一个 folder 合并到另一个 folder	Merge	保留，除非名称冲突	仅适用于 folder；作为后台 job 运行。同名 file 会覆盖 destination 的 file，source file 的 `_id` 会丢失；source folder 会被直接移除，不会进入 bin
可恢复地移除	Delete	--	在 recycle bin 中保留 30 天；仍占用 quota
撤销 Delete	Restore	原值	如果名称已被占用则返回 409：换一个名称恢复
永久释放空间	Purge	--	不可逆；其中的 folder subtree 也会一并清除

Item Fields

Item 字段

Field	Meaning
`_id`	The item's identity -- what every reference holds
`type`	`file` or `folder` , fixed at creation
`name` , `description`	The only editable fields ( `name` up to 256 characters, `description` up to 1000)
`_parentId`	The containing folder; `null` at the account root
`_integrationId` , `integrationName`	The integration whose system folder holds the item ( `integrationName` only on the system folder itself)
`isSystem`	`true` on platform-created, protected folders
`status`	`pending` until an upload or replace lands, then `active`
`size` , `mimeType`	Bytes (always `0` for folders) and the media type recorded at upload
`deletedAt` , `deletedBy`	Recycle-bin items only: when, and by whom -- a user id, or `cascadeDelete` for a descendant of a deleted folder

字段	含义
`_id`	Item 的身份标识——所有引用都会保留它
`type`	`file` 或 `folder` ，创建后固定不变
`name` , `description`	唯一可编辑的字段（ `name` 最多 256 个字符， `description` 最多 1000 个字符）
`_parentId`	所在 folder；位于账户 root 下时为 `null`
`_integrationId` , `integrationName`	包含该 item 的 integration 系统 folder（ `integrationName` 仅存在于系统 folder 自身）
`isSystem`	平台创建且受保护的 folder 上为 `true`
`status`	Upload 或 replace 完成前为 `pending` ，完成后为 `active`
`size` , `mimeType`	字节数（folder 始终为 `0` ）以及上传时记录的媒体类型
`deletedAt` , `deletedBy`	仅 recycle-bin item 包含：删除时间及删除者（用户 id，或被删除 folder 后代的 `cascadeDelete` ）

Related Skills

How to Manage Stored Files

如何管理存储文件

1. Find the item and its id

1. 查找 item 及其 id

List a folder's direct children (the account root by default), or search names across the whole account. Search matches any word of the query -- hyphens split words -- so a specific name returns unrelated hits as well: confirm the hit by its containing folder (

location

), or list that folder. An integration's files sit under its system folder: list the root and match

_integrationId

Read a file's metadata, including its

path

breadcrumb, by id. Folder metadata comes from the listing of the folder's parent.

列出某个 folder 的直接子项（默认是账户 root），或跨整个账户搜索名称。搜索会匹配查询中的任一单词——连字符会拆词——因此输入具体名称也可能返回无关命中：请通过所在 folder（

location

）确认命中项，或列出该 folder。Integration 的文件位于其系统 folder 下：列出 root 并匹配

_integrationId

。

按 id 读取 file 的 metadata，其中包括

path

breadcrumb。Folder metadata 则来自其父 folder 的列表结果。

2. Check the quota before a large upload

2. 大型 upload 前检查 quota

Read the account's usage: compare

totalUsage

with

hardLimit

(and

maxAllowedUsage

for the overage buffer). If space is short, purge what the recycle bin holds (step 7) before uploading -- deleting alone frees nothing.

读取账户用量：将

totalUsage

与

hardLimit

进行比较，并结合

maxAllowedUsage

判断 overage buffer。如果空间不足，请在 upload 前永久清除 recycle bin 中的内容（步骤 7）——仅删除不会释放空间。

3. Upload a file or create a folder

3. Upload file 或创建 folder

Name the destination folder by id; omit it for the account root. A name already held by a live item in that folder is refused (409) -- to update that file, replace its content instead (step 5). Read the item back until its

status

active

before you use it.

通过 id 指定 destination folder；省略时使用账户 root。如果该 folder 中已有未删除的 item 占用此名称，请求会返回 409——要更新该文件，请改为替换其 content（步骤 5）。使用该 item 前，请反复读取它，直到

status

为

active

。

4. Organize: rename, move, copy, merge

4. 整理：重命名、移动、复制、合并

Rename changes
```
name
```
(and
```
description
```
); the
```
_id
```
stays.
Move re-parents an item -- one, or up to 100 at once. A name collision in the destination is refused; send a new name in the same move. A folder can't move into itself or a descendant, and an item can't "move" to the folder it's already in.
Copy duplicates a file into a folder under a new
```
_id
```
. Name it when the destination already holds a
```
Clone - <name>
```
file.
Merge moves a folder's contents into another folder, then removes the source folder. It runs in the background and returns a job receipt, so list the destination to see it finish. A file whose name is free in the destination keeps its
```
_id
```
. A file whose name the destination already holds overwrites that file: the destination file keeps its
```
_id
```
but takes the source's content, the old content is gone, and the source file's
```
_id
```
disappears -- nothing goes to the recycle bin. List both folders and compare names before merging.

Rename 更改
```
name
```
（以及
```
description
```
）；
```
_id
```
保持不变。
Move 重新设置 item 的父级——一次可移动一个，或最多同时移动 100 个。Destination 中发生名称冲突时，请求会被拒绝；可在同一次 move 中一并提供新名称。Folder 不能移入自身或其后代，item 也不能“移动”到已经所在的 folder。
Copy 将 file 复制到某个 folder 下，并创建新的
```
_id
```
。如果 destination 中已有名为
```
Clone - <name>
```
的 file，请为副本指定其他名称。
Merge 将一个 folder 的内容移入另一个 folder，然后移除 source folder。它会在后台运行并返回 job receipt，因此需要列出 destination 才能确认完成。如果 file 的名称在 destination 中尚未被占用，它会保留
```
_id
```
。如果 destination 已有同名 file，则会覆盖该 file：destination file 保留自己的
```
_id
```
，但会采用 source 的 content，旧 content 会消失，source file 的
```
_id
```
也会消失——这些内容都不会进入 recycle bin。Merge 前请列出两个 folder 并比较名称。

5. Replace a file's content (keep every reference)

5. 替换 file 的 content（保留所有引用）

Replace the bytes of an existing file: its

_id

, name, folder, and every reference stay. The file is

pending

until the new bytes land, and the old content stays downloadable until then. After that the old bytes are gone -- the recycle bin covers deletes, not replaces -- so copy or download the file first if the old content may be needed. A second replace started while one is in flight is refused with 409

STORAGE_ITEM_REPLACE_CONFLICT

替换现有 file 的字节数据：其

_id

、名称、folder 和所有引用都会保持不变。在新字节数据到达前，file 处于

pending

，旧 content 仍可下载。完成后旧字节数据会被永久删除——recycle bin 只处理 delete，不处理 replace——因此，如果可能仍需使用旧 content，请先复制或下载文件。Replace 正在进行时启动第二次 replace 会返回 409

STORAGE_ITEM_REPLACE_CONFLICT

。

6. Download a file or a whole folder

6. Download file 或整个 folder

A file downloads from a short-lived presigned URL;

expiresIn

gives its lifetime in seconds. A whole folder downloads as one zip, built before the response and rooted at the folder's name; pending files are skipped. Treat a presigned URL as a credential while it lives: hand it to the user or fetch it promptly, and never log or store it.

File 通过短时效的 presigned URL 下载；

expiresIn

给出其有效期（秒）。整个 folder 会作为单个 zip 下载；zip 在响应前构建，并以 folder 名称为根；pending file 会被跳过。在有效期内应将 presigned URL 视为凭据：交给用户或尽快获取文件，绝不要记录或存储该 URL。

7. Delete, restore, purge

7. Delete、Restore、Purge

Before deleting, find what uses the item -- no public check lists it, and a delete is never blocked by references: flow steps and tokens that point at the item are left dangling and fail at run time. Look for the item's id in flow steps on Celigo APIs connections that read or write its folder, in MCP servers'

resources[]._fileId

, and in file-server partner accounts'

_homeFolderId

. The one block: a folder that is, or contains, a partner account's home folder is refused with 403

STORAGE_SFTP_HOME_FOLDER_PROTECTED

until that account is deleted or re-pointed.

Delete sends the item to the recycle bin for 30 days. A folder's delete takes its whole subtree; the bin then lists only the folder, and its descendants come back or are purged with it.
Restore returns an item to its original folder with its original
```
_id
```
; a folder brings back what was deleted with it, its contents following asynchronously. A descendant removed by its folder's delete can't be restored on its own -- restore the folder. If a live item took the name meanwhile, the restore is refused with 409
```
STORAGE_ITEM_ALREADY_EXISTS
```
and the item stays in the bin: restore it under a new name, or rename the item that took it.
Purge deletes a bin item for good and frees its bytes; purging a folder purges its subtree. Purge only what the user has confirmed.

Deleted storage items appear in the account's recycle bin as

StorageItem

entries, but they're restored and purged through Celigo Storage -- the bin's generic routes refuse them.

deletedAt

and

deletedBy

on a bin entry say when and by whom an item was deleted.

删除前，查找哪些对象正在使用该 item——没有公开检查能列出这些引用，并且 delete 永远不会因引用而被阻止：指向该 item 的 flow step 和 token 会变成悬空引用，并在运行时失败。请在以下位置查找 item 的 id：读写其 folder 的 Celigo APIs connection 上的 flow step、MCP server 的

resources[]._fileId

，以及 file-server partner account 的

_homeFolderId

。唯一的阻止条件是：某个 folder 正是或包含 partner account 的 home folder，此时会返回 403

STORAGE_SFTP_HOME_FOLDER_PROTECTED

，直至删除该 account 或将其重新指向其他 folder。

Delete 会将 item 送入 recycle bin 并保留 30 天。删除 folder 会同时删除其整个 subtree；此时 bin 中只列出该 folder，其后代会随它一起恢复或永久清除。
Restore 会将 item 及其原始
```
_id
```
放回原始 folder；恢复 folder 时，会同时恢复随其一起删除的内容，内容会异步重新出现。随 folder 一同删除的后代不能单独恢复——必须恢复该 folder。如果已有未删除的 item 占用该名称，恢复请求会返回 409
```
STORAGE_ITEM_ALREADY_EXISTS
```
，且 item 会留在 bin 中：请换一个名称恢复，或重命名占用该名称的 item。
Purge 会永久删除 bin 中的 item 并释放其字节空间；永久清除 folder 时，其 subtree 也会一并清除。只永久清除用户已经明确确认的内容。

已删除的 storage item 会作为

StorageItem

entry 出现在账户的 recycle bin 中，但必须通过 Celigo Storage 执行恢复和永久清除——bin 的通用 routes 会拒绝处理这些 item。Bin entry 上的

deletedAt

和

deletedBy

会说明 item 的删除时间和删除者。

8. Use stored files in a flow

8. 在 Flow 中使用存储文件

A flow reaches Celigo Storage through a Celigo APIs connection (

assistant: "integratorceligoapi"

) and file steps in folder mode --

HTTPExport

HTTPImport

with

http.type: "file"

-- that address a folder, never a single file. The step shapes are in configuring-exports and configuring-imports.

The connection needs
accessScope
on create: for storage,
```
type: "custom"
```
with the
```
_fileStoragePaths
```
the flow uses. The connection document never carries the scope; it's read from
```
GET /v1/accessScope/connections/{_id}
```
. A
```
custom
```
scope without paths makes every storage step fail with 401 at run time.
A file-mode export deletes each source file after it processes it successfully, unless
```
file.skipDelete
```
is
```
true
```
. Set it when anything else still needs the file: a second flow, a partner downloading from that folder, or a file an MCP server publishes.
EDI parses from a storage folder like any file transport: put the EDI profile (
```
_ediProfileId
```
) on the file-mode export (building-b2b).

Flow 通过 Celigo APIs connection（

assistant: "integratorceligoapi"

）和 folder 模式下的 file step 访问 Celigo Storage——即

HTTPExport

或

HTTPImport

，并设置

http.type: "file"

——它们寻址的是 folder，绝不是单个 file。相关 step 结构见 configuring-exports 和 configuring-imports。

创建 connection 时必须设置
accessScope
：针对 storage，应使用
```
type: "custom"
```
，并提供 flow 所需的
```
_fileStoragePaths
```
。Connection 文档自身从不携带该 scope；它需要从
```
GET /v1/accessScope/connections/{_id}
```
读取。没有 path 的
```
custom
```
scope 会导致所有 storage step 在运行时返回 401。
File-mode export 会在成功处理后删除每个 source file，除非
```
file.skipDelete
```
为
```
true
```
。如果还有其他对象需要该文件，请进行此设置，例如第二个 flow、下载该 folder 的合作伙伴，或发布该文件的 MCP server。
EDI 与其他 file transport 一样从 storage folder 解析：将 EDI profile（
```
_ediProfileId
```
）设置在 file-mode export 上（building-b2b）。

9. Query a file with SQL

9. 使用 SQL 查询 file

Storage Query runs one read-only

SELECT

over stored CSV, TSV, JSON, NDJSON, or Parquet files, without downloading them or building a flow. It needs its own license entitlement, and every submit draws on an account-wide rate budget. See references/storage-query.md.

Storage Query 会对存储的 CSV、TSV、JSON、NDJSON 或 Parquet file 运行一条只读

SELECT

，无需下载文件或构建 flow。它需要单独的 license entitlement，并且每次 submit 都会消耗 account-wide rate budget。参见 references/storage-query.md。

10. Give a trading partner SFTP access

10. 为交易伙伴提供 SFTP 访问

The file server gives each partner an SFTP login rooted in a storage folder: what a partner uploads lands there, and what you put there is what the partner can download. It needs a license add-on and a full-access API token, and partner passwords never pass through chat. See references/file-server.md.

File server 为每个合作伙伴提供一个以 storage folder 为根目录的 SFTP login：合作伙伴上传的内容会落入该 folder，而你放在该处的内容也正是合作伙伴可以下载的内容。它需要 license add-on 和 full-access API token，并且合作伙伴密码绝不经过 chat。参见 references/file-server.md。

Pre-Submit Checklist

提交前检查清单

The item was found by
```
_id
```
, and a search hit was confirmed by its folder -- never acted on by name alone
To change a referenced file, you're replacing its content, not deleting and re-uploading it
The old content of a file you're replacing is copied or downloaded, if anyone may need it
Before a delete or a folder move: what references the item (flow steps, MCP server resources, partner home folders) is known, and the user confirmed
A purge is confirmed by the user, item by item
Before a merge: no file name exists in both folders, or the user accepts that the source's file overwrites the destination's
Before a large upload:
```
totalUsage
```
plus the file fits under
```
hardLimit
```
A flow that reads a storage folder that anything else also uses sets
```
file.skipDelete: true
```
A Celigo APIs connection for storage carries
```
accessScope
```
with the folder paths it needs
An upload or replace has finished (
```
status: "active"
```
) before the file is used

已通过
```
_id
```
找到 item，并通过其 folder 确认 search hit——绝不只凭名称执行操作
要更改被引用的 file 时，使用的是替换 content，而不是删除后重新上传
如果有人可能还需要被替换 file 的旧 content，已将其复制或下载
在 delete 或移动 folder 前：已知哪些对象引用该 item（flow step、MCP server resource、partner home folder），且用户已确认
用户已逐项确认永久清除
在 merge 前：两个 folder 中不存在同名 file，或者用户接受 source file 覆盖 destination file
在大型 upload 前：
```
totalUsage
```
加上文件大小未超过
```
hardLimit
```
读取 storage folder 的 flow 也会被其他对象使用时，已设置
```
file.skipDelete: true
```
用于 storage 的 Celigo APIs connection 携带了所需 folder path 的
```
accessScope
```
Upload 或 replace 已完成（
```
status: "active"
```
）后才使用该 file

Gotchas

常见陷阱

Delete plus re-upload is a new item. The new file gets a new
```
_id
```
, and every reference to the old one dangles. Replace the content instead; a restore from the bin keeps the old
```
_id
```
.
Deleting frees no space. Deleted bytes count toward the quota until they're purged (or expire after 30 days). To get under the limit, purge.
A replace has no undo. Once the new bytes land, the old ones are gone: the recycle bin only holds deleted items.
References don't block a delete. Flow steps and tokens pointing at the item go dangling, and no public dependency check lists what uses it. Only a partner's home folder refuses deletion.
The integration's folder goes with the integration. Deleting an integration sends its system folder and all its files to the recycle bin, and purging the integration purges them.
A file-mode export deletes what it reads.
```
file.skipDelete
```
defaults to
```
false
```
; a folder shared with another flow, a partner, or an MCP server needs
```
true
```
.
Paths are names, ids are identities. Storage Query paths and the folder paths on tokens and Celigo APIs connections stop matching when a folder is renamed or moved; references by id don't.
Search is broad. It matches any word of the query, across the whole account. Confirm a hit by its folder before acting on it.
Pending items are locked. Until an upload or replace lands, the file can't be downloaded, moved, renamed, copied, or queried. An abandoned multipart upload of a new file holds its name and quota until cancelled; never cancel a replace.
Merge overwrites and removes without the bin. A same-name file replaces the destination file's content, and the source file's
```
_id
```
disappears; the source folder is removed outright. None of it goes to the recycle bin, so compare the two folders' names and check what referenced the source folder and its files by id first.
System folders can't be touched. Not renamed, moved, copied, deleted, or purged -- not even by an administrator. Work inside them.

Delete 后重新上传得到的是新 item。 新 file 会获得新的
```
_id
```
，对旧 file 的所有引用都会变成悬空引用。请改为替换 content；从 bin 恢复则可保留旧
```
_id
```
。
Delete 不会释放空间。 已删除的字节在永久清除前（或 30 天后到期前）仍会占用 quota。要低于限制，请执行 purge。
Replace 无法撤销。 新字节数据到达后，旧字节数据就会消失：recycle bin 只保存已删除的 item。
引用不会阻止 Delete。 指向该 item 的 flow step 和 token 会变成悬空引用，并且没有公开的 dependency check 能列出使用方。只有 partner 的 home folder 会阻止删除。
Integration 的 folder 会随 integration 一起处理。 删除 integration 会将其系统 folder 和全部文件送入 recycle bin；永久清除 integration 时也会永久清除它们。
File-mode export 会删除读取的内容。
```
file.skipDelete
```
默认为
```
false
```
；如果 folder 还被另一个 flow、合作伙伴或 MCP server 使用，则需要设为
```
true
```
。
Path 是名称，id 才是身份。 Storage Query path，以及 token 和 Celigo APIs connection 上的 folder path，在 folder 被重命名或移动后都会停止匹配；按 id 建立的引用不会受影响。
Search 范围很宽。 它会跨整个账户匹配查询中的任一单词。执行操作前，请通过所在 folder 确认命中项。
Pending item 被锁定。 在 upload 或 replace 完成前，file 不能被下载、移动、重命名、复制或查询。被中止的新 file multipart upload 会占用其名称和 quota，直至被取消；绝不取消 replace。
Merge 会覆盖并移除内容，不经过 bin。 同名 file 会替换 destination file 的 content，source file 的
```
_id
```
会消失，source folder 会被直接移除。这一切都不会进入 recycle bin，因此应先比较两个 folder 的名称，并检查哪些对象按 id 引用了 source folder 及其中的 file。
System folder 不可修改。 不能重命名、移动、复制、删除或永久清除——即使管理员也不行。请在其中进行操作。

Common Errors

常见错误

Error	Cause	Fix
409 `STORAGE_ITEM_ALREADY_EXISTS`	A live item in that folder has the name (an upload, create, rename, move, copy, or restore)	Pick another name, move or copy with a new name, restore under a new name -- or replace the existing file's content
403 `STORAGE_SYSTEM_ITEM_PROTECTED` ("System items cannot be modified or deleted")	The item is an integration's system folder	Work inside the folder; it goes away with its integration
403 `STORAGE_SFTP_HOME_FOLDER_PROTECTED`	The folder is, or contains, a file-server partner's home folder	Delete the partner account or point it at another folder first
403 `STORAGE_PRESIGNED_URL_ACTIVE`	Deleting a pending single-PUT upload whose URL is still live	Wait for the URL to expire, then delete
409 `STORAGE_ITEM_REPLACE_CONFLICT`	Another replace of the file is still in flight	Wait for it to finish, then replace again
`STORAGE_QUOTA_EXCEEDED`	`totalUsage` reached `hardLimit`	Purge the recycle bin or delete and purge files; then retry
404 `STORAGE_PARENT_NOT_FOUND` ("Parent folder not found")	The folder id names nothing in this environment -- deleted, merged away, or from another environment	Find the folder again by listing
422 `STORAGE_PARENT_NOT_FOLDER`	A file's id was given where a folder belongs	Use the containing folder's id
Item stuck `pending`	An upload or replace never completed	A new file: cancel it if it was a multipart upload, or delete it once its upload URL has expired, then upload again. A replace: the file keeps its previous content -- run the replace again (409 `STORAGE_ITEM_REPLACE_CONFLICT` means the abandoned one hasn't expired yet)
A storage step fails with 401 at run time	The Celigo APIs connection's `custom` scope has no `_fileStoragePaths` , or none covering the folder	Add the folder's path to the connection's scope

错误	原因	修复方法
409 `STORAGE_ITEM_ALREADY_EXISTS`	该 folder 中已有未删除的 item 使用此名称（涉及 upload、create、rename、move、copy 或 restore）	选择其他名称；使用新名称进行 move 或 copy；换一个名称恢复——或者替换现有 file 的 content
403 `STORAGE_SYSTEM_ITEM_PROTECTED` （"System items cannot be modified or deleted"）	该 item 是某个 integration 的系统 folder	在该 folder 内部操作；它会随其 integration 一起消失
403 `STORAGE_SFTP_HOME_FOLDER_PROTECTED`	该 folder 正是或包含 file-server partner 的 home folder	先删除 partner account，或将其指向其他 folder
403 `STORAGE_PRESIGNED_URL_ACTIVE`	正在删除 pending 的单次 PUT upload，但对应 URL 仍然有效	等待 URL 过期后再删除
409 `STORAGE_ITEM_REPLACE_CONFLICT`	该 file 的另一次 replace 仍在进行	等待其完成，然后再次 replace
`STORAGE_QUOTA_EXCEEDED`	`totalUsage` 已达到 `hardLimit`	永久清除 recycle bin 中的内容，或先 delete 再永久清除文件；然后重试
404 `STORAGE_PARENT_NOT_FOUND` （"Parent folder not found"）	Folder id 在当前 environment 中没有对应项——已被删除、被合并，或来自另一个 environment	重新列出目录以查找该 folder
422 `STORAGE_PARENT_NOT_FOLDER`	在应使用 folder 的位置提供了 file 的 id	使用所在 folder 的 id
Item 一直处于 `pending`	Upload 或 replace 从未完成	对于新 file：如果它是 multipart upload，则取消；如果 URL 已过期，则删除后重新 upload。对于 replace：file 会保留之前的 content——再次运行 replace（409 `STORAGE_ITEM_REPLACE_CONFLICT` 表示被中止的 replace 尚未过期）
Storage step 在运行时返回 401	Celigo APIs connection 的 `custom` scope 没有 `_fileStoragePaths` ，或没有覆盖该 folder 的 path	将该 folder 的 path 添加到 connection 的 scope 中

managing-file-storage

Original

Translation

Managing File Storage

管理文件存储

How to Run the Steps

如何运行各个步骤

The Storage Model

存储模型

Items are addressed by id, not by path

Item 通过 id 寻址，而不是 path

Integration (system) folders

Integration（系统）文件夹

Content, environment, and quota

Content、environment 和 quota

Uploads and the pending state

Upload 和 pending 状态

Access

访问权限

Quick Reference

快速参考

Which Operation

操作选择

Item Fields

Item 字段

Related Skills

相关 Skills

How to Manage Stored Files

如何管理存储文件

1. Find the item and its id

1. 查找 item 及其 id

2. Check the quota before a large upload

2. 大型 upload 前检查 quota

3. Upload a file or create a folder

3. Upload file 或创建 folder

4. Organize: rename, move, copy, merge

4. 整理：重命名、移动、复制、合并

5. Replace a file's content (keep every reference)

5. 替换 file 的 content（保留所有引用）

6. Download a file or a whole folder

6. Download file 或整个 folder

7. Delete, restore, purge

7. Delete、Restore、Purge

8. Use stored files in a flow

8. 在 Flow 中使用存储文件

9. Query a file with SQL

9. 使用 SQL 查询 file

10. Give a trading partner SFTP access

10. 为交易伙伴提供 SFTP 访问

Pre-Submit Checklist

提交前检查清单

Gotchas

常见陷阱

Common Errors

常见错误