cloudcannon-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The CloudCannon SDK

CloudCannon SDK

@cloudcannon/sdk

is the REST API client the CloudCannon CLI is built on. It exposes a hierarchy of sub-clients over the API, plus a typed

fetch

that reaches endpoints no sub-client wraps.

Reach for it when the work is programmatic. Reach for the CLI when the work is a shell command.

@cloudcannon/sdk

是构建 CloudCannon CLI 所基于的 REST API 客户端。它在 API 之上提供分层子客户端，并提供带类型的

fetch

，用于访问未由任何子客户端封装的端点。

当工作需要通过编程完成时，使用它；当工作是一项 shell 命令时，使用 CLI。

When to use

何时使用

Calling the CloudCannon API from a script, a build step, or a service
Operating over many sites or organisations in one pass
Reaching a surface the CLI does not expose — DAMs, backups, sync history and pulls, site scans, screenshots, provider connect/disconnect,
```
site.copy
```
,
```
site.delete
```
Handling API failures by type rather than by exit code
Finding out which methods exist, and what they take

从脚本、构建步骤或服务调用 CloudCannon API
一次处理多个站点或组织
访问 CLI 未暴露的 API 功能——DAM、备份、同步历史和 pulls、站点扫描、截图、服务商连接/断开连接、
```
site.copy
```
、
```
site.delete
```
按类型处理 API 故障，而不是依据退出代码
了解有哪些方法及其所需参数

When not to use

何时不应使用

A one-off operation from a shell — that is
```
cloudcannon-cli
```
. If a command already does the job, use it; it resolves site names, prints JSON, and needs no client wiring.
Running the site locally in CloudCannon —
```
cloudcannon dev
```
is covered end to end by
```
cloudcannon-dev-server
```
. The SDK has nothing to do with it.
Deciding what belongs in
cloudcannon.config.yml
— that is
```
cloudcannon-configuration
```
. The SDK reads and writes the file as bytes; it has no opinion on its contents.

Authoring editable regions or snippets —

cloudcannon-visual-editing

and

cloudcannon-snippets

从 shell 执行一次性操作——应使用
```
cloudcannon-cli
```
。如果已有命令可以完成这项工作，就使用该命令；它会解析站点名称、输出 JSON，且无需配置客户端。
在 CloudCannon 中本地运行站点——
```
cloudcannon-dev-server
```
已完整涵盖
```
cloudcannon dev
```
。SDK 与此无关。
决定
cloudcannon.config.yml
中应包含哪些内容——这属于
```
cloudcannon-configuration
```
。SDK 仅以字节形式读写该文件，并不评判其中的内容。
编写可编辑区域或 snippets——请使用
```
cloudcannon-visual-editing
```
和
```
cloudcannon-snippets
```
。

The rule that costs the most

最需要谨慎的规则

MUST confirm with the user before any call that writes to a hosted site. This is the same rule the CLI carries, and the reason is the same — see

cloudcannon-cli

§ The rule that costs the most for the canonical statement.

Two things make it easier to break here than at the command line:

There is no command name to read as a warning.
```
site.delete()
```
is a method call with no arguments, no flag, and no confirmation prompt.
The SDK reaches destructive endpoints the CLI has no command for at all —
```
site.delete()
```
,
```
site.copy()
```
,
```
disconnectSourceProvider()
```
,
```
disconnectOutputProvider()
```
.

The gate covers

client.fetch

too. A

POST

through the escape hatch is a write.

调用任何会写入托管站点的接口之前，必须先向用户确认。 这与 CLI 遵循的是同一规则，原因也相同——标准表述见

cloudcannon-cli

§ 最需要谨慎的规则。

以下两点使其比在命令行中更容易违反这一规则：

没有命令名可以作为警告。
```
site.delete()
```
是一次方法调用，没有参数、标志或确认提示。
SDK 可以访问 CLI 完全没有对应命令的破坏性端点——
```
site.delete()
```
、
```
site.copy()
```
、
```
disconnectSourceProvider()
```
、
```
disconnectOutputProvider()
```
。

这一确认门槛也适用于

client.fetch

。通过该逃生通道发出的

POST

同样属于写入操作。

Requirements

环境要求

Node 20 or newer, per the package's

engines

field — lower than the CLI's Node 24. The package is ESM (

"type": "module"

) and its default export is the client class.

import CloudCannonClient from "@cloudcannon/sdk";

