Bitzsoft.Integrations.ServiceNow 1.0.0-alpha.10

Bitzsoft.Integrations.ServiceNow

ServiceNow ITSM 多租户连接器，提供 OAuth 2.0 Client Credentials、安全的 Table API Incident 读取与可恢复同步，支持 net5.0、net8.0 与 net10.0。

安装

dotnet add package Bitzsoft.Integrations.ServiceNow

已实现能力

• 官方实例或显式可信私有 endpoint profile；
• 按 tenant/profile/instance/scope/凭据隔离的 single-flight token 缓存；
• 业务 GET 遇到 401 时失效 token 并安全重放一次；
• 限流头、Retry-After、稳定错误和取消语义；
• Incident get/list、完整 Raw 与仅限 u_ 的附加字段；
• active/state/group/company/updated-time 受控过滤；
• 绑定实例、API 路径和查询形状的短期分页游标；
• Incident Full/Incremental Sync。

本包不接受任意 encoded query，不提供通用 Table API 写入，也不把实例审计表声明成可靠的 通用删除日志。

凭据、权限与实例配置

生产宿主必须提供 Vault/KMS 支撑的 IIntegrationCredentialResolver。凭据字段为：

OAuthClientId
OAuthClientSecret

ServiceNow 应用至少需要目标 Incident 表及所请求字段的读取权限。字段 ACL 可能导致记录 存在但字段缺失，也可能出现分页空洞；应使用与生产一致的角色在非生产实例做契约认证。

services.AddBitzsoftServiceNow(
    ServiceNowEndpointProfile.CreateOfficial(
        new Uri("https://your-instance.service-now.com/")),
    new[]
    {
        new ServiceNowIncidentSyncProfile("Incidents")
    });

多租户宿主实现 IServiceNowEndpointProfileResolver 与 IServiceNowIncidentSyncProfileResolver，再使用 AddBitzsoftServiceNow<TEndpointProfileResolver, TSyncProfileResolver>()。

查询与分页

var context = new ServiceNowRequestContext(
    tenantId: "customer-a",
    profileId: "production",
    credentialName: "servicenow-app");

var incident = await client.GetIncidentAsync(
    context,
    sysId: "0123456789abcdef0123456789abcdef",
    additionalFields: new[] { "u_business_service" },
    cancellationToken);

var query = new ServiceNowIncidentQuery(
    pageSize: 200,
    filter: new ServiceNowIncidentFilter(
        active: true,
        updatedAtOrAfter: DateTimeOffset.UtcNow.AddDays(-1)),
    additionalFields: new[] { "u_business_service" });

var page = await client.QueryIncidentsAsync(
    context,
    query,
    cancellationToken);

while (page.NextCursor is not null)
{
    page = await client.QueryMoreIncidentsAsync(
        context,
        query,
        page.NextCursor,
        cancellationToken);
}

游标是短期 opaque 值，只能和创建它的 tenant/profile/query/fields/page size 一起使用。 短页和空页不等于结束；连接器按受验证的 Link 与水位判断后续页。

同步语义

• Full 从受认证响应的 HTTP Date 固定创建时间上界，再按 sys_id 键集扫描；
• ACL 导致空页时，只在同一键集位置使用经校验的 offset Link；
• Incremental 从已提交水位回叠 overlap，并固定新的服务端上界；
• 增量排序键为 (sys_updated_on, sys_id)；
• sys_mod_count 作为记录内单调版本序号；
• continuation 绑定 tenant/provider/stream/sink/profile/run/page shape；
• 只有最终页才能替换 delta checkpoint。

active=false 是普通更新而非删除。Table API 没有可靠、通用的 hard-delete feed， 删除漂移必须通过周期性、完整成功的 Full reconcile 发现。

安全、日志与故障处理

• 官方实例强制 HTTPS；自定义代理必须显式登记可信主机；
• token 请求和响应正文按凭据抑制；
• 普通业务正文完整传递，不设置强制日志大小上限；
• 供应商原始错误正文不写入异常，使用稳定错误码、FailureKind 和 RetryAfter；
• 只有只读 GET 在明确 token 失效时自动重放；
• POST/PATCH 不声明幂等，不应在超时或连接中断后盲目重试；
• 所有异步 API 支持取消，取消不计为供应商失败。

当前边界

当前只覆盖 Incident 读取与同步，不包含创建/更新 Incident、附件、CMDB、Change、 Problem、Service Catalog、Webhook 或 IntegrationHub。新增对象应基于明确客户场景、 目标实例 ACL 与可执行契约测试独立评估。