Cloudflare Network Interconnects（CNI）API 完全指南：REST 端点、SDK 命名空间与多语言自动化实战-育师

Cloudflare Network Interconnects（CNI）API 完全指南：REST 端点、SDK 命名空间与多语言自动化实战

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

Cloudflare Network Interconnect（CNI）是面向企业用户的私有高性能网络连接方案，而本文所讲的 CNI API 则是把"互联线路（Interconnect）申请、BGP 配置对象（CNI Object）管理、机柜槽位（Slot）查询、LOA 文件下载"等运维动作全面脚本化的官方接口。本文以仓库中的 CNI API 参考文档为主体骨架，结合同目录的 README、configuration.md、patterns.md 与 gotchas.md 做纵深扩充。读完本文，你将掌握：CNI 全套 REST 端点的地址与请求体字段、TypeScript / Python 官方 SDK 与 cURL 的三种实操写法、健康检查与默认 ASN 的配置方式，以及哪些能力 API 不提供、只能走 Dashboard 或联系账户团队。

CNI 是什么：API 自动化的前提背景

在进入端点细节前，先明确 CNI 的定位：它是连接到 Cloudflare 全球网络的私有、高性能链路，属于**企业版（Enterprise-only）**能力。根据 network-interconnect/README.md，CNI 提供三种连接类型：

连接类型	说明
Direct	在共享机房中的物理光纤，支持 10/100 Gbps，需自行向机房下单交叉连接（cross-connect）
Partner	通过 Console Connect、Equinix、Megaport 等伙伴平台提供的虚拟连接，由伙伴 SDN 管理
Cloud	AWS Direct Connect 或 GCP Cloud Interconnect，仅适用于 Magic WAN

数据平面分两个版本：v1（Classic）支持 GRE 隧道、VLAN/BFD/LACP，MTU 不对称（下行 1500 / 上行 1476），支持公网对等互联（peering）；v2（Beta）无 GRE，双向 1500 MTU，暂不支持 VLAN/BFD/LACP，改用 ECMP。

API 能自动化的边界（来自 README 的 Automation Boundary 一节）总结如下：

可 API 自动化：列出/创建/删除互联线路（Direct、Partner）、列出可用槽位、查询线路状态、下载 LOA PDF、创建/更新 CNI 对象（BGP 配置）、查询设置。
需要账户团队：初始请求审批、AWS Direct Connect 配置、GCP Cloud Interconnect 最终激活、Partner 互联接受（Equinix、Megaport）、v1 的 VLAN 分配、v1 配置文档生成、升级与排障支持。
完全无法自动化：物理交叉连接安装、伙伴门户操作（虚拟电路下单）、AWS/GCP 门户操作、维护窗口协调。

理解了这条边界，就能明白为什么下面的 API 设计"能做这些、不做那些"。

API 基础：Base URL 与认证方式

所有 CNI 端点都挂在 Cloudflare API v4 的基础地址之下，使用 Bearer Token 认证：

https://api.cloudflare.com/client/v4 Auth: Authorization: Bearer <token>

配合环境变量使用时，典型做法是：

export CF_TOKEN="<your-api-token>" # API 令牌 export ACCOUNT_ID="<your-account-id>" # 账户 ID，URL 路径参数 account_id 的取值

在 CI/CD 场景下，可参考 SKILL.md 中 wrangler 的认证约定，将CF_TOKEN作为机密环境变量注入。需要提醒的是：如果账户不是企业版，调用 CNI 端点会得到403 Forbidden: "Enterprise plan required"（详见 gotchas.md），此时只能联系账户团队升级套餐。

SDK 命名空间：主用与弃用

官方 SDK 将 CNI 能力收敛在networkInterconnects命名空间下，包含三个子命名空间：

主用（推荐）：

client.networkInterconnects.interconnects.* client.networkInterconnects.cnis.* client.networkInterconnects.slots.*

弃用（替代）：

client.magicTransit.cfInterconnects.*

规则明确：所有新代码一律使用networkInterconnects命名空间。interconnects对应物理/虚拟互联线路资源，cnis对应 BGP 配置对象（CNI Object），slots对应可用的机柜槽位资源。Python SDK 中对应为client.network_interconnects.interconnects.*、client.network_interconnects.cnis.*、client.network_interconnects.slots.*。

Interconnects 端点详解：线路全生命周期

端点一览

