Apify Actor 输出 Schema 权威指南用 Output Schema 与模板变量打通数据集、键值存储与运行结果展示【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills导读Output Schema输出模式是 Apify Actor 面向外部世界的一扇窗口它声明 Actor 把结果写到哪里默认数据集、默认键值存储并通过一组内建模板变量生成可直接访问这些输出的 URL。本文将围绕仓库中 output-schema.md 这份权威参考文档展开结合 Apify Actor 开发技能包SKILL.md与配套的 dataset、key-value store、actor.json 参考文档逐项拆解 Output Schema 的结构、字段语义、模板变量体系并给出可复制到.actor/output_schema.json的完整实战配置。读完本文你将能独立为任意 Actor 编写输出声明让 Apify Console 正确呈现运行结果也能在本地与云端正确验证输出。本文所有结论均以仓库内 apify-actor-development 技能包 中的文档与示例为依据该技能包在仓库中存在两份镜像plugins/agentic-awesome-skills-claude/skills/apify-actor-development 与 plugins/agentic-awesome-skills/skills/apify-actor-development内容一致。Output Schema 在 Actor 输出体系中的位置在 Apify 的存储模型中Actor 的运行输出并不直接返回给调用方而是落盘到两类平台级存储中Dataset数据集结构化 JSON 记录流适合爬取结果、列表数据通过Actor.pushData()/Actor.push_data()写入其展示方式由 dataset-schema.md 定义Key-Value Store键值存储任意二进制/文本文件适合 HTML 快照、图片、PDF 等非结构化产出通过Actor.setValue()/Actor.set_value()写入其组织方式由 key-value-store-schema.md 定义。Output Schema 正是在这两套存储 Schema 之上建立的总出口它指明 Actor 将输出存放在哪里并定义访问这些输出的模板。根据 output-schema.md 的说明Apify Console 会直接使用这份输出定义来渲染运行结果界面Run 结果页也就是说——Output Schema 写得对不对直接决定用户在 Console 里能否一键看到成品。从技能包的工作流看SKILL.md 的 Quick Start WorkflowOutput Schema 属于Configure schemas环节的必选项与.actor/input_schema.json、.actor/dataset_schema.json一并更新其标准存放路径为.actor/output_schema.json。Output Schema 的结构定义Output Schema 是一个 JSON 对象由三个顶层字段构成{ actorOutputSchemaVersion: 1, title: OUTPUT-SCHEMA-TITLE, properties: { /* define your outputs here */ } }各字段语义actorOutputSchemaVersion整数必需Output Schema 结构文档的版本号当前仅支持1title字符串必需Output Schema 的标题将展示在 Console 的运行结果区域应使用人类可读的描述性文本properties对象必需输出项的声明集合每个键对应一个输出入口键名通常与存储语义对应如files、dataset。与 input-schema.md 中type: objectproperties的结构风格一致Output Schema 同样采用对象 属性集的声明式结构但每个输出属性不是输入控件定义而是一个指向真实存储位置的模板字符串。完整示例文件爬虫的 Output Schema仓库文档给出了一个文件爬虫files scraper的完整示例它同时展示了键值存储与数据集两个出口{ actorOutputSchemaVersion: 1, title: Output schema of the files scraper, properties: { files: { type: string, title: Files, template: {{links.apiDefaultKeyValueStoreUrl}}/keys }, dataset: { type: string, title: Dataset, template: {{links.apiDefaultDatasetUrl}}/items } } }逐项解读files输出模板{{links.apiDefaultKeyValueStoreUrl}}/keys解析后指向默认键值存储的 API 地址并追加/keys路径段返回该存储下所有键即文件清单。这与技能包中文件爬虫将抓取到的文件写入键值存储的定位吻合——参考 key-value-store-schema.md 中Actor.setValue()保存文本/图片缓冲区的示例键值存储正是文件类产出的归宿dataset输出模板{{links.apiDefaultDatasetUrl}}/items解析后指向默认数据集的 API 地址并追加/items路径段返回数据集中的全部记录。对应Actor.pushData()写入的结构化记录流见 dataset-schema.md 的 JavaScript/Python 示例每个输出属性的type为string模板最终渲染为 URL 字符串title用于 Console 上的展示标签。注意type字段是 Apify Console 渲染模板值所需的类型声明务必保持为string模板中的{{...}}占位符将在运行时被对应的模板变量值替换。模板变量详解links 与 runOutput Schema 之所以能动态生成正确 URL靠的是内置模板变量。根据 output-schema.md 的完整清单模板变量分为两个命名空间links对象——常用 URL 快捷入口变量类型解析后的 URL 格式用途links.publicRunUrlstringhttps://console.apify.com/view/runs/:runId公开的 Run 查看页links.consoleRunUrlstringhttps://console.apify.com/actors/runs/:runIdConsole 中的 Run 页面links.apiRunUrlstringhttps://api.apify.com/v2/actor-runs/:runIdRun 的 API 端点links.apiDefaultDatasetUrlstringhttps://api.apify.com/v2/datasets/:defaultDatasetId默认数据集的 API 端点links.apiDefaultKeyValueStoreUrlstringhttps://api.apify.com/v2/key-value-stores/:defaultKeyValueStoreId默认键值存储的 API 端点links.containerRunUrlstringhttps://containerId.runs.apify.net/运行容器内 Web 服务器的地址standby 模式下尤其有用run对象——当前 Run 的元数据run对象的字段与GET RunAPI 端点返回的运行信息一致常用字段包括run.defaultDatasetIdstring默认数据集的 IDrun.defaultKeyValueStoreIdstring默认键值存储的 ID。run命名空间的价值在于当你想在输出中直接拼出存储 ID而不是依赖links的快捷 URL时可以写成{{run.defaultDatasetId}}。例如一个更底层的 dataset 输出模板可以是{ type: string, title: Dataset (raw ID), template: https://api.apify.com/v2/datasets/{{run.defaultDatasetId}}/items }组合使用建议优先使用links.*它把 URL 拼装细节域名、路径前缀、ID 注入全部封装好且与文档示例保持一致最不易出错需要引用非默认存储或做自定义拼装时使用run.defaultDatasetId/run.defaultKeyValueStoreId作为原材料links.containerRunUrl仅在 Actor 内运行了 HTTP 服务典型场景是 standby-mode.md 描述的 standby 模式Actor 像实时 Web/API 服务器一样常驻等待请求时才有意义。将 Output Schema 接入 Actor 项目1. 在 actor.json 中声明引用actor.json.actor/actor.json通过output字段指向 Output Schema 文件同时可在storages中声明 dataset / key-value store 的存储 Schema——三者共同构成完整的输出声明链。参考 actor-json.md 的结构{ actorSpecification: 1, name: project-cheerio-crawler-javascript, title: Project Cheerio Crawler Javascript, description: Crawlee and Cheerio project in javascript., version: 0.0, meta: { templateId: js-crawlee-cheerio, generatedBy: Claude Code with Claude Sonnet 4.5 }, input: ./input_schema.json, output: ./output_schema.json, storages: { dataset: ./dataset_schema.json }, dockerfile: ../Dockerfile }要点output指向.actor/output_schema.jsonstorages.dataset/storages.keyValueStore分别指向 dataset 与键值存储 Schema 文件Output Schema 里的{{links.apiDefaultDatasetUrl}}、{{links.apiDefaultKeyValueStoreUrl}}正是为这些默认存储生成访问地址按技能包要求SKILL.md 开头的重要提示meta.generatedBy必须填写你实际使用的工具与模型如Claude Code with Claude Sonnet 4.5用于 Apify 追踪 AGENTS.md 的改进。2. 本地验证与云端部署技能包明确要求本地测试必须用apify run而不是npm start/npx apify run等命令因为只有apify run才会正确配置 Apify 运行环境与本地存储。完整流程为apify run # 本地运行写入 storage/ 目录本地专用不会同步到 Console apify push # 部署到 Apify 平台Actor 名取自 .actor/actor.json 的 name 字段两条重要事实需要牢记来源SKILL.md 的 Local Testing 一节apify run产生的数据集、键值存储、请求队列只存在于本地storage/目录永远不会自动上传要验证 Output Schema 在 Console 上的渲染效果必须apify push后在平台运行再查看 Run 结果页。因此本地验证输出时请检查storage/目录或 Actor 日志而不是去 Console 找结果云端验证时再关注 Console 的 Output 标签页是否按模板正确渲染出数据集/文件列表入口。与 Dataset、Key-Value Store Schema 的分工边界为了避免混淆需要厘清三份输出相关Schema 各自的职责Schema 文件定义内容谁消费它.actor/output_schema.json本文主题输出存放在哪里 访问输出的模板 URLApify Console 的 Run 结果页.actor/dataset_schema.json数据集记录的结构、转换与表格视图展示Console 的 Output 标签页数据集视图.actor/key_value_store_schema.json键值存储中键的分组collections、类型校验Console 的键值存储浏览三者是叠加而非替代关系dataset schema 决定数据集里的每条记录长什么样、怎么显示如views.transformation.fields决定列顺序display.properties.字段.format支持text|number|date|link|boolean|image|array|object八种展示格式详见 dataset-schema.mdkey-value store schema 通过collections.name.keyPrefix把键按前缀归类如document-、image-并用contentTypes限制允许的 MIME 类型见 key-value-store-schema.md而 Output Schema 站在最上层用模板变量把默认数据集 / 默认键值存储的整体访问入口暴露给用户。实战检查清单与常见误区写作 Output Schema 时建议按以下清单自检✅actorOutputSchemaVersion设置为1title使用可读描述✅ 每个输出属性type为stringtemplate以{{开头且引用的变量名拼写正确links.apiDefaultDatasetUrl、links.apiDefaultKeyValueStoreUrl是最常用的两个✅ 文件类产出通过.../keys暴露键清单记录类产出通过.../items暴露数据✅.actor/actor.json中output与storages路径正确generatedBy已填写✅ 用apify run本地验证、apify push部署后在 Console 复核模板渲染结果❌ 不要混淆Output Schema 不是 dataset schemaproperties里放的是模板 URL不是字段格式化定义❌ 不要使用console.log()/print()代替 Apify 日志会绕过凭据脱敏详见 logging.md。遵循以上规范你的 Actor 输出就能在 Apify 平台上开箱即见——用户从 Run 结果页一键直达数据集与文件清单这正是 Output Schema 设计的最终目的。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考