SAP Business One Service Layer 介绍

一、基本概念

SAP Business One Service Layer 是 SAP Business One 的新一代扩展 API，旨在提供统一、高效的方式访问和操作 SAP Business One 的数据与服务。它基于 HTTP 和 OData 协议（支持 OData 版本 3 和 4），构建在 Apache HTTP 服务器上，具备高可扩展性和高可用性，可适配 SAP Business One 9.1、9.2、9.3、10.0 等版本（包括基于 SAP HANA 和 Microsoft SQL Server 的部署）。

从架构上看，Service Layer 采用三层架构：

• 客户端层：通过 HTTP/OData 协议与 Web 服务器通信（支持 HTML5、移动应用等多端客户端）；
• Web 服务器层：核心组件包括 OData 解析器（处理请求并转换为业务对象操作）、DI Core（与 SAP Business One 对象交互的接口）、会话管理器（实现会话粘性，配合负载均衡）、OBServer（处理业务逻辑，如税务计算、过账等）；
• 数据层：依赖 SAP HANA 或 Microsoft SQL Server 数据库实现数据持久化。
• 
  

二、适用场景

Service Layer 适用于以下场景，目标受众包括系统管理员、软件开发人员及企业 IT 规划者：

• 应用开发：开发基于 Service Layer API 的企业级应用（如自定义业务系统、移动端应用），实现与 SAP Business One 的数据交互；
• 系统部署优化：规划负载均衡部署，提升系统并发处理能力；
• 性能与稳定性保障：在高负载场景下确保系统稳定运行，优化查询与事务处理效率；
• 集成需求：与第三方系统（如 CRM、电商平台）集成，通过标准 OData 协议实现数据同步；
• 扩展定制：利用 JavaScript 扩展、用户定义对象（UDO）等功能，满足企业个性化业务需求。
• 
  

三、核心功能清单

Service Layer 提供了丰富的功能，覆盖数据访问、业务操作、扩展定制等多个维度，主要包括：

1. 基础交互与认证

• 登录 / 登出：通过 HTTP POST 请求实现会话创建与销毁，返回会话 ID（B1SESSION）和路由信息（ROUTEID）；
• 单点登录（SSO）：支持基于 SAML2 协议的 SSO，包括 PAOS（非浏览器客户端）和 HTTP-POST（浏览器客户端）两种方式，依赖 SLD 作为身份提供商；
• 元数据与服务文档：通过 $metadata 接口获取实体结构（如业务对象属性、枚举类型），通过服务根 URL 获取暴露的实体列表。

2. 数据操作（CRUD）

• 创建（Create）：通过 HTTP POST 请求创建实体（如客户、销售订单），支持子对象（如订单行）嵌套提交；
• 查询（Retrieve）：通过 HTTP GET 请求获取实体数据，支持按主键查询、批量查询及复杂过滤；
• 更新（Update）：支持 PATCH（部分更新）和 PUT（全量替换），仅修改请求中指定的属性；
• 删除（Delete）：通过 HTTP DELETE 请求删除实体（部分对象如销售订单可能受业务规则限制）。

3. 高级查询能力

• 查询选项：支持 $filter（过滤）、$select（字段筛选）、$orderby（排序）、$top/$skip（分页）、$expand（关联查询）等 OData 标准参数；
• 聚合与分组：支持 $apply 进行聚合计算（如 sum、avg、max）和分组（groupby）；
• 跨表关联（Cross-Joins）：允许无预定义关联的实体集查询，通过 $crossjoin 实现多表联合查询；
• 行级过滤：支持对文档行等子对象进行过滤，结合 $crossjoin 实现头行关联查询。

4. 扩展与定制

• 用户定义对象（UDO/UDT/UDF）：支持管理用户定义表（UDT）、用户定义字段（UDF）和用户定义对象（UDO），包括元数据管理和 CRUD 操作；
• 用户定义 Schema：允许通过配置文件自定义实体返回字段，精简数据结构；
• JavaScript 扩展：支持在服务器端嵌入 JavaScript 脚本，实现复杂业务逻辑（如事务管理、自定义校验），基于 Chrome V8 引擎解析；
• 附件与图片处理：支持上传、下载、更新附件（如 PDF、文档）和商品 / 员工图片，依赖 CIFS 协议实现跨系统文件共享。

5. 可靠性与监控

• 批处理操作：通过 $batch 接口在单个请求中执行多个操作（如创建 + 更新），支持事务性变更集（Change Sets）；
• ETag 机制：基于乐观并发控制，通过 ETag 标识资源版本，避免并发更新冲突；
• 日志与监控：提供请求日志监控（正常 / 错误请求详情）、配置控制器（动态调整参数）、Ping Pong API（检测服务器可用性）。

6. 其他功能

• 跨域资源共享（CORS）：允许指定域名的客户端跨域访问，通过配置 CorsAllowedOrigins 实现；
• SQL 查询：支持通过 SQL 语句直接查询数据库视图（需在允许列表中），提供参数化查询和权限控制；
• 高可用与负载均衡：支持多节点部署，通过 Apache 负载均衡器分发请求，会话粘性确保同一客户端请求路由至同一节点。
• 
  

