05 · 门② 集成与 API(入站 HTTP → 出站通信安排 → Postman 联调 完整实操)

本章目标:把 04 章的在线商店应用接上"外部世界",亲手跑通三条链路——

  1. 入站:在 ADT 建两个 HTTP Service(上传表单模板、触发打印),配进通信场景/通信安排,用 Postman 调通;

  2. 出站:建 Outbound Service + Communication Scenario,把行为池的 print 动作改成"走通信安排调自己的 API";

  3. 调标准业务对象:弄懂 EML 与"生成代理"两条路怎么选,并能读懂我司线上代码(模式 C/D)在干什么。

本章是一条闭环:外部 Postman 传模板 → 浏览器点 Print → 打印队列出 PDF。

本章产出(做完自查):

#

对象

类型

在哪建

作用

1

ZFORMTEMPLATE_SRV

HTTP Service(入站)

ADT

外部用 POST 上传模板 XML

2

ZCL_FORMTEMPLATE_SRV

处理类(Handler Class)

ADT(自动生成)

实现 IF_HTTP_SERVICE_EXTENSION~HANDLE_REQUEST

3

ZFORMPRINT_SRV

HTTP Service(入站)

ADT

外部/自己 POST {"Order_Uuid":"..."} 触发打印

4

ZCL_FORMPRINT_SRV

处理类

ADT(自动生成)

取数 → Adobe 渲染 → 入打印队列

5

ZPRINT_OUT

Outbound Service

ADT

声明"我要调外部 HTTP 服务"(系统自动加 _REST 后缀)

6

ZPRINT

Communication Scenario

ADT

把 2 个入站服务 + 1 个出站服务打包,Publish locally

7

ZPRINT2 + ZPRINT 安排

Communication System / Arrangement

Fiori

运行时绑定地址/端口/用户

8

ZBP_I_ONLINE_SHOP 的 print

行为池方法改造

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

不用建对象:EML 直接写;复杂场景用生成的代理类

released BO / released API

§8.2

API 消费全景 (📄 Day3 slide 15:查 API Hub 拿到 API 与场景 ID → 建通信场景/通信安排 → 写客户端实现)

四个概念先分清,后面每一步都围绕它们:

概念

是什么

谁建

在哪建

Communication Scenario

"这个集成包含哪些服务 + 支持什么认证"的打包声明

开发者(自建场景)或 SAP 预置(标准场景)

ADT

Communication System

对端系统的登记条目(主机名/端口/逻辑系统)

管理员/顾问

Fiori

Communication Arrangement

场景的运行时实例:绑定通信系统 + 入站/出站用户 + 出站路径

管理员/顾问

Fiori

Communication User

技术账号(只能被程序用,不能交互登录)

管理员

Fiori Maintain Communication Users

关系链一句话:开发者用 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

包 Z_Onlineshop + 一个传输请求(TR)

01 / 03 章

任何对象都存不下

2

表 ZONLINESHOP、视图 ZI_ONLINE_SHOP、服务 ZSD_ONLINE_SHOP / ZSB_ONLINE_SHOP 已激活发布

03 / 04 章

打印服务取不到数据(cl_fp_fdp_services 报错)

3

行为池 ZBP_I_ONLINE_SHOP + print 动作

04 章(§5.1 补法)

界面上没有 Print 按钮

4

表 ZFORMTEMPLATE(FORMID + FORM_BINARY)

04 章 Step 9

上传/打印都报"表不存在"

5

.xdp 表单模板文件(Adobe LiveCycle Designer 做的)

04 章 Step 9

打印没有版式

6

打印队列 DEVTEST + 通信安排 SAP_COM_0466 + 通信用户 PRINTUSER

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 → 场景 SAP_COM_0466(Printing – Pull Integration)→ Create

这是打印服务的标准场景

2

安排里 Users for Inbound Communication → Add → New User

Username PRINTUSER;Password 让系统生成并记下来;Description PrintUser

3

Fiori 打开 Maintain Print Queues → New

Queue DEVTEST,Description 随意;Communication User 选刚建的 PRINTUSER

4

本机启动 SAP Cloud Print Manager for Pull Integration,连到本租户

连上后队列自动被拉取

💡 本章 §4.3 的入站/出站用户都复用这个 PRINTUSER——它已经是通信用户(有密码、无交互登录),正好当接口账号。

1.3 若还没有 .xdp 表单模板:30 分钟补出来

