arcgis-custom-data-feeds

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ArcGIS Enterprise Custom Data Feeds (CDF)

ArcGIS Enterprise自定义数据馈送（CDF）

A Custom Data Feed is a Node.js provider — running on Koop.js inside the ArcGIS Enterprise SDK runtime — that pulls from any external source (REST API, database, file) and exposes it as a standard ArcGIS Feature Service. Your provider returns GeoJSON; the framework translates it into the GeoServices REST spec that ArcGIS clients consume.

Deployment and registration on ArcGIS Server (uploading

.cdpk

cdf register

) is out of scope here — this skill covers authoring and local testing of the provider.

自定义数据馈送（CDF）是一种Node.js提供程序——运行在ArcGIS Enterprise SDK运行时环境中的Koop.js之上——它可以从任意外部源（REST API、数据库、文件）拉取数据，并将其暴露为标准的ArcGIS Feature Service。你的提供程序返回GeoJSON格式数据，框架会将其转换为ArcGIS客户端可使用的GeoServices REST规范格式。

ArcGIS Server上的部署与注册（上传

.cdpk

、执行

cdf register

）不在本技能的讨论范围内——本技能涵盖提供程序的编写与本地测试。

Confirm the target Enterprise version first — before any code

写代码前先确认目标Enterprise版本

CDF arrived in ArcGIS Enterprise 11.1 (it does not exist in 10.x), and its capabilities are gated by release. The provider you write depends entirely on the version it must run against, so pin it before writing anything:

Ask which ArcGIS Enterprise version(s) must run this provider. A provider compiled against a newer runtime does not run on an older server — build against the lowest target release.
12.x requires a recompile. Providers must be recompiled in 12.x to run there; a provider built on 11.x is not binary-compatible with a 12.x runtime.
Match the OS family and Node.js major version of the development machine to the target server, or the compiled provider fails to load.

For the current release, the per-version capability list, and any breaking changes, read the live ArcGIS Enterprise SDK CDF guide and its "What's New" pages — do not rely on a restated matrix, which goes stale. To confirm a class, method, or option exists at a version, defer to the

arcgis-docs-lookup

skill.

CDF从ArcGIS Enterprise 11.1开始引入（10.x版本中不存在），其功能会随版本迭代而变化。你编写的提供程序完全依赖于它要运行的目标版本，因此在编写任何代码前请先确定版本：

确认该提供程序需要运行在哪些ArcGIS Enterprise版本上。针对较新运行时编译的提供程序无法在较旧服务器上运行——请针对最低目标版本进行构建。
12.x版本需要重新编译。提供程序必须在12.x环境中重新编译才能运行；基于11.x构建的提供程序与12.x运行时不兼容。
开发机器的操作系统家族和Node.js主版本必须与目标服务器匹配，否则编译后的提供程序将无法加载。

如需了解当前版本、各版本功能列表以及任何破坏性变更，请查阅官方实时文档**ArcGIS Enterprise SDK CDF指南**及其“新增功能”页面——不要依赖过时的信息汇总表。如需确认某个类、方法或选项在特定版本中是否存在，请使用

arcgis-docs-lookup

技能。

The 12.0 generation boundary

12.0版本的代际边界

CDF fundamentally changed at 12.0 — treat pre-12.0 and 12.0+ as two generations and never mix their assumptions:

The
config
npm module is retired in 12.0. Store credentials in a local JSON file inside
```
src/
```
and
```
require()
```
it directly. On 11.1–11.5,
```
config/default.json
```
is standard (top-level keys must be unique across all providers in the app).
12.0 upgrade trap: a provider that used the
```
config
```
module will not auto-re-register after an upgrade to 12.0. Migrate it to local JSON config before upgrading.
```
getMetadata()
```
(below) exists only from 12.0.

CDF在12.0版本中发生了根本性变化——请将12.0之前的版本和12.0及之后的版本视为两个不同代际，切勿混淆它们的设计假设：

12.0版本中
config
npm模块已被弃用。请将凭据存储在
```
src/
```
目录下的本地JSON文件中，并直接通过
```
require()
```
引入。在11.1–11.5版本中，
```
config/default.json
```
是标准配置文件（顶级键在应用中的所有提供程序中必须唯一）。
12.0版本升级陷阱：使用
```
config
```
模块的提供程序在升级到12.0后无法自动重新注册。请在升级前将其迁移为本地JSON配置。
```
getMetadata()
```
（下文介绍）仅从12.0版本开始存在。

Project scaffolding — the cdf CLI

项目脚手架——cdf CLI

bash

cdf createapp my-cdf-app          # once per project
cd my-cdf-app
cdf createprovider my-provider    # a provider inside the app
npm start                         # local dev server (HTTP :8080)
cdf export my-provider            # produce a deployable .cdpk

Generated shape (essentials):

providers/my-provider/src/index.js

(registration),

.../src/model.js

(core logic),

.../cdconfig.json

(provider config),

.../package.json

(provider deps).

