OAS Objects Reference & SFDC Extensions

好，我们来看一下这一页内容，它讲的是如果你想让一个Apex REST API变成Agentforce里可以直接调用的动作，那你写OpenAPI规范的时候，有一些非常严格的格式要求。这些要求不难理解，但如果你不了解，可能就会卡住。 首先，记住一个固定地址：所有这种对外的REST服务的服务器地址，必须是单一个的 `/services/apexrest`。你不能自己随便写一个别的路径，Salesforce强制要求所有通过Apex暴露出来的REST接口，都要放在这个入口下。 接下来，路径这一项，必须和你Apex类上用 `@RestResource(urlMapping='...')` 声明的那个路径完全一致。注意，是完全一样，大小写、斜杠什么的一个字都不能错。 另外还有一点要注意，有些常见的OpenAPI字段是不允许出现在这里的。比如说，路径项里不能有 `server`，操作的设置里不能有 `callback`，参数里不能出现 `cookie` 类型的参数。你写规范的时候直接把这些避开就行。 为了能让Salesforce识别出这个动作是可以在Agent里面用的，我们还需要用到一组Salesforce自己提供的扩展字段。这些字段都以 `x-sfdc` 开头，相当于是给标准OpenAPI加上了Salesforce专用的标记。 这里面最重要的有四个： - `x-sfdc-isAgentAction`，这是必须设置的，而且值一定要是true，它告诉平台“这是一个代理可调用的动作”。 - `x-sfdc-isUserInput`，也是必须的，用来标记哪些字段是需要由用户自然语言来提供输入的。 - `x-sfdc-isDisplayable`，还是必须的，控制这个动作的输出能不能在前端直接展示给用户。 - `x-sfdc-isPii`，这个是可选的，如果你的动作会处理个人敏感信息，就要标上。 最后一点，你要在Salesforce里创建一个“外部服务注册”的元数据，也就是`ExternalServiceRegistration`，把刚才写好的那个OpenAPI规范登记进去，并且把它的`registrationProviderType`设置成`Custom`。这样一来，这个API才会出现在API目录里，也才会被Agent识别成可以执行的动作。 概括一下，核心就是四件事：服务器地址固定用 `/services/apexrest`；路径要跟代码里的urlMapping一模一样；避开那几个禁止的参数字段；必填那三个Salesforce扩展标记。做到了，你的Apex REST就能无缝变成一个代理的动作了。