打印链路(ZFORMPRINT_SRV)读的是表里的表单二进制,没有 .xdp 就会在 ADS 渲染这步失败。模板制作在 Day2 Part 2 里,这里补成可执行步骤:

步骤

操作

细节

1

ADT 建控制台类 ZCL_DATASOURCE(实现 if_oo_adt_classrun),贴下面代码 → 激活 → F9 运行

控制台输出就是表单的数据结构 XSD(XML 文本)

2

把控制台输出全选复制,存成本地文件 Datasource.xsd(UTF-8)

文件别加 BOM

3

打开 Adobe LiveCycle Designer(Windows 工具;ES4 里叫 SAP Forms Designer 同名入口)→ File → New → 空白表单

—

4

File → New Data Connection → 选 XML Schema → 选 Datasource.xsd → Finish

左侧出现 ZI_ONLINE_SHOP 字段树

5

把字段拖到表单布局上排版(订单号/物料/数量/日期)→ 另存为 CustomForm.xdp

.xdp 是 XML 包,后面要当二进制存表

6

用记事本打开 CustomForm.xdp,全选复制 XML 文本

下一步上传/存表用

7

两种入库方式任选:① 走本章 §2 的 ZFORMTEMPLATE_SRV 用 Postman POST 文本;② 走 04 章 §9 的控制台类 + 调试器,把 XML 赋值给 lv_text 后 MODIFY zformtemplate

两种方式最终都是往 ZFORMTEMPLATE 的 FORM_BINARY 写内容

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.

控制台类取 XSD (📄 Day2 脚本 Part 2:运行 ZCL_DATASOURCE,控制台输出 XSD)

