datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-03-003-02-api.md

API 文档 - 元数据类型定义

元数据

• 需求编号：003-02
• 创建时间：2026-02-03
• 创建人：AI Assistant
• 版本号：v1.0.0

API 概述

元数据类型定义 API 提供 7 种 Salesforce 元数据类型的部署功能，包括自定义对象、自定义字段、Apex 类、Apex 触发器、Visualforce 页面、Visualforce 组件、Flow。同时提供部署日志查询功能，用于查看历史部署记录。

接口列表

1. 部署自定义对象

• 功能描述：将自定义对象定义部署到 Salesforce 组织

• 请求方式：POST

• 请求路径：/salesforce/metadata/type/customObject

• 权限要求：metadata:type:deploy

• 请求参数：

  参数名	类型	必填	说明
  customObject	Object	是	自定义对象定义，包含 fullName、label、pluralLabel、fields 等属性
  deployOptions	Object	是	部署选项，包含 allowMissingFiles、autoUpdatePackage、checkOnly 等属性

• 请求示例：

  {
    "customObject": {
      "fullName": "MyCustomObject__c",
      "label": "My Custom Object",
      "pluralLabel": "My Custom Objects",
      "nameField": {
        "type": "Text",
        "label": "Name"
      }
    },
    "deployOptions": {
      "allowMissingFiles": false,
      "autoUpdatePackage": false,
      "checkOnly": false,
      "ignoreWarnings": false,
      "performRetrieve": false,
      "purgeOnDelete": false,
      "rollbackOnError": true,
      "singlePackage": true,
      "testLevel": "NoTestRun"
    }
  }
  

• 响应参数：

  参数名	类型	说明
  code	Integer	状态码（200 成功，其他失败）
  msg	String	提示信息
  data.success	Boolean	是否成功
  data.id	String	部署 ID
  data.numberComponentErrors	Integer	组件错误数
  data.numberComponentsDeployed	Integer	部署的组件数
  data.numberTestErrors	Integer	测试错误数
  data.numberTestsCompleted	Integer	完成的测试数
  data.errorMessage	String	错误消息（如果有）

• 成功响应示例：

  {
    "code": 200,
    "msg": "部署自定义对象成功",
    "data": {
      "success": true,
      "id": "04sXXXXXXXXXXXXXXX",
      "numberComponentErrors": 0,
      "numberComponentsDeployed": 1,
      "numberTestErrors": 0,
      "numberTestsCompleted": 0
    }
  }
  

• 失败响应示例：

  {
    "code": 500,
    "msg": "部署自定义对象失败: 连接超时",
    "data": null
  }
  

2. 部署自定义字段

• 功能描述：将自定义字段定义部署到 Salesforce 组织

• 请求方式：POST

• 请求路径：/salesforce/metadata/type/customField

• 权限要求：metadata:type:deploy

• 请求参数：

  参数名	类型	必填	说明
  customField	Object	是	自定义字段定义，包含 fullName、label、type、length 等属性
  objectType	String	是	对象类型，如 "Account"、"Contact"、"MyCustomObject__c"
  deployOptions	Object	是	部署选项

• 请求示例：

  {
    "customField": {
      "fullName": "MyField__c",
      "label": "My Field",
      "type": "Text",
      "length": 255
    },
    "objectType": "Account",
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "NoTestRun"
    }
  }
  

• 响应参数：同"部署自定义对象"接口

3. 部署 Apex 类

• 功能描述：将 Apex 类部署到 Salesforce 组织

• 请求方式：POST

• 请求路径：/salesforce/metadata/type/apexClass

• 权限要求：metadata:type:deploy

• 请求参数：

  参数名	类型	必填	说明
  apexClass	Object	是	Apex 类定义，包含 fullName、apiVersion、status、body 等属性
  deployOptions	Object	是	部署选项

• 请求示例：

  {
    "apexClass": {
      "fullName": "MyApexClass",
      "apiVersion": 58.0,
      "status": "Active",
      "body": "public class MyApexClass {\n    public static void myMethod() {\n        System.debug('Hello World');\n    }\n}"
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "RunLocalTests"
    }
  }
  

• 响应参数：同"部署自定义对象"接口

4. 部署 Apex 触发器

• 功能描述：将 Apex 触发器部署到 Salesforce 组织

• 请求方式：POST

• 请求路径：/salesforce/metadata/type/apexTrigger

• 权限要求：metadata:type:deploy

• 请求参数：

  参数名	类型	必填	说明
  apexTrigger	Object	是	Apex 触发器定义，包含 fullName、apiVersion、status、object、body 等属性
  deployOptions	Object	是	部署选项

• 请求示例：

  {
    "apexTrigger": {
      "fullName": "MyApexTrigger",
      "apiVersion": 58.0,
      "status": "Active",
      "object": "Account",
      "body": "trigger MyApexTrigger on Account (before insert) {\n    for (Account acc : Trigger.new) {\n        acc.Name = 'Updated';\n    }\n}"
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "RunLocalTests"
    }
  }
  

• 响应参数：同"部署自定义对象"接口

5. 部署 Visualforce 页面

• 功能描述：将 Visualforce 页面部署到 Salesforce 组织

• 请求方式：POST

• 请求路径：/salesforce/metadata/type/apexPage

• 权限要求：metadata:type:deploy

• 请求参数：

  参数名	类型	必填	说明
  apexPage	Object	是	Visualforce 页面定义，包含 fullName、apiVersion、label、markup 等属性
  deployOptions	Object	是	部署选项

