field-service-sobject-create-configure

管理 Sfs Sobject Create

何时使用此技能

通过 Headless 360 REST API 创建 sObject 记录。介绍整个流程（描述 → 查询 → 创建）、Field Service 数据模型 DAG、字段要求、插入顺序和常见问题。创建 Skill、WorkType、SkillRequirement 或其他 Field Service sObject 时可参考。

工作流

通过 headless-360 创建 sObject 记录

积极提供帮助——在创建记录之前，先了解业务背景。考虑要创建的 sObject 所属的业务领域，并通过简短、结构化的问题（询问／原因／影响）逐步澄清，直到没有会影响创建内容的歧义。对于根据上下文或现有数据已显而易见的答案，跳过相关问题。

流程

阶段 1：描述 — dispatch_readonly GET /services/data/v67.0/sobjects/<SObject>/describe

阶段 2：查询现有记录 — 了解组织的数据结构……

dispatch_readonly GET /services/data/v67.0/query， queryParams.q = "SELECT <required + picklist fields> FROM <SObject> ORDER BY CreatedDate DESC LIMIT 20"。 用它来匹配命名和值的约定，查看哪些可选字段实际有值， 检查重复记录，并在尝试创建之前确认是否有写入权限。

阶段 3：创建 — 使用 dispatch POST 创建记录。单个……

数据模型 DAG

示例（Field Service 连接对象模式——同一模式适用于任何基于数据形状的 sObject DAG）：

Skill (0C5)    WorkType (08q)    ← roots (parallel)
    └──────────┬──────────┘
       SkillRequirement (0Hx)     ← junction (last)

字段和插入顺序

检查 describe 中的 fields[]，筛选出 createable:true（其余字段跳过——describe 内容很多）。同时满足 nillable:false 和 defaultedOnCreate:false 的字段为必填字段（由平台填充的默认字段可省略）。分两类：

• 标量 → 将其值放入创建请求正文。
• type:"reference" → 外键。如果 nillable:false（硬性依赖），先在 referenceTo[] 中创建父记录。多态引用会列出多个对象——选择其中一个。按拓扑顺序排序：先处理根节点，再将每个 id 传给依赖记录。nillable:true 引用为可选字段，可稍后 PATCH。

常见问题：

• 基础 sObject CRUD 不在 discover 语料库中——跳过 discover，直接执行 describe → dispatch。
• 写入时出现 CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY → 该 sObject 禁止通过 sObject-REST 写入 （例如 ExternalDataSource、CustomPermission）；请改用 Tooling/Metadata API。
• 400/403 → 通常是网关用户的 CRUD/FLS/共享权限不足，而不是请求正文有误——不要盲目重试请求正文。

示例 — WorkType

对 WorkType 执行 describe，并根据规则检查 fields[]。返回的 createable:true、nillable:false、defaultedOnCreate:false 字段就是必填字段—— 根据这些字段构建请求正文，不要假定字段名称。然后查询几个现有的 WorkType，了解约定并检查重复记录。之后根据推导出的请求正文创建记录，例如：

{ "url": "/services/data/v67.0/sobjects/WorkType", "method": "POST",
  "body": { "Name": "Standard Repair", "EstimatedDuration": 2 } }

───── 运行时上下文（Headless 360 / agentic）： 在 Headless 360 / agentic 环境中运行此技能时，尽可能优先使用平台 dispatch 工具（托管 Headless 360 MCP 中的 dispatch；本地开发 MCP 中的 dispatch），而不是 CLI 工具（sf project deploy、sfdx、shell 命令）。可用操作列于下方的 steps: 中；每项操作都已通过实时组织验证。请对规范路径调用 dispatch 工具。仅当某项能力没有对应 API 路径时，才可回退使用 CLI。

关键约束

前提条件：