GET /accounts/{account_id}/cni/interconnects # Query: page, per_page POST /accounts/{account_id}/cni/interconnects # Query: validate_only=true (optional) GET /accounts/{account_id}/cni/interconnects/{icon} GET /accounts/{account_id}/cni/interconnects/{icon}/status GET /accounts/{account_id}/cni/interconnects/{icon}/loa # Returns PDF DELETE /accounts/{account_id}/cni/interconnects/{icon}

GET列表支持分页参数page与per_page；
POST创建时可带可选查询参数validate_only=true做只校验不落库的干跑（dry-run）；
{icon}是互联线路的 ID（响应体中的id字段，形如icon_abc）；
GET .../loa返回 PDF 格式的 Letter of Authorization（授权函）。

Create Body 字段说明

创建线路的请求体包含以下字段：

字段	说明
`account`	账户 ID（与 URL 中的`{account_id}`一致）
`slot_id`	目标槽位 ID，从 Slots 接口查询，必须未被占用
`type`	连接类型：`direct`、`partner`、`cloud`（对应 README 中的三种连接方式）
`facility`	机房设施代码，例如`EWR1`（纽瓦克）。必须使用合法代码，否则返回`400 invalid facility code`
`speed`	带宽规格，如`10G`、`100G`
`name`	线路名称（业务标识，如`prod-interconnect`）
`description`	描述信息

Status 取值与含义

线路状态字段取值为active | healthy | unhealthy | pending | down。结合 configuration.md 的监控状态表可以进一步理解每个值的物理含义：

状态	含义
`healthy`	链路运行、流量正常、健康检查通过
`active`	链路已 up、光功率充足、以太网协商成功
`unhealthy`	链路 down、光功率低（低于 -20 dBm）、无法协商
`pending`	交叉连接未完成、设备无响应、RX/TX 光纤接反
`down`	物理链路断开、完全无连通性

响应示例

{"result": [{"id": "icon_abc", "name": "prod", "type": "direct", "facility": "EWR1", "speed": "10G", "status": "active"}]}

注意type: "direct"与status: "active"的搭配——创建成功后线路并非立即可用，通常会经历pending阶段（等待交叉连接施工与光纤接续），需通过status端点轮询推进。

轮询策略建议

patterns.md 中的 HA 模式代码使用pollUntilActive函数等待线路激活，而 gotchas.md 的反模式表明确指出：不要每秒轮询 status（浪费配额、易触发限速），轮询间隔建议 30～60 秒。

CNI Objects 端点详解：BGP 配置对象

CNI Object 是绑定在互联线路上的 BGP 配置实体。端点如下：

GET /accounts/{account_id}/cni/cnis POST /accounts/{account_id}/cni/cnis GET /accounts/{account_id}/cni/cnis/{cni} PUT /accounts/{account_id}/cni/cnis/{cni} DELETE /accounts/{account_id}/cni/cnis/{cni}

请求体字段：

字段	说明
`account`	账户 ID
`cust_ip`	客户侧 IP，/31 点对点子网中的一个地址，如`192.0.2.1/31`
`cf_ip`	Cloudflare 侧 IP，同 /31 子网的另一个地址，如`192.0.2.0/31`
`bgp_asn`	客户 BGP ASN，如`65000`（私用 ASN 区间）
`bgp_password`	BGP MD5 密码（可选但推荐）
`vlan`	VLAN 编号

关于 VLAN 有一个关键陷阱：在 v1 数据平面下VLAN 由 Cloudflare 分配，而不是自行指定。因此 gotchas.md 的反模式表特别警告"不要在自动化里硬编码 VLAN"，正确做法是从 CNI Object 的创建/查询响应中动态读取分配到的 VLAN ID。

BGP 配置参考（v1）

结合 configuration.md 的 BGP 配置一节，v1 线路的 BGP 对等参数示例如下：

Router ID: 192.0.2.1 Peer IP: 192.0.2.0 Remote ASN: 13335 # Cloudflare 的 ASN Local ASN: 65000 Password: [optional] VLAN: 100 # 由 CF 分配，勿硬编码

v2 的 BGP 配置更为简化；另外值得注意的是（configuration.md 中注明为 2024 年 12 月的演进）：Magic WAN/Transit 现在可以直接在 CNI v2 上对等 BGP，无需 GRE 隧道。

Slots 端点详解：查询可用槽位

在创建 Direct/Partner 线路前，通常需要先确认目标机房有没有可用的物理槽位：

GET /accounts/{account_id}/cni/slots GET /accounts/{account_id}/cni/slots/{slot}

