Bitzsoft.Integrations.SapS4Hana 1.0.0-alpha.10

Bitzsoft.Integrations.SapS4Hana

SAP S/4HANA Business Partner (A2X) OData v2 多租户连接器，目标框架为 net5.0;net8.0;net10.0。

当前只实现商业价值明确、契约边界可证明的 Business Partner 主数据切片：

• SAP_COM_0008 通信场景与 API_BUSINESS_PARTNER 精确服务根；
• Basic、OAuth2 Client Credentials、证书型 mTLS 通信用户；
• A_BusinessPartner 单条读取、受控字段选择和稳定键集分页；
• 仅允许停用、搜索词和往来语言字段的部分更新；
• 写入前同一 HTTP 会话获取 CSRF token、保留 session cookie，并强制调用方 提供 ETag；
• 可恢复但仅显式 SyncMode.Full 的 Business Partner 全量同步与结束后对账。

普通业务请求和响应正文完整传递，不设置连接器级或 RequestLogging 强制大小上限。 认证头、Cookie 与 X-CSRF-Token 必须脱敏。连接器不会把供应商错误正文写入异常， 也不会自动重试可能已生效的写操作。

安装与前置条件

dotnet add package Bitzsoft.Integrations.SapS4Hana

首次生产接入必须具备目标租户、SAP_COM_0008 通信安排和可执行 sandbox 契约测试。

配置

通信安排中复制的是完整 inbound service URL，而不是任意系统根地址：

var endpoint = new SapS4HanaEndpointProfile(
    profileId: "production",
    transport: new RestEndpoint(
        new Uri(
            "https://my-system-api.s4hana.cloud.sap/"
            + "sap/opu/odata/sap/API_BUSINESS_PARTNER/"),
        RestAuthenticationMode.OAuth2ClientCredentials,
        oauthTokenEndpoint: new Uri("https://oauth.example/token"),
        oauthScopes: new[] { "configured-sap-scope" },
        useMutualTls: true),
    communicationArrangementId: "SAP-BP-OUTBOUND");

services.AddBitzsoftSapS4Hana(
    new[] { endpoint },
    new[]
    {
        new SapS4HanaSyncProfile(
            endpointProfileId: "production",
            credentialName: "sap-business-partner")
    });

生产宿主必须自行提供加密、按租户解析的 IIntegrationCredentialResolver。Basic 凭据字段为 Username、Password； OAuth2 使用 REST 底座标准的 OAuthClientId、OAuthClientSecret；mTLS 证书仍由 IRestHttpClientLeaseFactory 按租户加载，不放入 endpoint profile。

读取与写入

var context = new SapS4HanaRequestContext(
    tenantId: "host-tenant",
    profileId: "production",
    credentialName: "sap-business-partner");

var page = await client.ListBusinessPartnersAsync(
    context,
    afterBusinessPartner: null,
    pageSize: 200);

var updated = await client.UpdateBusinessPartnerAsync(
    context,
    businessPartner: "1000001",
    expectedETag: current.ETag!,
    update: new SapBusinessPartnerUpdate(isBlocked: true));

写入成功后的回读如果失败，异常会以 OutcomeUnknown=true 返回；调用方应先按主键 读取并核对状态，不得盲目重试。

同步

var result = await engine.RunAsync(
    new SyncRunRequest(
        jobKey,
        mode: SyncMode.Full,
        pageSize: 200),
    source,
    sink,
    reconciler);

不要使用 Automatic。通用同步引擎在第一次完整运行后会把它解析为 Incremental， 但 Business Partner A2X 没有跨部署均可证明的闭合删除日志或 delta token。本连接器 会用 full_sync_required 明确拒绝增量，删除只能在成功完成 Full 后由 reconciler 识别。暂停或失败的运行不得触发删除。

未实现边界

当前不提供任意 entity set/filter/write、deep insert、batch write、自定义字段、 CDS View、IDoc、RFC/BAPI、Enterprise Event Enablement，或财务、采购、销售等 其他 SAP 模块。它们只有在出现明确客户场景、可测试租户和可证明契约后再单独评估， 不因“覆盖面”而扩张。

官方契约：

• https://help.sap.com/docs/SAP_S4HANA_CLOUD/3c916ef10fc240c9afc594b346ffaf77/85043858ea0f9244e10000000a4450e5.html
• https://help.sap.com/docs/odata-provisioning/odata-provisioning/session-security-protection
• https://www.odata.org/documentation/odata-version-2-0/