• 目标 sObject 可创建，且不在 sObject-REST 屏蔽列表中。（检查：GET /services/data/v67.0/sobjects/{N}/describe 返回 createable: true，位于顶层。POST 返回 CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY表示该 sObject 会屏蔽基础 REST 写入（例如ExternalDataSource、CustomPermission`）——请改用 Tooling 或 Metadata API。）
• 网关用户拥有所需的对象 CRUD 权限，以及相关字段级安全性（FLS）权限。（检查：POST 返回 400 / 403 和 INSUFFICIENT_ACCESS_OR_READONLY → CRUD/FLS 权限缺失，而不是载荷错误。为用户的配置文件 / 权限集授予该实体的 Create 权限，以及正文中每个字段的 Edit 访问权限。）
• 对于复合 / 图事务，调用方已在每个图节点的 records 中独立按拓扑顺序将父记录排在子记录之前。（检查：与 @{...} 一起使用的 ``referenceId必须引用同一图中更早出现的记录。顺序错误会导致子节点出现INVALID_REFERENCE_ID`，并使整个图以原子方式回滚。）

操作参考

按用途对操作分组。将这些操作用作上述工作流的构建模块。

摘要

操作	用途	状态	调用	依赖项
describe-sobject	读取	—	GET /services/data/v67.0/sobjects/{SObjectName}/describe	—
query-existing-records	读取	—	GET /services/data/v67.0/query	describe-sobject
create-sobject-record	写入	—	POST /services/data/v67.0/sobjects/{SObjectName}	describe-sobject
composite-graph-create	写入	—	POST /services/data/v67.0/composite/graph	describe-sobject
update-sobject-record	写入	—	PATCH /services/data/v67.0/sobjects/{SObjectName}/{Id}	create-sobject-record
delete-sobject-record	写入	—	DELETE /services/data/v67.0/sobjects/{SObjectName}/{Id}	—

依赖关系图

graph TD
  describe_sobject["describe-sobject (read)"]
  query_existing_records["query-existing-records (read)"]
  create_sobject_record["create-sobject-record (write)"]
  composite_graph_create["composite-graph-create (write)"]
  update_sobject_record["update-sobject-record (write)"]
  delete_sobject_record["delete-sobject-record (write)"]
  describe_sobject --> query_existing_records
  describe_sobject --> create_sobject_record
  describe_sobject --> composite_graph_create
  create_sobject_record --> update_sobject_record

读取操作

describe-sobject

获取 {SObjectName} 的字段目录。扫描 fields[]，查找 createable:true；同时满足 nillable:false 和 defaultedOnCreate:false 的字段为硬性必填字段。type:"reference" 字段为外键（FK）——当 nillable:false 时属于硬性依赖。基础 sObject CRUD 不在发现语料范围内（技能 §Pitfalls）；Agent 必须跳过 discover，直接调用 describe。

调用： GET /services/data/v67.0/sobjects/{SObjectName}/describe

输入：

• SObjectName （string） — sObject 的 API 名称（例如 WorkType、Skill、SkillRequirement）。路径段。

输出： SObjectDescribeSObjectResult。关键字段：createable、updateable、deletable、fields[]（每项包含 name、type、createable、nillable、defaultedOnCreate、referenceTo[]、picklistValues[]）。载荷很大（WorkType 超过 60KB）——推理前请筛选出 createable:true 的字段。

query-existing-records

预先读取少量现有记录，以匹配命名约定、发现重复项，并在执行创建操作前确认写入权限。技能 §Flow.2 建议使用以下 SOQL： SELECT <required + picklist fields> FROM <SObject> ORDER BY CreatedDate DESC LIMIT 20。

调用： GET /services/data/v67.0/query

输入：

• q （string） — SOQL 查询。通过 queryParams.q 传递（传输时进行 URL 编码）。建议将用于扫描约定的窗口设为 LIMIT 20 或更少。

依赖项： describe-sobject

输出： {totalSize, done, records: [<row>]}。records[] 是 Agent 用于扫描约定的数据结构。当结果超过 200 条时会显示 done:false 和 nextRecordsUrl——在 LIMIT 20 的情况下无需关注。

写入操作

create-sobject-record

创建一条记录。请求体中只能包含通过 describe 确认为 createable:true 的字段。对于 DAG（父记录 + 子记录 + 关联记录），建议使用 composite/graph，以便所有行在一个事务中 原子性写入。201 → {id, success, errors:[]}；非 2xx 返回 [{errorCode, message, fields:[]}]。

调用： POST /services/data/v67.0/sobjects/{SObjectName}

输入：

• SObjectName (string) — sObject 的 API 名称（路径段）。
• body (object) — 字段/值映射。只包含通过 describe 确认为 createable:true 的字段；省略 defaultedOnCreate:true 字段（平台会填充这些字段）。

