05 · 门② 集成与 API(入站 HTTP → 出站通信安排 → Postman 联调 完整实操)
📄 [教程] Day3 全天(Exercise 3 Part 1 + Part 2)+ PPT slide 11-23;总纲 PPT「接口」页 🔗 [官方] Communication Scenario(ABAP Cloud 集成) · Communication Arrangements(应用文档) · Create Communication Arrangement(操作步骤) · API Business Hub – S/4HANA Cloud 全部 API · 公有云全部通信场景清单(社区)
本章目标:把 04 章的在线商店应用接上"外部世界",亲手跑通三条链路——
入站:在 ADT 建两个 HTTP Service(上传表单模板、触发打印),配进通信场景/通信安排,用 Postman 调通;
出站:建 Outbound Service + Communication Scenario,把行为池的
print动作改成"走通信安排调自己的 API";调标准业务对象:弄懂 EML 与"生成代理"两条路怎么选,并能读懂我司线上代码(模式 C/D)在干什么。
本章是一条闭环:外部 Postman 传模板 → 浏览器点 Print → 打印队列出 PDF。
本章产出(做完自查):
# |
对象 |
类型 |
在哪建 |
作用 |
|---|---|---|---|---|
1 |
|
HTTP Service(入站) |
ADT |
外部用 POST 上传模板 XML |
2 |
|
处理类(Handler Class) |
ADT(自动生成) |
实现 |
3 |
|
HTTP Service(入站) |
ADT |
外部/自己 POST |
4 |
|
处理类 |
ADT(自动生成) |
取数 → Adobe 渲染 → 入打印队列 |
5 |
|
Outbound Service |
ADT |
声明"我要调外部 HTTP 服务"(系统自动加 |
6 |
|
Communication Scenario |
ADT |
把 2 个入站服务 + 1 个出站服务打包,Publish locally |
7 |
|
Communication System / Arrangement |
Fiori |
运行时绑定地址/端口/用户 |
8 |
|
行为池方法改造 |
ADT |
Print 按钮改成 HTTP 出站调用 |
9 |
打印队列项 + PDF |
运行结果 |
Fiori / 本机 |
端到端验收证据 |
✅ 衔接:04 章结束时
ZONLINESHOP/ZI_ONLINE_SHOP/ZC_ONLINE_SHOP/ BDEF /ZBP_I_ONLINE_SHOP/ZSD_ONLINE_SHOP/ZSB_ONLINE_SHOP都已激活发布,Preview 能建单。本章不重建这些对象,只加接口。打印相关前提(表ZFORMTEMPLATE、.xdp模板、打印队列DEVTEST、通信用户)属于 04 章 Step 9,§1 有清单,缺一项就先补。
0. 三条链路一张图(动手前先建立地图)
方向 |
谁调谁 |
你要建什么 |
运行时靠什么 |
本章位置 |
|---|---|---|---|---|
入站 Inbound |
外部系统 → SAP |
HTTP Service + 处理类(轻量自定义 API);或直接暴露 RAP OData 服务 |
通信场景 + 通信安排(入站用户) |
§2、§4、§6 |
出站 Outbound |
SAP → 外部/自己 |
Outbound Service + 通信场景 |
Fiori 通信系统 + 通信安排(出站用户) |
§3、§4、§5 |
调标准 BO |
ABAP 代码 → SAP 标准 BO |
不用建对象: |
released BO / released API |
§8.2 |
(📄 Day3 slide 15:查 API Hub 拿到 API 与场景 ID → 建通信场景/通信安排 → 写客户端实现)
四个概念先分清,后面每一步都围绕它们:
概念 |
是什么 |
谁建 |
在哪建 |
|---|---|---|---|
Communication Scenario |
"这个集成包含哪些服务 + 支持什么认证"的打包声明 |
开发者(自建场景)或 SAP 预置(标准场景) |
ADT |
Communication System |
对端系统的登记条目(主机名/端口/逻辑系统) |
管理员/顾问 |
Fiori |
Communication Arrangement |
场景的运行时实例:绑定通信系统 + 入站/出站用户 + 出站路径 |
管理员/顾问 |
Fiori |
Communication User |
技术账号(只能被程序用,不能交互登录) |
管理员 |
Fiori |
关系链一句话:开发者用 ADT 写服务、打包成场景并发布;管理员在 Fiori 把场景变成安排(绑对端地址和账号);代码里只认"场景 + 通信系统"两个名字,地址账号全在配置里。
ADT(开发者) Fiori(管理员)
HTTP Service / Outbound Service
│ 打包进
▼
Communication Scenario ──Publish locally──▶ Communication Arrangement
├─ Communication System(对端地址 + 端口)
├─ Inbound User(对方调我,如 PRINTUSER)
└─ Outbound User(我调对方)+ 出站 Path
1. 动手前:前置清单与对象总账(约 10 分钟)
# |
前置条件 |
哪来的 |
缺了会怎样 |
|---|---|---|---|
1 |
包 |
01 / 03 章 |
任何对象都存不下 |
2 |
表 |
03 / 04 章 |
打印服务取不到数据( |
3 |
行为池 |
04 章(§5.1 补法) |
界面上没有 Print 按钮 |
4 |
表 |
04 章 Step 9 |
上传/打印都报"表不存在" |
5 |
|
04 章 Step 9 |
打印没有版式 |
6 |
打印队列 |
04 章 Step 9 |
渲染报"打印队列不存在" |
7 |
本机 SAP Cloud Print Manager(CPIM) |
04 章 Step 9 |
队列有项但 PDF 不落本机 |
8 |
Postman |
官网下载 |
无法模拟外部调用 |
对象总账:本章新建 7 个对象(上表 1–7)、改 1 个方法(第 8 项),第 9 项是做出来的运行结果;所有对象挂在同一个 TR 上。
1.1 若缺 ZFORMTEMPLATE 表:先建(30 秒)
ADT 右键包 Z_Onlineshop → New → Other ABAP Repository Object → 搜 database table → Name ZFORMTEMPLATE → 选 TR → Finish,然后用整段源码覆盖模板:
@EndUserText.label : 'Persistence Layer for Form Template'
@AbapCatalog.enhancement.category : #NOT_EXTENSIBLE
@AbapCatalog.tableCategory : #TRANSPARENT
@AbapCatalog.deliveryClass : #A
@AbapCatalog.dataMaintenance : #RESTRICTED
define table zformtemplate {
key client : abap.clnt not null;
key formid : abap.char(30) not null;
form_binary : abap.rawstring(900000);
}
Ctrl+F3 激活,Problems 无红叉。
1.2 若缺打印三件套:补 4 步
步骤 |
操作 |
填什么 |
|---|---|---|
1 |
Fiori 打开 Communication Arrangements → New → 场景 |
这是打印服务的标准场景 |
2 |
安排里 Users for Inbound Communication → Add → New User |
Username |
3 |
Fiori 打开 Maintain Print Queues → New |
Queue |
4 |
本机启动 SAP Cloud Print Manager for Pull Integration,连到本租户 |
连上后队列自动被拉取 |
💡 本章 §4.3 的入站/出站用户都复用这个
PRINTUSER——它已经是通信用户(有密码、无交互登录),正好当接口账号。
1.3 若还没有 .xdp 表单模板:30 分钟补出来
打印链路(ZFORMPRINT_SRV)读的是表里的表单二进制,没有 .xdp 就会在 ADS 渲染这步失败。模板制作在 Day2 Part 2 里,这里补成可执行步骤:
步骤 |
操作 |
细节 |
|---|---|---|
1 |
ADT 建控制台类 |
控制台输出就是表单的数据结构 XSD(XML 文本) |
2 |
把控制台输出全选复制,存成本地文件 |
文件别加 BOM |
3 |
打开 Adobe LiveCycle Designer(Windows 工具;ES4 里叫 SAP Forms Designer 同名入口)→ |
— |
4 |
|
左侧出现 |
5 |
把字段拖到表单布局上排版(订单号/物料/数量/日期)→ 另存为 |
|
6 |
用记事本打开 |
下一步上传/存表用 |
7 |
两种入库方式任选:① 走本章 §2 的 |
两种方式最终都是往 |
CLASS zcl_datasource DEFINITION PUBLIC FINAL CREATE PUBLIC.
PUBLIC SECTION.
INTERFACES if_oo_adt_classrun.
ENDCLASS.
CLASS zcl_datasource IMPLEMENTATION.
METHOD if_oo_adt_classrun~main.
DATA(lo_fdp_util) = cl_fp_fdp_services=>get_instance( 'ZSD_ONLINE_SHOP' ).
DATA(lv_schema) = lo_fdp_util->get_xsd( ).
DATA(lv_schema_xml) = cl_abap_conv_codepage=>create_in( )->convert( lv_schema ).
out->write( lv_schema_xml ).
ENDMETHOD.
ENDCLASS.
(📄 Day2 脚本 Part 2:运行 ZCL_DATASOURCE,控制台输出 XSD)
(📄 Day2 脚本:Adobe LiveCycle Designer → File → New Data Connection)
(📄 Day2 脚本:选完 XSD 后左侧出现 ZI_ONLINE_SHOP 字段,拖到布局上)
⚠️ 没有 Adobe Designer(macOS 上没有官方版本)时:本章 §2–§5 的接口、通信安排、行为池出站改造照做不误,只有 §6 的"打印 PDF 落地"验收跳过;等有 Windows 环境再补模板即可。
2. 入站①:建两个 HTTP Service(Day3 Step 1)
场景:外部(Postman / 客户系统)直接 POST 报文本系统,一个接口存模板、一个接口触发打印。HTTP Service 是 ABAP Cloud 里最轻的自定义 REST 入口:你只管写 handler,认证/URL/暴露交给通信场景与安排。
2.1 新建 ZFORMTEMPLATE_SRV
步骤 |
操作 |
填什么 / 为什么 |
|---|---|---|
1 |
打开 Eclipse 的 ABAP Cloud 项目,确认连的是 D 开发租户 |
Project Explorer 里能看到 |
2 |
右键包 |
所有 ABAP 对象的统一入口 |
3 |
展开 Connectivity → 选 HTTP Service → Next |
见下图 |
4 |
Name |
Handler Class 由系统按 |
5 |
选 TR → Finish |
— |
6 |
创建完停在服务编辑页:Handler Class 是蓝色链接,URL 已生成 |
记下这条 URL(§4 之前的验证靠它) |
(📄 Day3 脚本:本地项目里找到 Day2 建的 ABAP Cloud 项目并登录)
(📄 Day3 脚本:右键包 Z_ONLINESHOP → New → Other ABAP Repository Object)
(📄 Day3 脚本:展开 Connectivity,选中 HTTP Service)
(📄 Day3 脚本:Name ZFORMTEMPLATE_SRV、Description Maintain form template service)
(📄 Day3 脚本:点 Handler Class 链接打开自动生成的类;URL 形如 https://<租户>/sap/bc/http/sap/ZFORMTEMPLATE_SRV?sap-client=080)
验证:包下出现 Connectivity → HTTP Services → ZFORMTEMPLATE_SRV;服务页 URL 一栏非空(此时还没有 handler 逻辑,调用只会返回空响应,属正常)。
💡 URL 规则固定:
/sap/bc/http/sap/<服务名小写>。ADT 里显示的是 UI 主机;对外调用要走通信安排里给出的 API 主机(域名多一个-api),两者路径相同——这是新人第一个大坑。
2.2 写"上传模板"处理逻辑(完整代码)
点服务页的 Handler Class 链接打开 ZCL_FORMTEMPLATE_SRV,光标停在 IF_HTTP_SERVICE_EXTENSION~HANDLE_REQUEST 里(方法体是空的,request / response 是系统给的参数,别改签名),把整段替换成:
(📄 Day3 脚本:点 Handler Class 链接后打开的类,方法体为空等待你填)
METHOD if_http_service_extension~handle_request.
" 入参:HTTP body 就是 .xdp 模板的 XML 全文;出参:无(默认 200)
DATA: lt_table TYPE TABLE OF zformtemplate,
ls_table LIKE LINE OF lt_table. "脚本原样保留:lt_table 未使用,可删
CASE request->get_method( ).
WHEN CONV string( if_web_http_client=>post ).
DATA(lv_text) = request->get_text( ).
ls_table-formid = 'ZDEMOTEST'.
ls_table-form_binary = cl_abap_conv_codepage=>create_out( )->convert( lv_text ).
MODIFY zformtemplate FROM @ls_table.
ENDCASE.
ENDMETHOD.
逐行解释:
语句 |
作用 |
为什么这么写 |
|---|---|---|
|
按 HTTP 方法分发 |
只处理 POST;GET/其它方法直接忽略(生产环境建议先判方法,不匹配就返回 405) |
|
把常量转成 |
|
|
读整个 body |
|
|
text → 二进制 |
|
|
按主键 |
主键固定 |
验证:Ctrl+F3 激活,Problems 无红叉。(真正看到数据落表在 §6.1 Postman 上传之后。)
2.3 新建第二个服务 ZFORMPRINT_SRV
同 §2.1 再来一遍,只是填的参数不同:
字段 |
值 |
|---|---|
Name |
|
Description |
|
Handler Class |
自动带出 |
(📄 Day3 脚本:重复同样步骤,建打印服务 ZFORMPRINT_SRV)
2.4 写"触发打印"处理逻辑(完整代码)
打开 ZCL_FORMPRINT_SRV 的 handler,用整段替换:
METHOD if_http_service_extension~handle_request.
" 入参:{"Order_Uuid":"..."};出参:无(PDF 进打印队列 DEVTEST)
DATA: BEGIN OF ls_input,
Order_Uuid TYPE c LENGTH 40,
END OF ls_input.
DATA(lv_text) = request->get_text( ).
/ui2/cl_json=>deserialize(
EXPORTING
json = lv_text
CHANGING
data = ls_input ).
TRY.
" ① 拿到 04 章那个服务定义的数据源:XSD、key 清单、按 key 读 XML
DATA(lo_fdp_util) = cl_fp_fdp_services=>get_instance( 'ZSD_ONLINE_SHOP' ).
DATA(lv_schema) = lo_fdp_util->get_xsd( ).
DATA(lv_schema_xml) = cl_abap_conv_codepage=>create_in( )->convert( lv_schema ).
DATA(lt_keys) = lo_fdp_util->get_keys( ).
lt_keys[ name = 'ORDER_UUID' ]-value = ls_input-Order_Uuid.
DATA(lv_xml) = lo_fdp_util->read_to_xml( lt_keys ).
DATA(lv_xml_out) = cl_abap_conv_codepage=>create_in( )->convert( lv_xml ).
DATA lv_string TYPE string. "脚本原样保留:未使用,可删
" ② 取模板二进制
SELECT SINGLE *
FROM zformtemplate
WHERE formid = 'ZDEMOTEST'
INTO @DATA(ls_form).
" ③ ADS 渲染 PDF 并直接放进打印队列
cl_fp_ads_util=>render_4_pq(
EXPORTING
iv_locale = 'en_US'
iv_pq_name = 'DEVTEST' "打印队列名,必须在 Maintain Print Queues 里存在
iv_xml_data = lv_xml
iv_xdp_layout = ls_form-form_binary
is_options = VALUE #(
trace_level = 4 ) "排错用 4;生产环境用 0
IMPORTING
ev_trace_string = DATA(lv_trace)
ev_pdl = DATA(lv_pdf) ).
" ④ 队列项命名:OnlieShopOrder_<UUID>(注:原脚本拼写就是 Onlie,保持与截图一致)
DATA docname TYPE c LENGTH 120.
docname = 'OnlieShopOrder_' && ls_input-Order_Uuid.
cl_print_queue_utils=>create_queue_item_by_data(
iv_qname = 'DEVTEST'
iv_print_data = lv_pdf
iv_name_of_main_doc = docname ).
CATCH cx_root INTO DATA(lv_1).
DATA(lv_error) = lv_1->get_longtext( ).
ENDTRY.
ENDMETHOD.
关键调用:
调用 |
作用 |
备注 |
|---|---|---|
|
JSON → ABAP 结构 |
全库通行做法(§8.1 的序列化用它做双向映射) |
|
拿到 04 章服务定义的数据源访问器 |
参数是 Service Definition 名,不是 Binding |
|
模板数据源 XSD / 主键清单 / 单实例 XML |
04 章本地打印类用的是同一套 API |
|
ADS 渲染 PDF 并写入指定打印队列 |
|
|
生成一条打印队列项 |
Main Document 名即队列里显示的文件名 |
验证:Ctrl+F3 激活,Problems 无红叉。此时还没有模板/队列,直接调用会进 CATCH——正常,§6 才联调。
2.5 两个服务的激活与自查
检查项 |
怎么做 |
通过标准 |
|---|---|---|
激活 |
两个类各按 |
Problems 视图无红叉 |
对象齐全 |
包下 |
看到 |
URL 规则 |
打开服务页看 URL |
|
处理类绑定 |
服务页 Handler Class 链接点得开 |
打开的就是你刚改的类 |
⚠️ 只按
Ctrl+S保存不生效:handler 类和服务对象都必须"已激活"(图标不带红叉),否则通信场景里挂上去的是旧版本。 💡 URL 里的服务名大小写不敏感:ADT 显示ZFORMTEMPLATE_SRV、通信安排里显示zformtemplate_srv,都能通。
3. 入站②:出站服务与通信场景(Day3 Step 2)
3.1 建 Outbound Service ZPRINT_OUT
步骤 |
操作 |
填什么 / 注意 |
|---|---|---|
1 |
右键包 |
— |
2 |
展开 Cloud Communication Management → 选 Outbound Service → Next |
见下图 |
3 |
Outbound Service |
选完类型系统自动加 |
4 |
选 TR → Finish |
— |
(📄 Day3 脚本:Cloud Communication Management 下建 Outbound Service)
(📄 Day3 脚本:ZPRINT_OUT + HTTP Service;注意名称栏已显示系统自动补的 _REST)
验证:包下 Cloud Communication Management 里出现 ZPRINT_OUT_REST;打开能看到 Outbound Service ID = ZPRINT_OUT_REST。
3.2 建 Communication Scenario ZPRINT
步骤 |
操作 |
填什么 / 注意 |
|---|---|---|
1 |
右键包 → New → Other ABAP Repository Object → Cloud Communication Management → Communication Scenario → Next |
与出站服务同一个父目录 |
2 |
Name |
场景名后面代码里要用 |
3 |
选 TR → Finish |
— |
4 |
打开场景,Inbound 页签:Supported Authentication Methods 勾 Basic(X.509 可一起勾,不影响练习) |
练习用 Basic 用户名密码 |
5 |
Inbound Services → Add → Inbound ID |
入站服务 ID 规律: |
6 |
再 Add 一条:Inbound ID |
— |
7 |
Outbound 页签:Supported Authentication Methods 勾 Basic;Outbound Services → Add → |
出站身份认证同样用 Basic |
8 |
|
先保存,再发布 |
(📄 Day3 脚本:Name ZPRINT、Description Communication scenario for printing)
(📄 Day3 脚本:Inbound 页先勾认证方式,再从 Add 加入站服务;右上角是 Publish Locally)
(📄 Day3 脚本:0001 → ZFORMPRINT_SRV_HTTP)
(📄 Day3 脚本:0002 → ZFORMTEMPLATE_SRV_HTTP)
(📄 Day3 脚本:Inbound Services 两行齐全,下方能看到选中服务的明细)
(📄 Day3 脚本:Outbound 页加入 ZPRINT_OUT_REST)
验证:Inbound Services 列表 2 行(ZFORMPRINT_SRV_HTTP、ZFORMTEMPLATE_SRV_HTTP),Outbound Services 列表 1 行(ZPRINT_OUT_REST);General 页 Communication Scenario Type = Customer Managed、Allowed Instances = One instance per scenario & communication system。
3.3 Publish locally(发布到本租户)
步骤 |
操作 |
说明 |
|---|---|---|
1 |
场景编辑页右上角点 Publish Locally |
场景不发布,Fiori 里就选不到它 |
2 |
等操作完成(状态会从 |
中途别改对象 |
验证(最硬的判据):打开 Fiori 的 Communication Arrangements → New → 在 Scenario 里能搜到 ZPRINT。搜不到 = 没发布成功或没激活,回上一步重来。
4. 配置:通信系统 + 通信安排(Day3 Step 3,Fiori)
这一步全在浏览器里做,是"开发者交对象、管理员配运行时"的分界点。
4.1 按场景新建通信安排
步骤 |
操作 |
填什么 / 注意 |
|---|---|---|
1 |
浏览器登录 D 租户 Fiori Launchpad(与 ADT 同一套 SSO) |
不用重新登 |
2 |
搜索并打开应用 Communication Arrangements |
— |
3 |
点 New |
— |
4 |
Scenario 选 |
场景选得到,说明 §3.3 发布成功 |
5 |
创建后进详情页,右侧 API-URL 先抄下来(形如 |
下一步建通信系统要用它的主机名 |
(📄 Day3 脚本:Fiori 打开 Communication Arrangements;列表里能看到 SAP_COM_0466、SAP_COM_0106 等标准场景的安排)
(📄 Day3 脚本:Scenario ZPRINT、Arrangement Name ZPRINT → Create)
(📄 Day3 脚本:先抄 API-URL;此时 Communication System 为空、入站用户未配)
4.2 建通信系统 ZPRINT2
步骤 |
操作 |
填什么 / 注意 |
|---|---|---|
1 |
安排详情的 Communication System 旁点 New |
直接就地新建 |
2 |
System ID |
System ID 就是代码里的 |
3 |
General → Host Name 填 API-URL 的主机部分:去掉 |
粘成整条 URL 一定连不上 |
4 |
Logical System 填 |
回环调自己,逻辑系统写 LOCAL 即可 |
5 |
保存通信系统 |
— |
(📄 Day3 脚本:System ID / System Name 都填 ZPRINT2)
(📄 Day3 脚本:Host Name 去掉 https:// 后粘贴;Logical System LOCAL;Port 443)
验证:Host Name 里不含 https://;Port = 443;保存后通信系统状态可编辑但已落库(回到安排页能看到 ZPRINT2)。
4.3 配入站用户 / 出站用户
步骤 |
操作 |
填什么 |
|---|---|---|
1 |
回安排页 → Users for Inbound Communication → Add |
Authentication Method 选 User ID and Password |
2 |
选通信用户 |
对方(外部)调你时用的账号 |
3 |
Users for Outbound Communication → Add |
弹窗 New Outbound User |
4 |
Authentication Method |
你调对方(这里是调自己)时用的账号,练习里同一个用户即可 |
5 |
保存通信系统 |
— |
(📄 Day3 脚本:Inbound 用户 PRINTUSER,认证方式 User ID and Password)
(📄 Day3 脚本:New Outbound User,同样 PRINTUSER + 密码)
验证:回安排页,Inbound Communication 和 Outbound Communication 两个区域的 User Name 都是 PRINTUSER,Authentication Method 都是 User ID and Password。
4.4 补齐出站服务路径并激活安排
回安排页,Outbound Services 区域展开 Printing Outbound Service:
字段 |
填什么 |
为什么 |
|---|---|---|
Service Status |
|
不激活,出站调用直接失败 |
Path |
|
出站要调的相对路径,从 §2.5 入站服务 |
Port |
|
HTTPS |
Service URL |
系统按 通信系统 Host + Path 自动拼出来 |
只读,用来自查 |
— |
改完点右上角 Save,再点 Edit 退出编辑态 |
不保存 = 出站调用仍走旧配置 |
(📄 Day3 脚本:出站 Path 填 /sap/bc/http/sap/zformprint_srv;上方入站/出站用户都是 PRINTUSER)
(📄 Day3 脚本:保存后 Editing Status 变成 Active,入站服务 URL 一并可见)
验证:安排页 Editing Status: Active;Outbound Services 行显示 Path 与拼好的 Service URL;Inbound Services 里两条 Service URL 都以 /sap/bc/http/sap/... 结尾。
4.5 三个 URL 别搞混(照这张表抄)
用途 |
去哪抄 |
形状(示例,主机以你环境为准) |
|---|---|---|
外部上传模板 |
安排 → Inbound Services → |
|
外部触发打印 |
安排 → Inbound Services → |
|
出站代码取目的地 |
不用抄 |
|
💡 开发租户的 URL 末尾常带
?sap-client=<client>(截图环境是 080;本司 GQN 是 100),Postman 直接整条粘没问题。
5. 出站代码:让 Print 按钮调外部 API(Day3 Step 4)
5.1 前置:行为层里必须先有 print 动作
如果 04 章只做到"建单/预览"(没做打印动作),先在三个地方补齐,否则界面上没有 Print 按钮:
" ① BDEF(ZI_ONLINE_SHOP)里加一行动作声明
action ( features : global ) print;
" ② 元数据扩展(ZC_ONLINE_SHOP)里把动作做成按钮:
" 把 Orderid 原来那行 @UI.identification 替换成下面这个数组(加一项 FOR_ACTION)
@UI.identification: [ { position: 1 },
{ type: #FOR_ACTION, dataAction: 'print', label: 'Print' } ]
Orderid;
" ③ 行为池类定义里加方法声明
METHODS print FOR MODIFY
IMPORTING keys FOR ACTION online_shop~print.
验证:Ctrl+F3 激活 BDEF / 元数据扩展 / 行为池;服务绑定重新 Publish 后,Preview 进详情页能看到 Print 按钮。
5.2 改 ZBP_I_ONLINE_SHOP 的 print 方法
步骤 |
操作 |
说明 |
|---|---|---|
1 |
包下 |
见下图 |
2 |
切到编辑器底部 Local Types 页签 |
行为实现都在局部类 |
3 |
找到 |
只改方法体,类定义不动 |
4 |
|
Problems 无红叉 |
(📄 Day3 脚本:包 → Source Code Library → Classes → ZBP_I_ONLINE_SHOP)
(📄 Day3 脚本:Local Types 页签里 lhc_online_shop 的 METHOD print 目前是空的)
完整代码(替换 print 方法体):
METHOD print.
DATA lo_http_client TYPE REF TO if_web_http_client. "脚本原样保留:方法内未使用,可删
DATA lv_payload TYPE string.
TRY.
" ① 按"通信场景 + 通信系统"解析出出站目的地(地址/端口/用户在 Fiori 里配)
DATA(lo_url_destination) = cl_http_destination_provider=>create_by_comm_arrangement(
comm_scenario = 'ZPRINT'
comm_system_id = 'ZPRINT2' ).
" ② 建 HTTP 客户端,组请求头
DATA(http_client) = cl_web_http_client_manager=>create_by_http_destination( lo_url_destination ).
DATA(req) = http_client->get_http_request( ).
req->set_header_field( i_name = 'Content-type' i_value = 'application/json; charset=UTF-8' ).
req->set_header_field( i_name = 'Accept' i_value = 'application/json' ).
" ③ 一个订单一个请求:{ "Order_Uuid": "..." } POST 给 ZFORMPRINT_SRV
LOOP AT keys INTO DATA(ls_key).
lv_payload = '{"Order_Uuid":"' && ls_key-order_uuid && '"}'.
req->set_text( lv_payload ).
DATA(lo_response) = http_client->execute( if_web_http_client=>post ).
DATA(lv_input) = lo_response->get_text( ).
ENDLOOP.
CATCH cx_root INTO DATA(e).
DATA(error) = e->get_longtext( ).
ENDTRY.
ENDMETHOD.
逐段解释:
语句 |
作用 |
易错点 |
|---|---|---|
|
用配置解析目的地 |
|
|
由目的地建客户端 |
客户端用完建议 |
|
复用同一个 request 对象逐步改 |
头只需设一次,body 每单 |
|
界面多选时逐单调用 |
|
|
同步发出 |
返回后才知道结果 |
|
兜底 |
教学脚本把错误塞进局部变量 |
💡 与 §2.4 的分工:行为池只负责"通知",真正取数/渲染/入队全在
ZFORMPRINT_SRV里。这样改打印逻辑只动服务,不动 RAP 层——这正是入站接口的价值。
5.3 生产化:教学脚本缺的 4 件事
教学脚本写法 |
生产必须补 |
|---|---|
响应只读文本,不判状态 |
判 |
异常只存 |
用 |
循环里一条失败不拦后面 |
明确策略:整单回滚,或逐条结果落结果表(模式 C 的做法) |
场景名/系统 ID/队列名硬编码 |
抽成常量或配置,别散落在代码里(我司模式 C 的配置表就是这么来的) |
6. 端到端联调(Day3 Part 2)
6.1 Postman 上传模板(走 ZFORMTEMPLATE_SRV)
步骤 |
操作 |
填什么 |
|---|---|---|
1 |
Postman 新建请求,方法选 POST |
注意不是 GET |
2 |
URL 粘贴 §4.5 表格里 |
整条复制,含 |
3 |
Authorization 页签:Type = Basic Auth,Username |
与 §4.3 入站用户一致 |
4 |
Body 页签:选 raw,右侧格式选 XML;用文本编辑器打开 |
粘的就是模板本体 |
5 |
点 Send |
— |
(📄 Day3 脚本:Service URL 粘进 Postman,Authorization 选 Basic Auth + PRINTUSER)
(📄 Day3 脚本:Body → raw → XML,粘 .xdp 的 XML,Send 后右下角 Status: 200 OK)
验证:
Postman 返回 200 OK(返回体为空是正常的,handler 没写 response);
回 ADT → 表
ZFORMTEMPLATE右键 Open With → Data Preview:能看到FORMID = ZDEMOTEST一行,FORM_BINARY有内容;若返回 401/403/404/500,直接跳 §10 排错表。
6.2 在浏览器里点 Print
步骤 |
操作 |
说明 |
|---|---|---|
1 |
ADT 打开服务绑定 |
与 04 章同一个入口 |
2 |
列表里点一条订单(如 Order Id |
没有订单就先 Create 一条(Material |
3 |
右上角点 Print |
触发 |
(📄 Day3 脚本:Business Services → Service Bindings → ZSB_ONLINE_SHOP → Preview)
(📄 Day3 脚本:进入一张 ShopOrder,点 Print)
验证:点完不弹错误;按钮执行完成后去 §6.3 看队列(界面成功不代表 PDF 已生成——真正的判据在队列)。
6.3 在打印队列和本机验收
步骤 |
操作 |
通过标准 |
|---|---|---|
1 |
Fiori 搜索应用 Maintain Print Queues → 点队列 |
Items 里出现一条 |
2 |
看该行字段 |
Status |
3 |
(有 CPIM 时)看本机输出目录 |
文件名同队列项,PDF 能打开且字段正确 |
(📄 Day3 脚本:Maintain Print Queues → DEVTEST,队列项 OnlieShopOrder_FA163...,Status Successful)
(📄 Day3 脚本:CPIM 拉取后 PDF 落到本机目录,内容是最初那张订单的字段)
验证(端到端三点全中才算成功):
队列里 有 以
OnlieShopOrder_开头的 PDF 项且Successful;PDF 里
ORDERID / MATERIAL / QUANTITY / DELIVERYDATE与订单一致;本机目录(CPIM 里配置的 Queue Options 输出路径)能看到同名
.pdf。
💡 只想单独验证打印服务(绕开 RAP/出站)?用 Postman 直接 POST
ZFORMPRINT_SRV的 Service URL,Body 用{"Order_Uuid":"<你的订单 UUID>"}。这一步能快速分清"是打印逻辑坏了"还是"出站配置坏了"。
6.4 用 Postman 直接调打印接口(排错必会)
步骤 |
操作 |
填什么 |
|---|---|---|
1 |
ADT 打开表 |
订单主键,界面上是隐藏字段 |
2 |
Postman 新建 POST 请求,URL 用 §4.5 里 |
与上传模板用的是不同服务 |
3 |
Authorization → Basic Auth, |
同 §6.1 |
4 |
Body → raw → JSON,内容: |
注意字段名大小写与 §2.4 的 |
验证:返回 200(body 为空,正常);同时 DEVTEST 队列多出一条 OnlieShopOrder_<UUID>,Status Successful。
7. 概念与选型(跑通后再回头看,记得更牢)
7.1 四种入站通道
通道 |
建什么 |
适合 |
不适合 |
|---|---|---|---|
HTTP Service(本章) |
ADT |
轻量自定义 REST(报文自己定)、回调/通知 |
结构化 CRUD、要自动生成元数据 |
OData Web API(RAP) |
|
正式对外接口、结构化 CRUD、要 API Hub 风格文档 |
报文格式特殊、非 CRUD 的简单动作 |
RFM(远程函数模块) |
ADT 远程启用 FM |
与老 ABAP 系统同步集成、性能敏感 |
新接口(公有云里 RFM 使用受限、不推荐新建) |
SOAP Provider |
由 WSDL 生成服务 |
遗留 SOAP 对接 |
新接口(优先 OData/REST) |
7.2 认证方式对照
方式 |
用在哪 |
本章/我司情况 |
|---|---|---|
Basic(通信用户+密码) |
通信安排入站/出站 |
本章练习用;我司模式 C 也用它(账号在配置表) |
OAuth 2.0 |
安排里启用,客户端取 token |
我司未用;对外正式接口优先考虑 |
X.509 / mTLS(证书) |
安排里启用 |
本章场景可选开启,练习不用 |
Principal Propagation |
把终端用户身份透传到后端(BTP 场景) |
未用;做"以用户身份调用"时才需要 |
自定义签名 |
第三方专用(如金税 HMAC-SHA1) |
金税接口在用(§8.3) |
红线:接口凭证不写死在代码里。练习用通信用户,存量用配置表,新接口一律走通信安排。
7.3 出站三条路怎么选
做法 |
何时用 |
代码长什么样 |
|---|---|---|
通信安排(本章) |
新接口默认 |
|
配置表 + |
存量维护、目标系统多到不想逐个建安排 |
读表拿 URL/账号 → |
EML |
调标准业务对象(过账/冲销/改单) |
|
生成代理类 |
老 SOAP 接口、报文巨大 |
|
7.4 连一个"标准 API"的标准流程
去 api.sap.com(SAP API Business Hub)搜业务对象,例如
API_OUTBOUND_DELIVERY_SRV;在 API 文档页记下三件事:版本(
;v=0002)、通信场景 ID(API 页会列出;本租户的通信安排列表里也能看到这类标准场景,如交货处理的SAP_COM_0106)、限制/前置条件;在 Fiori 建该标准场景的通信安排(不用在 ADT 建场景);
代码里
create_by_comm_arrangement( comm_scenario = '<该 API 的场景 ID>' comm_system_id = '<你的通信系统>' ),或按 §8.1 的 URL 方式直连;先 Postman/API Hub 的 try-out 调通再写代码 —— 遇标准 API 先读文档是团队习惯(我司代码注释里就挂着 KBA 2899036 与 api.sap.com 链接)。
8. 公司实践:模式 C / D 的真实代码(📦)
复刻来源:
docs/顾问开发的代码--现有线上代码/四个 gCTS 导出包。路径均相对该目录。
8.1 模式 C:配置表 + create_by_url + CSRF 预取(我司出站主力)
📦 样板:sap-zzsd-master/src/zzfg_sd_api.fugr.zzfm_pub_sdtodn.abap(销售订单 → 出库交货过账,295 行,头部注释还挂着 SAP KBA 2899036 与 API Hub 链接)。
它和本章 §5 的最大差别:不走通信安排,而是把"目标系统"存在自建配置表 ZZT_REST_SYSID(一行一个系统,SELF = 本系统回环),URL/账号都从表里读。六步骨架:
" ① 读目标配置(URL 前缀 + 账号)
SELECT SINGLE * FROM zzt_rest_sysid
WHERE zztsysid = @self_sysid "常量 'SELF' = 本系统
INTO @DATA(ls_sys).
lv_username = ls_sys-zzuser.
lv_password = ls_sys-zzpwd.
lv_url_pre = ls_sys-zzurl && '/sap/opu/odata/sap'.
" ② 按单据类别选 API(退货走另一套服务)
CASE LV_SDDocumentCategory.
WHEN 'H'. "退货订单
lv_uri_path = |/API_CUSTOMER_RETURNS_DELIVERY_SRV;v=0002/A_ReturnsDeliveryHeader?sap-language=zh|.
WHEN OTHERS."正常订单
lv_uri_path = |/API_OUTBOUND_DELIVERY_SRV;v=0002/A_OutbDeliveryHeader?sap-language=zh|.
ENDCASE.
" ③ 组报文:结构 → JSON(name_mappings 负责 ABAP 大写 ↔ JSON 驼峰)
lv_json = /ui2/cl_json=>serialize(
data = ls_dninfo
compress = abap_true
name_mappings = lt_name_mapping ).
" ④ CSRF 预取:先 GET 拿 token/etag/cookie
DATA(lo_url_destination) = cl_http_destination_provider=>create_by_url( lv_url ).
http_client = cl_web_http_client_manager=>create_by_http_destination( lo_url_destination ).
DATA(lo_request) = http_client->get_http_request( ).
lo_request->set_header_field( i_name = 'Content-type' i_value = 'application/json' ).
lo_request->set_header_field( i_name = 'Accept' i_value = 'application/json' ).
lo_request->set_header_field( i_name = 'x-csrf-token' i_value = 'fetch' ).
lo_request->set_authorization_basic( i_username = lv_username i_password = lv_password ).
lo_response = http_client->execute( if_web_http_client=>get ).
DATA(lv_csrf) = lo_response->get_header_field( 'x-csrf-token' ).
DATA(lv_etag) = lo_response->get_header_field( 'etag' ).
DATA(lt_cookies) = lo_response->get_cookies( ).
" ⑤ 正式 POST:带 token / If-Match / 全部 cookie
lo_request->set_header_field( i_name = 'x-csrf-token' i_value = lv_csrf ).
lo_request->set_header_field( i_name = 'If-Match' i_value = lv_etag ).
LOOP AT lt_cookies ASSIGNING FIELD-SYMBOL(<cookie>).
lo_request->set_cookie( i_name = <cookie>-name i_path = <cookie>-path
i_value = <cookie>-value i_domain = <cookie>-domain
i_expires = <cookie>-expires i_secure = <cookie>-secure ).
ENDLOOP.
lo_request->set_text( lv_json ).
lo_response = http_client->execute( if_web_http_client=>post ).
" ⑥ 解析响应 → 统一结果结构 ZZS_REST_OUT(msgty/msgtx/sapnum)
IF lo_response->get_status( )-code = '201'.
ls_rest_out-msgty = 'S'.
ls_rest_out-msgtx = 'success'.
" 201 返回体里取交货单号 → ls_rest_out-sapnum
ELSE.
" 错误返回体里取 error.message.value → ls_rest_out-msgtx
ENDIF.
http_client->close( ).
为什么当年这么做、为什么新接口别抄:
好处 |
代价 |
|---|---|
新增目标系统只加一行配置,不必逐个建通信安排/通信系统 |
① 密码明文落表 |
回环调标准 API = "任何标准 OData 能干的事"都能拿过来 |
② 绕开通信治理:没有 OAuth2、没有证书轮换、没有调用审计 |
统一结果结构 + 结果表,失败可补推 |
③ CSRF/cookie 全手工维护,容易漏(漏了就是 403) |
📦 佐证与坑:
ZZT_REST_SYSID/ZZT_REST_APPEND两张表不在四个导出包里(属未导出的公共包,见docs/SAP公有云开发现状认知.md§7 问题清单第 2 条),动出站配置前先找顾问拿定义。 📦 同族样板:zzcl_api_sd003.clas.abap(价格条件读写,大量I_SLSPRCG*released CDS +WITH PRIVILEGED ACCESS)、zzcl_api_sd012.clas.abap(交货单批次拆分,I_DELIVERYDOCUMENTITEM+ 批次管理判断)——它们证明"入站/编排层"在本司实际长在类方法里,由 FM/Job 调用。
8.2 模式 D:EML 调标准 BO(新代码首选)
📦 样板:sap-fi-master/src/zzcl_api_fi001.clas.abap:866(改凭证付款条件)、zzcl_api_fi010.clas.abap:76(冲销凭证)。两处都用 EML 直接操作 released 标准 BO,不经过 HTTP:
" 冲销一张会计凭证(摘自 zzcl_api_fi010.clas.abap 的 can_post 方法;省略了前置取数与配置读取)
DATA: lt_jr TYPE TABLE FOR ACTION IMPORT i_journalentrytp~reverse.
APPEND INITIAL LINE TO lt_jr ASSIGNING FIELD-SYMBOL(<jr>).
<jr>-companycode = ls_result-companycode.
<jr>-fiscalyear = ls_result-fiscalyear.
<jr>-accountingdocument = ls_result-accountingdocument.
<jr>-%param = VALUE #(
postingdate = iv_postingdate
reversalreason = iv_reasoncode ).
MODIFY ENTITIES OF i_journalentrytp
ENTITY journalentry
EXECUTE reverse FROM lt_jr
FAILED DATA(ls_failed)
REPORTED DATA(ls_reported)
MAPPED DATA(ls_mapped).
LOOP AT ls_reported-journalentry ASSIGNING FIELD-SYMBOL(<ls_reported>).
DATA(lv_result) = <ls_reported>-%msg->if_message~get_text( ).
ENDLOOP.
IF ls_failed-journalentry IS INITIAL.
o_resp-msgty = 'S'. o_resp-msgtx = '冲销成功'.
ELSE.
o_resp-msgty = 'E'. o_resp-msgtx = '冲销失败' && lv_result.
ENDIF.
同文件里还留着被注释掉的上一代实现——cl_soap_destination_provider=>create_by_url + NEW zco_journal_entry_bulk_change( ... ) 代理类。这条演进线值得记住:同一功能,老写法是生成 SOAP 代理,新写法是 EML;新开发一律 EML,只有报文巨大/只能 SOAP 时才用代理。
8.3 生成代理 + 第三方签名(了解即可)
📦
sap-fi-master/src/zzfi001/下ZJOURNAL_ENTRY_CREATE_REQUEST*结构 +ZCO_JOURNAL_ENTRY_CREATE_REQUE代理类:由向导从 Journal Entry – Post API 元数据生成,zzcl_api_fi001/zzcl_api_fi010的post方法仍在用(cl_soap_destination_provider=>create_by_url+ 代理 →journal_entry_create_request_c( ))。生成对象禁止手改。📦
sap-fi-master/src/zzfg_fi_nn.fugr.zfm_gtax_create.abap(金税诺诺):70+ 字段name_mappings→/ui2/cl_json=>serialize→ZFM_GTAX_HMAC_SHA1签名 → HTTP 调诺诺 → 响应反序列化进ZZS_FII013_*→ 结果落ZZTFI020/021/024。_CX后缀 = 红冲变体,ZFM_GTAX_GET= 结果查询。对接第三方带签名的 REST 的完整样板。
8.4 我司出站接口去向(维护时先查这张表)
目标 |
场景(举例) |
实现位置(相对四包 |
|---|---|---|
本系统标准 API |
SO→DN 过账、退货、改金额 |
|
MES |
BOM/生产订单/报工推送 |
|
WMS |
交货/预留/委外推送 |
SD |
旺店通/领星 |
交货/发货/入库 |
|
OA/钉钉/数字人力 |
审批发起/回传 |
|
诺诺金税 |
开票/红冲/查询 |
|
TMS 银行 |
流水拉取/回款 |
|
9. 新增一个接口的标准步骤(照此执行)
# |
步骤 |
判据 |
|---|---|---|
1 |
API Hub 确认目标 API 的版本/字段/限制,抄下通信场景 ID |
文档页能看到 scenario ID |
2 |
领号 + 建 |
结构随对象一起进 TR |
3 |
选通道:新项目走通信场景+安排;存量维护才用配置表 |
评审时能说清为什么 |
4 |
实现: |
壳与实现分离,便于重试/测试 |
5 |
JSON 映射集中定义 |
结果表能查到每次调用的成败 |
6 |
失败可重试:接 06 章 Application Job 轮询结果表补推 |
Job 能捞出失败记录 |
7 |
权限:通信用户/业务角色按最小权限给(08 章) |
用业务用户验证过 |
8 |
台账登记:接口名/方向/认证方式/配置键/结果表/负责人 |
台账里能搜到 |
10. 排错清单(照症状查)
现象 |
最可能原因 |
怎么查 / 怎么修 |
|---|---|---|
Postman 401 |
用户名/密码错;通信用户没密码;用成了普通业务用户 |
用安排里 Inbound User 的账号; |
Postman 403 |
通信用户缺权限(IAM/业务角色);服务授权默认值没配 |
查该用户角色(08 章);服务页的 |
Postman 404 |
URL 抄错(少了 |
对着安排里的 Service URL 整条复制;确认场景 Inbound 列表有它 |
Postman 500 |
handler 运行时报错(模板表空、ADS 不可用、字段没赋值) |
在 CATCH 里临时 |
返回 200 但表里没数据 |
请求方法不是 POST( |
确认 Postman 方法是 POST;Data Preview 查 |
Print 报 communication system not found |
|
核对 |
Print 报 no destination / arrangement not found |
场景没 Publish locally;安排里缺出站服务或 Path 为空 |
重发场景;出站 Path 填 |
Print 界面无反应 |
|
临时把错误写进 |
队列里没有项,但 Print 成功 |
出站 POST 没到打印服务(场景/路径/用户错) |
用 Postman 直接打 |
队列有项但本机没 PDF |
CPIM 没启动/没连租户/输出目录不对 |
查 CPIM 连接状态与 Queue Options 输出路径 |
PDF 空白或字段错位 |
|
重新 |
11. 本章检查清单
能画出"通信场景 → 通信安排 → 通信系统/通信用户"的关系,并说清谁在 ADT 建、谁在 Fiori 配
两个 HTTP Service(
ZFORMTEMPLATE_SRV、ZFORMPRINT_SRV)已建、handler 完整、激活无错通信场景
ZPRINT的 Inbound 有 2 条、Outbound 有 1 条,已 Publish locally通信系统
ZPRINT2的 Host Name 已去https://,Port 443;安排ActivePostman 用 Basic Auth +
PRINTUSER上传.xdp返回 200,表ZFORMTEMPLATE里能看到ZDEMOTEST行为池
print方法已改成create_by_comm_arrangement出站,激活无错浏览器点 Print 后,
DEVTEST队列出现OnlieShopOrder_*且Successful(有 CPIM 时本机能打开 PDF)能用 Postman 直接 POST
ZFORMPRINT_SRV输出 PDF(排错手段,见 §6.4)能说出入站四种通道、四种认证方式各适合什么场景
能读懂模式 C 的 CSRF 预取六步,并说出为什么新接口不再这么写
能写出 EML 冲销凭证的三行核心代码(
MODIFY ENTITIES OF i_journalentrytp ... EXECUTE reverse)
➡️ 下一步
下一章:06 · 门② Application Job 定时任务——接口跑通后,把"失败重试/每日增量推送"交给 Application Job。
主线回顾:01 · 环境准备与开发工具 → 03 · 门② ABAP Cloud 基础与数据字典 → 04 · 门② RAP 业务对象开发