四、案例介绍

案例（一）：创建销售订单并关联客户

场景：通过 Service Layer 创建一个包含两行商品的销售订单，并关联已存在的客户。

1. 登录：发送 POST 请求获取会话：

http

POST https://<server>:<port>/b1s/v1/Login

{ "CompanyDB": "US506", "UserName": "manager", "Password": "1234" }

响应返回 B1SESSION 和 ROUTEID 用于后续请求。

2. 创建销售订单：发送 POST 请求，包含客户编码、订单日期及两行商品：

http

POST /Orders

{

  "CardCode": "c1",  // 客户编码

  "DocDate": "2024-07-24",

  "DocDueDate": "2024-07-31",

  "DocumentLines": [

    { "ItemCode": "i1", "Quantity": 10, "UnitPrice": 100, "TaxCode": "T1" },

    { "ItemCode": "i2", "Quantity": 5, "UnitPrice": 200, "TaxCode": "T1" }

  ]

}

成功后返回订单编号（DocEntry）和完整订单信息。

案例 （二）：批量操作（创建客户 + 订单）

场景：通过批处理在一个请求中创建客户和关联的销售订单，确保操作原子性。

1. 构造批处理请求：使用 multipart/mixed 格式，包含两个操作（创建客户 + 创建订单）：

http

POST /$batch

Content-Type: multipart/mixed; boundary=batch_123

--batch_123

Content-Type: multipart/mixed; boundary=changeset_456

--changeset_456

Content-Type: application/http

POST /BusinessPartners

{ "CardCode": "c2", "CardName": "新客户", "CardType": "cCustomer" }

--changeset_456

Content-Type: application/http

POST /Orders

{ "CardCode": "c2", "DocDate": "2024-07-24", "DocumentLines": [{ "ItemCode": "i1", "Quantity": 2 }] }

--changeset_456--

--batch_123--

2. 结果：若两个操作均成功，客户和订单被创建；若任一失败，整批操作回滚。

案例（三）：JavaScript 扩展实现复杂事务

场景：通过 JavaScript 脚本实现 “创建订单后自动生成交货单” 的联动逻辑。

1. 部署脚本：创建 JavaScript 文件，定义 POST 入口函数，包含事务控制：

javascript

var ServiceLayerContext = require('ServiceLayerContext.js');

function POST() {

  var slContext = new ServiceLayerContext();

  slContext.startTransaction(); // 开启事务

  // 1. 创建订单

  var order = { "CardCode": "c1", "DocumentLines": [{ "ItemCode": "i1", "Quantity": 1 }] };

  var orderRes = slContext.Orders.add(order);

  if (!orderRes.isOK()) {

    slContext.rollbackTransaction(); // 订单创建失败，回滚

    throw new Error("订单创建失败");

  }

  // 2. 基于订单创建交货单

  var delivery = { "CardCode": "c1", "BaseEntry": orderRes.body.DocEntry, "BaseType": 17 };

  var deliveryRes = slContext.DeliveryNotes.add(delivery);

  if (!deliveryRes.isOK()) {

    slContext.rollbackTransaction(); // 交货单创建失败，回滚

    throw new Error("交货单创建失败");

  }

  slContext.commitTransaction(); // 全部成功，提交事务

}

2. 调用脚本：通过 POST /b1s/v1/script/<partner>/<scriptName> 触发逻辑，实现订单与交货单的原子性创建。
3. 
   

五、总结

SAP Business One Service Layer 作为新一代扩展 API，通过标准化的 OData 协议简化了与 SAP Business One 的集成，其核心优势包括：

• 标准化与兼容性：基于 HTTP/OData 协议，支持多语言客户端（如 .NET、JavaScript）和第三方工具（如 Postman）；
• 高可扩展性：支持负载均衡、多节点部署，配合会话管理确保高并发场景下的稳定性；
• 功能完备性：覆盖从基础 CRUD 到复杂事务、扩展定制的全场景需求，支持 UDO/UDT/UDF 等个性化配置；
• 易用性：提供元数据文档、详细的查询选项和批处理能力，降低开发与集成门槛。

无论是企业级应用开发、系统集成还是个性化业务扩展，Service Layer 都为 SAP Business One 用户提供了灵活、高效的解决方案，助力企业快速响应业务需求变化。

联系我们

上海思邦信息技术有限公司（简称EXPAND，或思邦）于2003年创立于上海，专注于提供SAP Business One ERP产品和技术服务，包括：

• SAP Business One ERP产品的标准功能；
• SAP B1的Addons增强功能和定制开发；
• SAP B1与CRM、钉钉、飞书、泛微OA、MES、SRM、WMS等的集成方案。
• 针对以上产品和方案的商务咨询，实施交付，定制开发，运维支持和认证培训等。

思邦致力于成长型企业数字化转型升级的服务！