支持的查询参数：

参数	说明
`facility`	按机房过滤，如`EWR1`
`occupied`	按占用状态过滤，`false`表示只看空闲槽位
`speed`	按带宽过滤，如`10G`

如果跳过这一步直接创建，很可能撞上400 Bad Request: "slot_id already occupied"——即该槽位已被其他互联线路占用。官方推荐的标准姿势是先用occupied=false过滤拿到空闲槽位（gotchas.md 中的 API 错误处理）：

await client.networkInterconnects.slots.list({ account_id: id, occupied: false, facility: 'EWR1', });

健康检查：在隧道端点层配置

CNI 自身的健康检查并不通过独立的/cni/*端点配置，而是通过Magic Transit / WAN 隧道端点（CNI v2）来配置。在 TypeScript SDK 中示例如下：

await client.magicTransit.tunnels.update(accountId, tunnelId, { health_check: { enabled: true, target: '192.0.2.1', rate: 'high', type: 'request' }, });

target：健康检查目标 IP；
rate（检查频率）：high|medium|low；
type（探测类型）：request|reply。

配置完成后，建议立即开启维护通知（Dashboard → Notifications），CNI Connection Maintenance 告警可提前最多 2 周预告维护窗口，新订阅的维护告警最长有 6 小时延迟（详见 configuration.md 的监控与告警一节）。

Settings 端点：查询与更新默认 ASN

账户级的 CNI 默认设置通过以下端点管理：

GET /accounts/{account_id}/cni/settings PUT /accounts/{account_id}/cni/settings

请求体仅一个字段：default_asn。它用于为账户设置默认 BGP ASN，便于后续 CNI 对象创建时复用，避免每次重复传参。

三语言实战：TypeScript / Python / cURL 完整示例

TypeScript SDK

以下示例完整覆盖"列表、创建（带/不带校验）、查状态、下载 LOA、创建 CNI 对象、筛选槽位"六个高频操作：

import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env.CF_TOKEN }); // List（列出所有互联线路，可带分页参数） await client.networkInterconnects.interconnects.list({ account_id: id }); // Create with validation（干跑：只校验配置，不真正创建） await client.networkInterconnects.interconnects.create({ account_id: id, account: id, slot_id: 'slot_abc', type: 'direct', facility: 'EWR1', speed: '10G', name: 'prod-interconnect', }, { query: { validate_only: true }, // Dry-run validation }); // Create without validation（正式创建） await client.networkInterconnects.interconnects.create({ account_id: id, account: id, slot_id: 'slot_abc', type: 'direct', facility: 'EWR1', speed: '10G', name: 'prod-interconnect', }); // Status（查询线路状态，注意参数是 accountId 与 iconId） await client.networkInterconnects.interconnects.get(accountId, iconId); // LOA（SDK 未封装 PDF 下载，直接用 fetch 拉取并落盘） const res = await fetch(`https://api.cloudflare.com/client/v4/accounts/${id}/cni/interconnects/${iconId}/loa`, { headers: { Authorization: `Bearer ${token}` }, }); await fs.writeFile('loa.pdf', Buffer.from(await res.arrayBuffer())); // CNI object（创建 BGP 配置对象，/31 点对点子网） await client.networkInterconnects.cnis.create({ account_id: id, account: id, cust_ip: '192.0.2.1/31', cf_ip: '192.0.2.0/31', bgp_asn: 65000, vlan: 100, }); // Slots（按机房与带宽过滤空闲槽位） await client.networkInterconnects.slots.list({ account_id: id, occupied: false, facility: 'EWR1', speed: '10G', });

两点实用提示：

validate_only=true是创建前最值得用的一步——如果配置有问题，接口会返回422 Unprocessable: "validate_only request failed"，并附带具体错误详情，此时应先修正配置再正式创建（gotchas.md）。
LOA 下载需要fs与Buffer配合fetch完成，注意令牌通过Authorization请求头传递。

Python SDK

Python 端的模式与 TypeScript 一一对应，只需注意命名空间使用下划线风格network_interconnects：

import os from cloudflare import Cloudflare client = Cloudflare(api_token=os.environ["CF_TOKEN"]) # List, create, status（与 TypeScript 同构） client.network_interconnects.interconnects.list(account_id=id) client.network_interconnects.interconnects.create(account_id=id, account=id, slot_id="slot_abc", type="direct", facility="EWR1", speed="10G") client.network_interconnects.interconnects.get(account_id=id, icon=icon_id) # CNI objects and slots client.network_interconnects.cnis.create(account_id=id, cust_ip="192.0.2.1/31", cf_ip="192.0.2.0/31", bgp_asn=65000) client.network_interconnects.slots.list(account_id=id, occupied=False)

注意：Python SDK 中创建 CNI 对象时可省略account参数（由account_id推导），而查询互联线路状态用的是icon关键字参数。

cURL

不依赖任何 SDK 时，直接用 REST 端点：

# List interconnects（列出互联线路） curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects" \ -H "Authorization: Bearer ${CF_TOKEN}" # Create interconnect（创建线路，validate_only=true 干跑校验） curl -X POST "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects?validate_only=true" \ -H "Authorization: Bearer ${CF_TOKEN}" -H "Content-Type: application/json" \ -d '{"account": "id", "slot_id": "slot_abc", "type": "direct", "facility": "EWR1", "speed": "10G"}' # LOA PDF（下载授权函到本地文件） curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects/${ICON_ID}/loa" \ -H "Authorization: Bearer ${CF_TOKEN}" --output loa.pdf

API 不提供的能力：明确边界与替代方案

原文档明确列出了以下API 无法覆盖的能力，自动化设计时必须为它们预留人工/外部通道：

BGP 会话状态查询——只能通过 Dashboard 或 BGP 日志查看；
带宽利用率指标——需要外部监控系统；
每条互联线路的流量统计；
历史可用性/宕机数据；
光功率读数（light level）——需联系账户团队；
维护窗口排期——仅支持通知，不开放 API 编排。

与之呼应的 gotchas.md 的 "What's Not Queryable via API" 一节还补充了：光纤路径细节、交叉连接施工状态、维护窗口时间表同样不可查询。推荐的变通做法是：

BGP 状态 → 外部监控（如对端路由器的 BGP 会话监控）；
历史数据 → 日志聚合平台；
维护窗口 → 订阅 Cloudflare Status 维护通知。

常见 API 错误与限速：实战排错清单

把 gotchas.md 的 API Errors 一节与本文端点对照，整理成可直接对号入座的排错表：

错误	原因	解法
`400 slot_id already occupied`	槽位已被其他线路占用	用`occupied=false`过滤空闲槽位后再选
`400 invalid facility code`	机房代码拼写错误或不受支持	核对官方设施代码表
`403 Enterprise plan required`	账户非企业版	联系账户团队升级
`422 validate_only request failed`	干跑校验发现问题（槽位错误、配置非法）	阅读错误详情，修正后再正式创建

速率限制：官方限制为每个令牌1200 请求 / 5 分钟。应对策略包括：实现指数退避（exponential backoff）重试、缓存槽位列表以减少重复查询（gotchas.md）。

自动化落地建议与反模式

结合 patterns.md 的 Failover & Security 一节与 gotchas.md 的反模式表，面向 API 自动化给出以下可执行建议：

最小权限令牌：为自动化脚本签发只包含 CNI 相关权限的 API Token，并定期轮换凭证；
BGP 密码认证：CNI 对象创建时尽量携带bgp_password，配合 BGP 路由过滤（注意不要被防火墙拦截 TCP/179）；
避免每秒轮询：status 轮询间隔控制在 30～60 秒；
不要硬编码 VLAN：v1 的 VLAN 由 Cloudflare 分配，须从 CNI 对象响应中读取；
不要假设 BGP up 即流量通：BGP 会话建立 ≠ 路由已安装，上线后必须验证路由表与实际流量（patterns.md）；
生产环境至少两条线路：CNI 无 SLA，单一线路是单点故障，应使用 ≥2 条且设备多样性的线路，并通过 BGP local preference 分级（如主线路 200、备线路 150、第三线路 100、公网兜底）。

继续深入：本仓库配套参考

本文对应的完整参考集位于 network-interconnect 目录，按任务场景推荐阅读顺序：

首次搭建：先读 README 了解连接类型与前提条件 → 再读 configuration.md 完成 BGP 与监控配置 → 最后回到本文的 api.md 做 API 化；
设计高可用架构：参考 patterns.md（HA、多云混合、多机房模式）；
排障：直接翻阅 gotchas.md（物理层、BGP 层、API 层错误全覆盖）；
若需了解 CNI 在部署流程中的整体定位，可查看 cloudflare-deploy 技能的 SKILL.md（其中"我需要网络/连接"决策树将私有网络连接导向 network-interconnect 参考集）。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考