• 请求示例：

  {
    "apexPage": {
      "fullName": "MyVisualforcePage",
      "apiVersion": 58.0,
      "label": "My Visualforce Page",
      "markup": "<apex:page>\n    <h1>Hello World</h1>\n</apex:page>"
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "NoTestRun"
    }
  }
  

• 响应参数：同"部署自定义对象"接口

6. 部署 Visualforce 组件

• 功能描述：将 Visualforce 组件部署到 Salesforce 组织

• 请求方式：POST

• 请求路径：/salesforce/metadata/type/apexComponent

• 权限要求：metadata:type:deploy

• 请求参数：

  参数名	类型	必填	说明
  apexComponent	Object	是	Visualforce 组件定义，包含 fullName、apiVersion、label、markup 等属性
  deployOptions	Object	是	部署选项

• 请求示例：

  {
    "apexComponent": {
      "fullName": "MyVisualforceComponent",
      "apiVersion": 58.0,
      "label": "My Visualforce Component",
      "markup": "<apex:component>\n    <h1>Component Content</h1>\n</apex:component>"
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "NoTestRun"
    }
  }
  

• 响应参数：同"部署自定义对象"接口

7. 部署 Flow

• 功能描述：将 Flow 定义部署到 Salesforce 组织

• 请求方式：POST

• 请求路径：/salesforce/metadata/type/flow

• 权限要求：metadata:type:deploy

• 请求参数：

  参数名	类型	必填	说明
  flow	Object	是	Flow 定义，包含 fullName、apiVersion、label、processType、start 等属性
  deployOptions	Object	是	部署选项

• 请求示例：

  {
    "flow": {
      "fullName": "MyFlow",
      "apiVersion": 58.0,
      "label": "My Flow",
      "processType": "AutoLaunchedFlow",
      "start": {
        "connector": {
          "targetReference": "myAction"
        }
      }
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "NoTestRun"
    }
  }
  

• 响应参数：同"部署自定义对象"接口

8. 查询部署日志

• 功能描述：查询元数据部署操作的历史记录

• 请求方式：GET

• 请求路径：/salesforce/metadata/type/logs

• 权限要求：metadata:type:logs

• 请求参数：无

• 响应参数：

  参数名	类型	说明
  code	Integer	状态码（200 成功，其他失败）
  msg	String	提示信息
  data	Array	部署日志列表
  data[].id	Long	日志 ID
  data[].operationType	String	操作类型（DEPLOY_CUSTOM_OBJECT、DEPLOY_CUSTOM_FIELD 等）
  data[].metadataType	String	元数据类型（CustomObject、CustomField 等）
  data[].metadataName	String	元数据名称
  data[].deployId	String	部署 ID
  data[].status	String	部署状态（Queued、InProgress、Succeeded、Failed、Cancelled、Timeout）
  data[].numberComponentErrors	Integer	组件错误数
  data[].numberComponentsDeployed	Integer	部署的组件数
  data[].numberTestErrors	Integer	测试错误数
  data[].numberTestsCompleted	Integer	完成的测试数
  data[].errorMessage	String	错误消息
  data[].operationTime	String	操作时间（格式：yyyy-MM-dd HH:mm:ss）

• 成功响应示例：

  {
    "code": 200,
    "msg": "操作成功",
    "data": [
      {
        "id": 1,
        "operationType": "DEPLOY_CUSTOM_OBJECT",
        "metadataType": "CustomObject",
        "metadataName": "MyCustomObject__c",
        "deployId": "04sXXXXXXXXXXXXXXX",
        "status": "Succeeded",
        "numberComponentErrors": 0,
        "numberComponentsDeployed": 1,
        "numberTestErrors": 0,
        "numberTestsCompleted": 0,
        "operationTime": "2026-02-03 10:30:00"
      }
    ]
  }
  

错误码

错误码	说明	处理建议
200	操作成功	无需处理
500	服务器内部错误	检查服务器日志，联系管理员
401	未授权	检查用户是否登录，是否有权限
403	禁止访问	检查用户是否有相应权限
404	资源不存在	检查请求路径是否正确
400	请求参数错误	检查请求参数是否符合要求
408	请求超时	检查网络连接，稍后重试

部署选项说明

DeployOptions 参数

参数名	类型	默认值	说明
allowMissingFiles	Boolean	false	是否允许缺失文件
autoUpdatePackage	Boolean	false	是否自动更新包
checkOnly	Boolean	false	是否仅检查（不实际部署）
ignoreWarnings	Boolean	false	是否忽略警告
performRetrieve	Boolean	false	是否执行检索
purgeOnDelete	Boolean	false	是否在删除时清除
rollbackOnError	Boolean	true	是否在错误时回滚
runTests	String[]	null	运行的测试列表
singlePackage	Boolean	true	是否为单包
testLevel	String	"NoTestRun"	测试级别（NoTestRun、RunSpecifiedTests、RunLocalTests、RunAllTestsInOrg）

注意事项

1. 部署超时：部署操作可能需要较长时间（最多 5 分钟），请确保客户端设置合理的超时时间。

2. 并发部署：建议避免同时部署多个元数据，以免产生冲突。

3. 测试级别：对于 Apex 类和触发器的部署，建议设置适当的测试级别（RunLocalTests 或 RunAllTestsInOrg）。

4. 错误处理：部署失败时，请查看响应中的 errorMessage 字段获取详细错误信息。

5. 日志查询：部署日志会异步记录，可能需要等待几秒钟才能查询到最新的部署记录。

相关文档

• 需求文档
• 设计文档
• 决策记录
• SQL 脚本
• 提示词文档
• 会话记录
• 变更日志
• 复盘文档