依赖： describe-sobject

输出： 201 → {id: "<15/18-char id>", success: true, errors: []}。4xx → {errorCode, message, fields} 数组。

回滚： delete-sobject-record

注意： 错误约定：

• CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY → sObject 会阻止基础 REST 写入；请改用 Tooling / Metadata API。常见于 ExternalDataSource、CustomPermission。
• INSUFFICIENT_ACCESS_OR_READONLY → 网关用户存在 CRUD/FLS/共享权限问题；不要使用相同请求体重试。
• REQUIRED_FIELD_MISSING → 重新检查 describe 筛选条件（某些 字段仅在特定记录类型中才是 createable 且 nillable:false）。
• INVALID_FIELD_FOR_INSERT_UPDATE → 字段不是 createable:true；请从请求体中移除。

composite-graph-create

在一个事务中原子性地创建一组相关记录构成的 DAG。 Skill §Data-model-DAG 示例：Skill + WorkType（根节点）→ SkillRequirement（关联记录）。在每条记录上使用 referenceId， 并在子记录的 FK 字段中使用 @{parentRef.id}，以便在写入 时绑定。成功时返回 200，其中包含每个节点的 compositeResponse[] 条目，并带有各子项的 201 状态。任何失败都会回滚 整个图。

调用： POST /services/data/v67.0/composite/graph

输入：

• body (object) — {graphs: [{graphId, compositeRequest: [{referenceId, method:"POST", url:"/services/data/v67.0/sobjects/<N>", body:{...}}, ...]}]}。一次调用可以包含多个图； 每个图的原子性相互独立。

依赖： describe-sobject

输出： 200 → {graphs: [{graphId, graphResponse: {compositeResponse: [{body:{id, success, errors}, httpHeaders, httpStatusCode, referenceId}]}, isSuccessful}]}。任何失败时，isSuccessful:false，并返回各子项的 4xx 响应体。

回滚： delete-sobject-record

注意： 错误约定：

• INVALID_REFERENCE_ID → 子记录引用了数组中位于它之后的 referenceId，或引用的 ID 不存在。请按拓扑顺序 对 compositeRequest[] 排序，确保父记录在前。
• LIMIT_EXCEEDED → composite/graph 每个图最多包含 500 条记录，每次调用最多包含 75 个图。
• MIXED_DML_OPERATION → **该图在同一事务中混用了设置对象 sObject（例如 Skill、Group、User、Permission*）与 非设置对象 sObject（例如 WorkType、Account、Contact）—— 即使在 composite/graph 中，平台也禁止此类操作。**拆分为两次调用：在第 1 次调用中创建设置对象侧记录并记录其 ID，然后在第 2 次调用中创建非设置对象侧记录及 引用该 ID 的关联记录。该技能中的 Skill+WorkType+SkillRequirement 示例必须按此方式拆分。
• 任何子项出现 HTTP 4xx → 该图的整个 compositeResponse 都会回滚；同级子项会报告 PROCESSING_HALTED，失败的图无需执行 DELETE 清理。

update-sobject-record

更新现有记录中的字段。用于延迟绑定 nillable:true 引用关联（技能 §Fields-and- insertion-order）或修正。PATCH 会合并字段，而非 完全替换：仅修改请求正文中的字段；未提供的字段保持不变。成功时返回 204（无响应正文）。

调用： PATCH /services/data/v67.0/sobjects/{SObjectName}/{Id}

输入：

• SObjectName (string)
• Id (string) — 15 或 18 个字符的记录 ID（路径段）。
• body (object) — 字段/值映射。仅包含 describe 中 updateable:true 的字段。

依赖： create-sobject-record

输出： 成功时返回 204 No Content。4xx → 与 POST 相同的 [{errorCode, message, fields}] 格式。

delete-sobject-record

删除记录。用于回滚单个 create-sobject-record 和 composite-graph-create 的目标（事务成功但后续验证失败的子记录）。 成功时返回 204。注意：composite/graph 失败时会原子回滚 — 只有在 SUCCESSFUL graph 后续验证未通过时，才需要 DELETE。

调用： DELETE /services/data/v67.0/sobjects/{SObjectName}/{Id}

输入：

• SObjectName (string)
• Id (string)

输出： 204 No Content。404 → ID 已不存在（幂等）；视为成功。