Install npm packages at the provider level (
providers/my-provider/
), never at the app level. Never modify
framework/
— the bundled Koop packages are read-only.

bash

cdf createapp my-cdf-app          # 每个项目执行一次
cd my-cdf-app
cdf createprovider my-provider    # 在应用内创建一个提供程序
npm start                         # 本地开发服务器（HTTP端口：8080）
cdf export my-provider            # 生成可部署的.cdpk文件

生成的核心项目结构：

providers/my-provider/src/index.js

（注册文件）、

.../src/model.js

（核心逻辑）、

.../cdconfig.json

（提供程序配置）、

.../package.json

（提供程序依赖）。

请在提供程序级别安装npm包（
providers/my-provider/
目录下），切勿在应用级别安装。永远不要修改
framework/
目录——其中的Koop包是只读的。

The Model class

Model类

model.js

exports a class with up to four methods. The "since" column is durable release history, not a live matrix:

Method	Required	Since	Purpose
`getData(req)`	Yes	11.1	Fetch data; return a GeoJSON FeatureCollection
`editData(req, edits)`	No	11.4	Handle applyEdits (adds / updates / deletes)
`authorize(req)`	No	11.5	Pre-request authorization; throw to reject
`getMetadata()`	No	12.0	Return `idField` + `inputCrs` for edit reprojection

getData(req)

returns a GeoJSON

FeatureCollection

with a

metadata

block. Use the async/await form and never mix async and callback patterns in the same method — doing so crashes the process. See references/geojson-response-format.md for the full response schema and references/provider-patterns.md for the full-fetch vs. pass-through patterns.

Key

req

properties:

req.params.layer

(

'0'

'1'

, …),

req.params.<key>

(service parameter values),

req.query.where

req.query.resultOffset

req.query.resultRecordCount

(pagination),

req.query.returnCountOnly

