175 lines
3.8 KiB
Markdown
175 lines
3.8 KiB
Markdown
|
# 执行 SOQL 查询
|
|||
|
|
|
|||
|
|
## 接口概述
|
|||
|
|
|
|||
|
|
执行标准的 SOQL (Salesforce Object Query Language) 查询语句，从 Salesforce 获取数据。
|
|||
|
|
|
|||
|
|
## 基本信息
|
|||
|
|
|
|||
|
|
| 属性 | 值 |
|
|||
|
|
|------|-----|
|
|||
|
|
| 接口名称 | 执行 SOQL 查询 |
|
|||
|
|
| 接口路径 | `/partner/query` |
|
|||
|
|
| 请求方法 | `POST` |
|
|||
|
|
| Content-Type | `application/json` |
|
|||
|
|
| 需要认证 | 是 |
|
|||
|
|
| 所属模块 | datai-salesforce-partner |
|
|||
|
|
|
|||
|
|
## 请求参数
|
|||
|
|
|
|||
|
|
### 请求体 (Request Body)
|
|||
|
|
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
|||
|
|
|--------|------|------|------|--------|
|
|||
|
|
| soql | String | 是 | SOQL 查询语句 | `SELECT Id, Name FROM Account LIMIT 10` |
|
|||
|
|
| batchSize | Integer | 否 | 批次大小，默认 500，最大 2000 | `500` |
|
|||
|
|
|
|||
|
|
### 请求示例
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"soql": "SELECT Id, Name, BillingCity, Industry FROM Account WHERE Industry = 'Technology' LIMIT 10",
|
|||
|
|
"batchSize": 500
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 响应参数
|
|||
|
|
|
|||
|
|
### 响应体 (Response Body)
|
|||
|
|
|
|||
|
|
| 参数名 | 类型 | 说明 |
|
|||
|
|
|--------|------|------|
|
|||
|
|
| code | Integer | 响应状态码，200 表示成功 |
|
|||
|
|
| msg | String | 响应消息 |
|
|||
|
|
| data | Object | 响应数据 |
|
|||
|
|
|
|||
|
|
### data 对象结构
|
|||
|
|
|
|||
|
|
| 参数名 | 类型 | 说明 |
|
|||
|
|
|--------|------|------|
|
|||
|
|
| records | Array | 记录列表，每个记录是一个键值对对象 |
|
|||
|
|
| queryLocator | String | 查询定位器，用于 QueryMore 获取下一页 |
|
|||
|
|
| done | Boolean | 是否完成（true 表示没有更多数据） |
|
|||
|
|
| size | Integer | 记录数量 |
|
|||
|
|
| success | Boolean | 是否成功 |
|
|||
|
|
| errors | Array | 错误信息列表 |
|
|||
|
|
|
|||
|
|
### 响应示例
|
|||
|
|
|
|||
|
|
**成功响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"msg": "操作成功",
|
|||
|
|
"data": {
|
|||
|
|
"records": [
|
|||
|
|
{
|
|||
|
|
"Id": "001xx000003DHb2AAG",
|
|||
|
|
"Name": "Acme Corporation",
|
|||
|
|
"BillingCity": "San Francisco",
|
|||
|
|
"Industry": "Technology"
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"Id": "001xx000003DHb3AAH",
|
|||
|
|
"Name": "Tech Solutions Inc",
|
|||
|
|
"BillingCity": "New York",
|
|||
|
|
"Industry": "Technology"
|
|||
|
|
}
|
|||
|
|
],
|
|||
|
|
"queryLocator": "01gD0000002J6ozIAC-2000",
|
|||
|
|
"done": false,
|
|||
|
|
"size": 2,
|
|||
|
|
"success": true,
|
|||
|
|
"errors": []
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**错误响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 500,
|
|||
|
|
"msg": "SOQL 查询失败: Invalid query",
|
|||
|
|
"data": null
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 错误码
|
|||
|
|
|
|||
|
|
| 错误码 | 说明 | 处理建议 |
|
|||
|
|
|--------|------|----------|
|
|||
|
|
| 400 | 请求参数错误 | 检查 soql 语句格式是否正确 |
|
|||
|
|
| 401 | 认证失败 | 检查 Salesforce 认证信息是否有效 |
|
|||
|
|
| 500 | 服务器内部错误 | 检查 SOQL 语句语法是否正确 |
|
|||
|
|
|
|||
|
|
## 使用说明
|
|||
|
|
|
|||
|
|
### SOQL 语法示例
|
|||
|
|
|
|||
|
|
1. **基本查询**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"soql": "SELECT Id, Name FROM Account"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
2. **带条件查询**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"soql": "SELECT Id, Name, BillingCity FROM Account WHERE Industry = 'Technology' AND BillingCity = 'San Francisco'"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
3. **排序和限制**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"soql": "SELECT Id, Name, CreatedDate FROM Account ORDER BY CreatedDate DESC LIMIT 10"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
4. **关联查询**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"soql": "SELECT Id, Name, Account.Name, Account.Industry FROM Contact WHERE Account.Industry = 'Technology'"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
5. **聚合查询**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"soql": "SELECT Industry, COUNT(Id) FROM Account GROUP BY Industry"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 分页处理
|
|||
|
|
|
|||
|
|
当查询结果超过批次大小时，使用返回的 `queryLocator` 调用 `queryMore` 接口获取下一页数据。
|
|||
|
|
|
|||
|
|
### 注意事项
|
|||
|
|
|
|||
|
|
1. SOQL 语句必须以 `SELECT` 开头
|
|||
|
|
2. 批次大小范围：1-2000，默认 500
|
|||
|
|
3. 查询结果最大记录数限制为 50,000
|
|||
|
|
4. 复杂查询可能超时，建议添加适当的过滤条件和 LIMIT
|
|||
|
|
5. 字段名区分大小写
|
|||
|
|
6. 字符串值需要用单引号包裹
|
|||
|
|
|
|||
|
|
## 相关接口
|
|||
|
|
|
|||
|
|
- [获取查询结果的下一页](./003-query-more.md)
|
|||
|
|
- [查询所有记录（包括已删除的）](./002-query-all.md)
|
|||
|
|
- [执行 SOSL 搜索](./004-search.md)
|
|||
|
|
|
|||
|
|
## 更新日志
|
|||
|
|
|
|||
|
|
| 版本 | 日期 | 更新内容 | 作者 |
|
|||
|
|
|------|------|----------|------|
|
|||
|
|
| 1.0.0 | 2026-01-30 | 初始版本 | AI Assistant |
|