根据包的

engines

字段，需要 Node 20 或更高版本——低于 CLI 要求的 Node 24。该包采用 ESM（

"type": "module"

），默认导出为客户端类。

import CloudCannonClient from "@cloudcannon/sdk";

Quick start

快速入门

Sub-clients take a UUID and nothing else, so almost every task starts by finding one.

import CloudCannonClient from "@cloudcannon/sdk";

// The SDK reads no credentials of its own — you supply them.
const client = new CloudCannonClient({
  userAccessKey: {
    id: process.env.CC_ACCESS_KEY_ID,
    secret: process.env.CC_ACCESS_KEY_SECRET,
  },
});

const { items: orgs } = await client.orgs();
const { items: sites } = await client.org(orgs[0].uuid).sites({ filters: { search: "my-site" } });

const site = await client.site(sites[0].uuid).get();

子客户端只接受 UUID，因此几乎每项任务都要先找到一个 UUID。

import CloudCannonClient from "@cloudcannon/sdk";

// SDK 不会读取任何凭据——需要由你提供。
const client = new CloudCannonClient({
  userAccessKey: {
    id: process.env.CC_ACCESS_KEY_ID,
    secret: process.env.CC_ACCESS_KEY_SECRET,
  },
});

const { items: orgs } = await client.orgs();
const { items: sites } = await client.org(orgs[0].uuid).sites({ filters: { search: "my-site" } });

const site = await client.site(sites[0].uuid).get();

File	Covers
SKILL.md (this file)	Routing, the write gate, requirements
client.md	Constructing the client, the config shape, and why it reads no credentials itself
resources.md	The sub-client hierarchy, UUID addressing, pagination, return types
api-surface.md	Reading the authoritative method list, and the raw `client.fetch` escape hatch
editing-sessions.md	Writing files to a hosted site through the SDK
troubleshooting.md	Symptom → cause → fix

文件	涵盖内容
SKILL.md（本文件）	路由、写入确认门槛、环境要求
client.md	构建客户端、配置结构，以及它为何不自行读取凭据
resources.md	子客户端层级、UUID 寻址、分页、返回类型
api-surface.md	查看权威方法列表，以及原始 `client.fetch` 逃生通道
editing-sessions.md	通过 SDK 将文件写入托管站点
troubleshooting.md	症状 → 原因 → 修复

Common mistakes

常见误区

Excuse	Reality
"I'll pass the site name to `client.site()` ."	Sub-clients take a UUID only. Resolve it first — resources.md § Addressing a resource.
" `client.sites()` will list every site I can see."	There is no such method. Sites are listed per organisation. See resources.md.
"The SDK will pick up my `cloudcannon login` credentials."	It reads nothing from disk or the environment. That chain is a CLI feature — client.md.
"I'll write out the method signatures from memory."	Signatures change between releases. Read them from the installed package — api-surface.md.
" `await site.getFile(path)` gives me the file contents."	It gives you a `Response` . Several methods do — resources.md § What a method returns.
"The list came back, so that's all of them."	Paginated endpoints return one page. Check `total_pages` — resources.md § Pagination.
" `client.fetch` is the low-level API, so the write gate is a CLI thing."	The gate is about the endpoint, not the wrapper. A `POST` through `fetch` writes to a live site exactly as a named method does.

误区	实际情况
"我会把站点名称传给 `client.site()` 。"	子客户端只接受 UUID。请先解析它——resources.md § 资源寻址。
" `client.sites()` 会列出我能看到的每个站点。"	不存在这样的方法。站点按组织列出。请参阅 resources.md。
"SDK 会读取我的 `cloudcannon login` 凭据。"	它不会从磁盘或环境变量中读取任何内容。这条凭据链是 CLI 的功能——client.md。
"我会凭记忆写出方法签名。"	方法签名会随版本发布而变化。请从已安装的包中读取——api-surface.md。
" `await site.getFile(path)` 会返回文件内容。"	它返回的是 `Response` 。多个方法都是如此——resources.md § 方法返回什么。
"列表已经返回，所以那就是全部。"	分页端点只返回一页。请检查 `total_pages` ——resources.md § 分页。
" `client.fetch` 是底层 API，因此写入确认门槛是 CLI 才需要管的事。"	确认门槛针对的是端点，而不是封装方式。通过 `fetch` 发出 `POST` ，会像具名方法一样写入线上站点。