Adobe Designer 数据连接 (📄 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 里能看到 GBZ_EN [GBZ, 080, ...],包 Z_ONLINESHOP 在 Favorite Packages 下

2

右键包 Z_ONLINESHOP → New → Other ABAP Repository Object

所有 ABAP 对象的统一入口

3

展开 Connectivity → 选 HTTP Service → Next

见下图

4

Name ZFORMTEMPLATE_SRV;Description Maintain form template service

Handler Class 由系统按 ZCL_<服务名> 自动带出 ZCL_FORMTEMPLATE_SRV,不用改

5

选 TR → Finish

—

6

创建完停在服务编辑页:Handler Class 是蓝色链接,URL 已生成

记下这条 URL(§4 之前的验证靠它)

项目里的包 (📄 Day3 脚本:本地项目里找到 Day2 建的 ABAP Cloud 项目并登录)

右键包新建对象 (📄 Day3 脚本:右键包 Z_ONLINESHOP → New → Other ABAP Repository Object)

Connectivity 下选 HTTP Service (📄 Day3 脚本:展开 Connectivity,选中 HTTP Service)

填写服务名与描述 (📄 Day3 脚本:Name ZFORMTEMPLATE_SRV、Description Maintain form template service)

服务页上的 Handler Class 与 URL (📄 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.

逐行解释:

语句

作用

为什么这么写

CASE request->get_method( )

按 HTTP 方法分发

只处理 POST;GET/其它方法直接忽略(生产环境建议先判方法,不匹配就返回 405)

CONV string( if_web_http_client=>post )

把常量转成 string 再比

get_method( ) 返回 string,类型一致才能比

request->get_text( )

读整个 body

.xdp 本质是 XML 文本,先按文本取

cl_abap_conv_codepage=>create_out( )->convert( ... )

text → 二进制

FORM_BINARY 是 rawstring;模板要以二进制存(打印时直接喂 ADS)

MODIFY zformtemplate FROM @ls_table

按主键 FORMID 写入/覆盖

主键固定 ZDEMOTEST,所以重复上传就是"覆盖模板",天然幂等

验证:Ctrl+F3 激活,Problems 无红叉。(真正看到数据落表在 §6.1 Postman 上传之后。)

2.3 新建第二个服务 ZFORMPRINT_SRV

同 §2.1 再来一遍,只是填的参数不同:

字段

值

Name

ZFORMPRINT_SRV

Description

Print form template service

Handler Class

自动带出 ZCL_FORMPRINT_SRV

新建第二个 HTTP Service (📄 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.

关键调用:

调用

作用

备注

/ui2/cl_json=>deserialize

JSON → ABAP 结构

全库通行做法(§8.1 的序列化用它做双向映射)

cl_fp_fdp_services=>get_instance( 'ZSD_ONLINE_SHOP' )

拿到 04 章服务定义的数据源访问器

参数是 Service Definition 名,不是 Binding

get_xsd( ) / get_keys( ) / read_to_xml( lt_keys )

模板数据源 XSD / 主键清单 / 单实例 XML

04 章本地打印类用的是同一套 API

cl_fp_ads_util=>render_4_pq

ADS 渲染 PDF 并写入指定打印队列

iv_xdp_layout 喂 .xdp 二进制;trace_level = 4 排错用

cl_print_queue_utils=>create_queue_item_by_data

生成一条打印队列项

Main Document 名即队列里显示的文件名

验证:Ctrl+F3 激活,Problems 无红叉。此时还没有模板/队列,直接调用会进 CATCH——正常,§6 才联调。

2.5 两个服务的激活与自查

检查项

怎么做

通过标准

激活

两个类各按 Ctrl+F3

Problems 视图无红叉

对象齐全

包下 Connectivity → HTTP Services

看到 ZFORMTEMPLATE_SRV、ZFORMPRINT_SRV 两个

URL 规则

打开服务页看 URL

/sap/bc/http/sap/zformtemplate_srv、.../zformprint_srv

处理类绑定

服务页 Handler Class 链接点得开

打开的就是你刚改的类

⚠️ 只按 Ctrl+S 保存不生效:handler 类和服务对象都必须"已激活"(图标不带红叉),否则通信场景里挂上去的是旧版本。 💡 URL 里的服务名大小写不敏感:ADT 显示 ZFORMTEMPLATE_SRV、通信安排里显示 zformtemplate_srv,都能通。


3. 入站②:出站服务与通信场景(Day3 Step 2)

3.1 建 Outbound Service ZPRINT_OUT

步骤

操作

填什么 / 注意

1

右键包 Z_ONLINESHOP → New → Other ABAP Repository Object

—

2

展开 Cloud Communication Management → 选 Outbound Service → Next

见下图

3

Outbound Service ZPRINT_OUT;Description Printing Outbound Service;Service Type HTTP Service

选完类型系统自动加 _REST 后缀,所以最终对象名是 ZPRINT_OUT_REST

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 ZPRINT;Description Communication scenario for printing

场景名后面代码里要用

3

选 TR → Finish

—

4

打开场景,Inbound 页签:Supported Authentication Methods 勾 Basic(X.509 可一起勾,不影响练习)

练习用 Basic 用户名密码

5

Inbound Services → Add → Inbound ID 0001,Inbound Service ID ZFORMPRINT_SRV_HTTP,Service Type HTTP Service → Finish

入站服务 ID 规律:<服务名>_HTTP

6

再 Add 一条:Inbound ID 0002,Inbound Service ID ZFORMTEMPLATE_SRV_HTTP

—

7

Outbound 页签:Supported Authentication Methods 勾 Basic;Outbound Services → Add → ZPRINT_OUT_REST

出站身份认证同样用 Basic

8

Ctrl+S 保存

先保存,再发布

新建通信场景 (📄 Day3 脚本:Name ZPRINT、Description Communication scenario for printing)

场景 Inbound 页(空) (📄 Day3 脚本:Inbound 页先勾认证方式,再从 Add 加入站服务;右上角是 Publish Locally)

加入站服务 0001 (📄 Day3 脚本:0001 → ZFORMPRINT_SRV_HTTP)

加入站服务 0002 (📄 Day3 脚本:0002 → ZFORMTEMPLATE_SRV_HTTP)

两个入站服务都在列表里 (📄 Day3 脚本:Inbound Services 两行齐全,下方能看到选中服务的明细)

Outbound 页挂出站服务 (📄 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

等操作完成(状态会从 Publishing 变成已发布,具体文案以本机 ADT 版本为准)

中途别改对象

验证(最硬的判据):打开 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 选 ZPRINT;Arrangement Name 填 ZPRINT → Create

场景选得到,说明 §3.3 发布成功

5

创建后进详情页,右侧 API-URL 先抄下来(形如 https://<租户>-api.lab.s4hana.cloud.sap)

下一步建通信系统要用它的主机名

Fiori 里的通信安排应用 (📄 Day3 脚本:Fiori 打开 Communication Arrangements;列表里能看到 SAP_COM_0466、SAP_COM_0106 等标准场景的安排)

新建安排选场景 (📄 Day3 脚本:Scenario ZPRINT、Arrangement Name ZPRINT → Create)

安排详情里的 API-URL (📄 Day3 脚本:先抄 API-URL;此时 Communication System 为空、入站用户未配)

4.2 建通信系统 ZPRINT2

步骤

操作

填什么 / 注意

1

安排详情的 Communication System 旁点 New

直接就地新建

2

System ID ZPRINT2;System Name ZPRINT2 → Create

System ID 就是代码里的 comm_system_id,别写错

3

General → Host Name 填 API-URL 的主机部分:去掉 https://、去掉结尾 /(示例:my402879-api.lab.s4hana.cloud.sap)

粘成整条 URL 一定连不上

4

Logical System 填 LOCAL;Port 填 443

回环调自己,逻辑系统写 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

选通信用户 PRINTUSER(§1.2 建的)→ 保存

对方(外部)调你时用的账号

3

Users for Outbound Communication → Add

弹窗 New Outbound User

4

Authentication Method User Name and Password;User Name/Client ID PRINTUSER;Password 填该通信用户的密码 → Create

你调对方(这里是调自己)时用的账号,练习里同一个用户即可

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

Active

不激活,出站调用直接失败

Path

/sap/bc/http/sap/zformprint_srv

出站要调的相对路径,从 §2.5 入站服务 ZFORMPRINT_SRV 的 URL 里抄下来

Port

443

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 → ZFORMTEMPLATE_SRV 行

https://<租户>-api.lab.s4hana.cloud.sap/sap/bc/http/sap/zformtemplate_srv

外部触发打印

安排 → Inbound Services → ZFORMPRINT_SRV 行

https://<租户>-api.lab.s4hana.cloud.sap/sap/bc/http/sap/zformprint_srv

出站代码取目的地

不用抄

create_by_comm_arrangement( comm_scenario = 'ZPRINT' comm_system_id = 'ZPRINT2' ) 自己解析

💡 开发租户的 URL 末尾常带 ?sap-client=<client>(截图环境是 080;本司 GQN 是 100),Postman 直接整条粘没问题。



6. 端到端联调(Day3 Part 2)

6.1 Postman 上传模板(走 ZFORMTEMPLATE_SRV)

步骤

操作

填什么

1

Postman 新建请求,方法选 POST

注意不是 GET

2

URL 粘贴 §4.5 表格里 ZFORMTEMPLATE_SRV 那条 Service URL

整条复制,含 ?sap-client=...

3

Authorization 页签:Type = Basic Auth,Username PRINTUSER,Password 通信用户密码

与 §4.3 入站用户一致

4

Body 页签:选 raw,右侧格式选 XML;用文本编辑器打开 .xdp 文件,全选 XML 内容粘进来

粘的就是模板本体

5

点 Send

—

Postman Basic 认证 (📄 Day3 脚本:Service URL 粘进 Postman,Authorization 选 Basic Auth + PRINTUSER)

Postman 粘贴模板 XML 并发送 (📄 Day3 脚本:Body → raw → XML,粘 .xdp 的 XML,Send 后右下角 Status: 200 OK)

验证:

  1. Postman 返回 200 OK(返回体为空是正常的,handler 没写 response);

  2. 回 ADT → 表 ZFORMTEMPLATE 右键 Open With → Data Preview:能看到 FORMID = ZDEMOTEST 一行,FORM_BINARY 有内容;

  3. 若返回 401/403/404/500,直接跳 §10 排错表。

6.2 在浏览器里点 Print

步骤

操作

说明

1

ADT 打开服务绑定 ZSB_ONLINE_SHOP → 展开 Entity Set ZI_ONLINE_SHOP → Preview

与 04 章同一个入口

2

列表里点一条订单(如 Order Id 1)进详情页

没有订单就先 Create 一条(Material Test-01、Quantity 10)

3

右上角点 Print

触发 print 动作 → 出站 → ZFORMPRINT_SRV → 队列

服务绑定里的 Preview (📄 Day3 脚本:Business Services → Service Bindings → ZSB_ONLINE_SHOP → Preview)

订单详情页上的 Print 按钮 (📄 Day3 脚本:进入一张 ShopOrder,点 Print)

验证:点完不弹错误;按钮执行完成后去 §6.3 看队列(界面成功不代表 PDF 已生成——真正的判据在队列)。

6.3 在打印队列和本机验收

步骤

操作

通过标准

1

Fiori 搜索应用 Maintain Print Queues → 点队列 DEVTEST

Items 里出现一条 OnlieShopOrder_<ORDER_UUID>

2

看该行字段

Status Successful、Format PDF、Item Size 几十 KB

3

(有 CPIM 时)看本机输出目录

文件名同队列项,PDF 能打开且字段正确

打印队列里的 PDF (📄 Day3 脚本:Maintain Print Queues → DEVTEST,队列项 OnlieShopOrder_FA163...,Status Successful)

本机落地的 PDF (📄 Day3 脚本:CPIM 拉取后 PDF 落到本机目录,内容是最初那张订单的字段)

验证(端到端三点全中才算成功):

  1. 队列里 有 以 OnlieShopOrder_ 开头的 PDF 项且 Successful;

  2. PDF 里 ORDERID / MATERIAL / QUANTITY / DELIVERYDATE 与订单一致;

  3. 本机目录(CPIM 里配置的 Queue Options 输出路径)能看到同名 .pdf。

💡 只想单独验证打印服务(绕开 RAP/出站)?用 Postman 直接 POST ZFORMPRINT_SRV 的 Service URL,Body 用 {"Order_Uuid":"<你的订单 UUID>"}。这一步能快速分清"是打印逻辑坏了"还是"出站配置坏了"。

6.4 用 Postman 直接调打印接口(排错必会)

步骤

操作

填什么

1

ADT 打开表 ZONLINESHOP → Open With → Data Preview,抄一条 ORDER_UUID(32 位十六进制)

订单主键,界面上是隐藏字段

2

Postman 新建 POST 请求,URL 用 §4.5 里 ZFORMPRINT_SRV 那条 Service URL

与上传模板用的是不同服务

3

Authorization → Basic Auth,PRINTUSER + 密码

同 §6.1

4

Body → raw → JSON,内容:{"Order_Uuid":"<刚抄的 UUID>"} → Send

注意字段名大小写与 §2.4 的 ls_input-Order_Uuid 对应

验证:返回 200(body 为空,正常);同时 DEVTEST 队列多出一条 OnlieShopOrder_<UUID>,Status Successful。


7. 概念与选型(跑通后再回头看,记得更牢)

7.1 四种入站通道

通道

建什么

适合

不适合

HTTP Service(本章)

ADT Connectivity → HTTP Service + 处理类

轻量自定义 REST(报文自己定)、回调/通知

结构化 CRUD、要自动生成元数据

OData Web API(RAP)

ZSD_* + Service Binding OData V4 – Web API

正式对外接口、结构化 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(证书)

安排里启用 X.509,需传证书管理

本章场景可选开启,练习不用

Principal Propagation

把终端用户身份透传到后端(BTP 场景)

未用;做"以用户身份调用"时才需要

自定义签名

第三方专用(如金税 HMAC-SHA1)

金税接口在用(§8.3)

红线:接口凭证不写死在代码里。练习用通信用户,存量用配置表,新接口一律走通信安排。

7.3 出站三条路怎么选

做法

何时用

代码长什么样

通信安排(本章)

新接口默认

create_by_comm_arrangement( comm_scenario = ... comm_system_id = ... )

配置表 + create_by_url(我司模式 C)

存量维护、目标系统多到不想逐个建安排

读表拿 URL/账号 → create_by_url → 手工 CSRF/JSON(§8.1)

EML

调标准业务对象(过账/冲销/改单)

MODIFY ENTITIES OF i_journalentrytp ...(§8.2)

生成代理类

老 SOAP 接口、报文巨大

NEW zco_* + cl_soap_destination_provider(§8.3)

7.4 连一个"标准 API"的标准流程

  1. 去 api.sap.com(SAP API Business Hub)搜业务对象,例如 API_OUTBOUND_DELIVERY_SRV;

  2. 在 API 文档页记下三件事:版本(;v=0002)、通信场景 ID(API 页会列出;本租户的通信安排列表里也能看到这类标准场景,如交货处理的 SAP_COM_0106)、限制/前置条件;

  3. 在 Fiori 建该标准场景的通信安排(不用在 ADT 建场景);

  4. 代码里 create_by_comm_arrangement( comm_scenario = '<该 API 的场景 ID>' comm_system_id = '<你的通信系统>' ),或按 §8.1 的 URL 方式直连;

  5. 先 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( ).

为什么当年这么做、为什么新接口别抄:

好处

代价

新增目标系统只加一行配置,不必逐个建通信安排/通信系统

① 密码明文落表 ZZPWD,安全审计过不了

回环调标准 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 我司出站接口去向(维护时先查这张表)

目标

场景(举例)

实现位置(相对四包 src/)

本系统标准 API

SO→DN 过账、退货、改金额

sap-zzsd-master:zzfg_sd_api.fugr.zzfm_pub_*

MES

BOM/生产订单/报工推送

sap-zzpp-master:zzfg_pp_api.fugr.zzfm_pp_006*

WMS

交货/预留/委外推送

SD zzcl_api_sd*、MM zzcl_api_mm016

旺店通/领星

交货/发货/入库

ZZT_MM002_WDT/_LX 结果表对应 FM

OA/钉钉/数字人力

审批发起/回传

ZZTSD012、ZZTFI011 链路

诺诺金税

开票/红冲/查询

sap-fi-master:zzfg_fi_nn.fugr.zfm_gtax_*

TMS 银行

流水拉取/回款

sap-fi-master:zzfg_fi_tms.fugr.zzfm_fi006


9. 新增一个接口的标准步骤(照此执行)

#

步骤

判据

1

API Hub 确认目标 API 的版本/字段/限制,抄下通信场景 ID

文档页能看到 scenario ID

2

领号 + 建 ZZS_xNN_REQ/RESP(+resp_json)结构与表类型

结构随对象一起进 TR

3

选通道:新项目走通信场景+安排;存量维护才用配置表

评审时能说清为什么

4

实现:ZZFM_API_xNN 薄壳(校验/回编号)+ ZZFM_PUB_xNN 实现(或类方法)

壳与实现分离,便于重试/测试

5

JSON 映射集中定义 name_mappings,响应必须解析并落结果表

结果表能查到每次调用的成败

6

失败可重试:接 06 章 Application Job 轮询结果表补推

Job 能捞出失败记录

7

权限:通信用户/业务角色按最小权限给(08 章)

用业务用户验证过

8

台账登记:接口名/方向/认证方式/配置键/结果表/负责人

台账里能搜到


10. 排错清单(照症状查)

现象

最可能原因

怎么查 / 怎么修

Postman 401

用户名/密码错;通信用户没密码;用成了普通业务用户

用安排里 Inbound User 的账号;Maintain Communication Users 里重设密码

Postman 403

通信用户缺权限(IAM/业务角色);服务授权默认值没配

查该用户角色(08 章);服务页的 Configure authorization default values 入口

Postman 404

URL 抄错(少了 /sap/bc/http/sap/);服务没激活;场景里没加这个入站服务

对着安排里的 Service URL 整条复制;确认场景 Inbound 列表有它

Postman 500

handler 运行时报错(模板表空、ADS 不可用、字段没赋值)

在 CATCH 里临时 response->set_status( i_code = 500 i_reason = 'Error' ) + response->set_text( lv_error ),再调一次看报错文本

返回 200 但表里没数据

请求方法不是 POST(CASE 没命中);表被别的行覆盖

确认 Postman 方法是 POST;Data Preview 查 FORMID

Print 报 communication system not found

comm_system_id 与 Fiori 里的 System ID 不一致;安排没保存

核对 ZPRINT2;安排必须 Editing Status = Active

Print 报 no destination / arrangement not found

场景没 Publish locally;安排里缺出站服务或 Path 为空

重发场景;出站 Path 填 /sap/bc/http/sap/zformprint_srv

Print 界面无反应

print 方法 CATCH 吞了错误(脚本原样写法)

临时把错误写进 reported 或打日志;见 §5.3

队列里没有项,但 Print 成功

出站 POST 没到打印服务(场景/路径/用户错)

用 Postman 直接打 ZFORMPRINT_SRV(§6.3 提示),二分定位

队列有项但本机没 PDF

CPIM 没启动/没连租户/输出目录不对

查 CPIM 连接状态与 Queue Options 输出路径

PDF 空白或字段错位

.xdp 与 XSD 不匹配(03/04 章的字段改过)

重新 get_xsd( ) 生成数据源,在 Designer 里重绑字段


11. 本章检查清单

  • 能画出"通信场景 → 通信安排 → 通信系统/通信用户"的关系,并说清谁在 ADT 建、谁在 Fiori 配

  • 两个 HTTP Service(ZFORMTEMPLATE_SRV、ZFORMPRINT_SRV)已建、handler 完整、激活无错

  • 通信场景 ZPRINT 的 Inbound 有 2 条、Outbound 有 1 条,已 Publish locally

  • 通信系统 ZPRINT2 的 Host Name 已去 https://,Port 443;安排 Active

  • Postman 用 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)


➡️ 下一步