(

'true'

→ return

{ count: N }

req._user

(requires

forwardUserIdentity: true

on the service).

model.js

导出一个类，最多包含四个方法。“起始版本”列是固定的版本历史记录，而非实时更新的矩阵：

方法名称	是否必填	起始版本	用途
`getData(req)`	是	11.1	获取数据；返回GeoJSON FeatureCollection格式数据
`editData(req, edits)`	否	11.4	处理applyEdits操作（添加/更新/删除）
`authorize(req)`	否	11.5	请求前授权；抛出异常以拒绝请求
`getMetadata()`	否	12.0	返回 `idField` 和 `inputCrs` 用于编辑时的投影转换

getData(req)

返回带有

metadata

块的GeoJSON

FeatureCollection

。请使用async/await语法，并且切勿在同一方法中混合使用异步和回调模式——否则会导致进程崩溃。完整响应架构请参考references/geojson-response-format.md，全量拉取与透传模式请参考references/provider-patterns.md。

req

的关键属性：

req.params.layer

（值为

'0'

、

'1'

等）、

req.params.<key>

（服务参数值）、

req.query.where

、

req.query.resultOffset

req.query.resultRecordCount

（分页参数）、

req.query.returnCountOnly

（值为

'true'

时需返回

{ count: N }

）、

req._user

（需要在服务中设置

forwardUserIdentity: true

）。

GeoJSON response rules

GeoJSON响应规则

All features in a layer must share the same geometry type.
Always declare
fields
explicitly — never rely on type inference from the first feature; it produces wrong types.
Always set
idField
to a unique numeric property. Omitting it forces full-feature hashing (slow, collision-prone). For editable providers,
```
idField
```
must reference a real field — auto-generated OIDs are unsupported.
Default CRS is WGS84 (4326); set
```
metadata.inputCrs
```
to the WKID when your data uses another.

For multi-layer services, return

{ layers: [...], tables: [], metadata: { name, inputCrs } }

when

req.params.layer

is undefined.

In the pass-through pattern, set
```
filtersApplied
```
(
```
where
```
,
```
geometry
```
,
```
objectIds
```
,
```
resultOffset
```
,
```
resultRecordCount
```
) to
```
true
```
for each filter you handled upstream so the framework does not double-apply it.
```
ttl
```
sets the LRU cache TTL in seconds (cache capacity: 500 elements).

同一图层中的所有要素必须具有相同的几何类型。
始终显式声明
fields
——切勿依赖第一个要素进行类型推断，这会导致类型错误。
**始终设置
```
idField
```
**为唯一的数值型属性。省略该属性会触发全要素哈希计算（速度慢且容易冲突）。对于可编辑的提供程序，
```
idField
```
必须指向真实字段——不支持自动生成的OID。
默认坐标系为WGS84（4326）；如果你的数据使用其他坐标系，请设置
```
metadata.inputCrs
```
为对应的WKID。

对于多图层服务，当

req.params.layer

未定义时，需返回

{ layers: [...], tables: [], metadata: { name, inputCrs } }

格式的数据。

在透传模式下，对于每个你已在上游处理的过滤器（
```
where
```
、
```
geometry
```
、
```
objectIds
```
、
```
resultOffset
```
、
```
resultRecordCount
```
），请将
```
filtersApplied
```
设置为
```
true
```
，以避免框架重复应用过滤器。
```
ttl
```
设置LRU缓存的过期时间（单位：秒），缓存容量为500条数据。

Guard destructive edits in editData()

在editData()中保护破坏性编辑操作

editData()

writes

adds

updates

deletes

to the provider's upstream store (a database, an external API) — these are irreversible data operations, so before generating any

editData

code that updates or deletes, satisfy every point in order:

Name the target. State the upstream system and the exact store/collection/table the writes hit. An unnamed target is a stop.
Show what it is. Surface what the update/delete affects (which records, roughly how many) so the user sees what they are about to change or lose.
Confirm it is not production. Say so explicitly and get the user's confirmation before proceeding.
Prefer the reversible form first. Offer a read-first / count-first path so the blast radius is known before the destructive write runs.
Never emit blind. Withhold the update/delete code until 1–4 are satisfied and the user confirms — even when the user sounds confident.

Return

{ addResults, updateResults, deleteResults }

with per-item

{ objectId, success, error? }

. Error codes:

insert,

delete,

update.

rollbackOnFailure

is not enforced by the framework — implement transaction logic in

editData()

yourself. Gate writes with

authorize(req)

(throw to reject).

editData()

会将

adds

updates

deletes

写入提供程序的上游存储（数据库、外部API）——这些操作是不可逆的数据操作，因此在生成任何用于更新或删除的

editData

代码之前，请依次满足以下所有条件：

明确目标。说明上游系统以及写入操作会影响的具体存储/集合/表。未明确目标的情况下请停止操作。
展示影响范围。显示更新/删除操作会影响哪些记录（大致数量），让用户清楚他们将要更改或删除的内容。
确认非生产环境。明确说明当前环境并非生产环境，并在继续操作前获得用户的确认。
优先选择可逆方式。先提供只读/计数的路径，让用户在执行破坏性写入操作前了解影响范围。
切勿盲目生成代码。在满足1-4条件并获得用户确认之前，不要提供更新/删除代码——即使用户看起来很有信心。

返回格式为

{ addResults, updateResults, deleteResults }

，每个条目包含

{ objectId, success, error? }

。错误代码：

（插入错误）、

（删除错误）、

（更新错误）。框架不强制实现

rollbackOnFailure

——请在

editData()

中自行实现事务逻辑。可以使用

authorize(req)

来限制写入操作（抛出异常以拒绝请求）。

Configuration and secrets

配置与密钥管理

12.0+:
```
require()
```
a local JSON config file inside
```
src/
```
. Add it to
```
.gitignore
```
.
11.1–11.5: the
```
config
```
module (
```
config/default.json
```
).
Never hardcode credentials; never commit config JSON with real secrets.

12.0及以上版本：通过
```
require()
```
引入
```
src/
```
目录下的本地JSON配置文件。将该文件添加到
```
.gitignore
```
中。
11.1–11.5版本：使用
```
config
```
模块（
```
config/default.json
```
）。
切勿硬编码凭据；切勿提交包含真实密钥的配置JSON文件。

Done when

完成标准

The target Enterprise version is fixed (and the provider built against the lowest target, recompiled for 12.x if needed); pre-12.0 vs 12.0+ config handling matches that version; every

getData

response declares

fields

and a numeric

idField

with one geometry type per layer; secrets live in gitignored config, never inline; any

editData

update/delete has passed through the guard; and version-specific claims were confirmed against the live Enterprise SDK CDF guide via

arcgis-docs-lookup

已确定目标Enterprise版本（并针对最低目标版本构建，如需在12.x运行则已重新编译）；12.0之前版本与12.0及以上版本的配置处理方式与对应版本匹配；每个

getData

响应都声明了

fields

和数值型

idField

，且每个图层只有一种几何类型；密钥存储在已加入git忽略的配置文件中，而非硬编码；任何

editData

中的更新/删除操作都通过了防护检查；且所有版本相关的声明都已通过

arcgis-docs-lookup

技能在官方实时Enterprise SDK CDF指南中得到确认。

Reference files

参考文件

File	When to read
references/geojson-response-format.md	Full metadata schema, field types, multi-layer format, edit templates
references/provider-patterns.md	Full-fetch vs. pass-through, count/extent shortcuts, upstream auth
references/examples/minimal-provider.md	Complete working read-only provider (illustrative, targeting 12.0)
references/examples/editable-provider.md	Complete editable provider with a database backend (illustrative, targeting 12.0)

文件链接	阅读场景
references/geojson-response-format.md	查看完整元数据架构、字段类型、多图层格式、编辑模板
references/provider-patterns.md	了解全量拉取与透传模式、计数/范围快捷方式、上游授权方式
references/examples/minimal-provider.md	完整的只读提供程序示例（仅供参考，目标版本为12.0）
references/examples/editable-provider.md	带有数据库后端的完整可编辑提供程序示例（仅供参考，目标版本为12.0）