sap-btp-job-scheduling

SAP BTP 作业调度服务

相关技能

• sap-dependency-security：当作业调度微服务维护 npm/CLI 依赖堆栈时，用于强化依赖项和工作流安全性

目录

• 概述
• 何时使用此技能
• 快速决策树
• 核心概念
• 服务限制
• 快速参考表
  • 计划格式
  • Cron 格式（7 个字段）
  • 计划生命周期状态
  • 作业的 HTTP 方法
• 最佳实践
  • 调度优化
  • 异步作业
  • 一次性计划
• 身份验证快速入门
  • 标准计划（OAuth 2.0）
  • xs-security.json 配置
• 创建作业示例
• Node.js 客户端库
• 速率限制
• 服务行为
  • 中断恢复
  • 自动停用触发条件
• 捆绑资源
• 常见问题
• 外部资源
• 更新与维护

概述

SAP Job Scheduling Service 是一项与运行时无关的平台服务，可在 SAP BTP 上定义和管理一次性及重复作业，或 Cloud Foundry 任务。它可在多个超大规模云服务提供商（AWS、Azure、GCP）上运行，无需修改应用程序。

文档来源：https://help.sap.com/docs/job-scheduling

上次验证时间：2025-11-27

何时使用此技能

在以下情况下使用此技能：

• 设置 Job Scheduling Service，用于 Cloud Foundry 或 Kyma 运行时
• 通过 REST API 或仪表板创建和管理作业
• 使用 cron、日期/时间或人类可读格式配置计划
• 为长时间运行的进程实现异步作业执行
• 使用 OAuth 2.0 和 XSUAA 保护操作端点
• 与 SAP Cloud ALM 或 Alert Notification Service 集成
• 开发多租户应用程序，实现支持租户感知的作业调度
• 排查作业执行问题和计划失败
• 使用 Node.js 客户端库（@sap/jobs-client）

快速决策树

要执行什么任务？

Setup & Configuration
├─ Initial setup prerequisites → references/setup-guide.md
├─ Create service instance
│  ├─ BTP Cockpit → references/setup-guide.md#cockpit
│  ├─ CF CLI → references/setup-guide.md#cf-cli
│  └─ Kyma Dashboard → references/setup-guide.md#kyma
└─ Configure XSUAA scopes → references/security.md

Job Management
├─ Create jobs → references/rest-api.md#create-job
├─ Configure schedules → references/rest-api.md#schedules
├─ Run logs & monitoring → references/rest-api.md#run-logs
└─ Dashboard operations → references/operations.md#dashboard

Schedule Configuration
├─ One-time vs recurring → references/concepts.md#schedule-types
├─ Cron format → references/concepts.md#cron-format
├─ Date/time formats → references/concepts.md#date-formats
└─ Human-readable → references/concepts.md#human-readable

Asynchronous Execution
├─ Async mode flow → references/concepts.md#async-mode
├─ Callback implementation → references/rest-api.md#update-run-log
└─ CF tasks → references/concepts.md#cf-tasks

Security & Authentication
├─ OAuth 2.0 setup → references/security.md#oauth
├─ XSUAA configuration → references/security.md#xsuaa
└─ Credential rotation → references/security.md#rotation

Integrations
├─ SAP Cloud ALM → references/integrations.md#cloud-alm
└─ Alert Notification → references/integrations.md#alert-notification

Troubleshooting
├─ Common errors → references/troubleshooting.md#errors
├─ FAQ → references/troubleshooting.md#faq
└─ Support: BC-CP-CF-JBS

Version History & Updates
└─ What's New (2021-2025) → references/changelog.md

核心概念

作业

由多个计划和一个操作端点组成的集合。作业会在指定时间同步调用（短时操作）或异步调用（长时间运行的进程）已配置的 URL。

计划

作业中的一次性或重复实体。支持多种格式（cron、日期/时间、人类可读），并有三种生命周期状态：SCHEDULED → RUNNING → COMPLETED。

操作端点

应用程序公开的 HTTP/REST 端点，服务会在计划触发时调用该端点。在生产环境中必须使用 OAuth 2.0 进行保护。

Cloud Foundry 任务

在自己的容器中独立运行的应用程序或脚本。始终以异步方式执行，并可配置内存分配。

服务限制

限制	值
最短计划间隔	5 分钟
同步请求超时	15 秒
异步超时（默认）	30 分钟（最长可配置为 7 天）
POST 请求正文大小限制	100 KB
运行日志保留时间	15 天
服务 SLA	距计划时间约 20 分钟

快速参考表

Schedule 格式

格式	示例	用例
Cron	* * * * 10:12 0,30 0	10:00-12:00 之间每 30 分钟执行一次
Date/Time	2025-10-20T04:30:00Z	ISO-8601 格式的一次性执行
Human-readable	tomorrow at 4pm	使用自然语言安排计划
repeatInterval	2 hours, 5 minutes	按固定间隔重复执行
repeatAt	4.40pm, 18:40	每天在指定时间执行

Cron 格式（7 个字段）

Year Month Day DayOfWeek Hour Minute Second
*    *     *   *         *    *      *

字段	值	特殊语法
Year	4 位数字（2025）	* = 任意值
Month	1-12	*/a = 每隔 a 个
Day	-31 到 31	负数 = 从末尾开始
DayOfWeek	mon、tue、wed...	a.y = 第 a 个出现项
Hour	0-23	a:b = 范围
Minute	0-59	a:b/c = 范围内步长
Second	0-59	a,b,c = 多个值

计划生命周期状态

阶段	状态	描述
SCHEDULED	SCHEDULED	已排队，等待未来执行
RUNNING	TRIGGERED、ACK_RECVD、ACK_NOT_RECVD	正在执行
COMPLETED	SUCCESS、ERROR、REQUEST_ERROR、UNKNOWN	已完成

作业的 HTTP 方法

方法	端点	用途
POST	/scheduler/jobs	创建作业
GET	/scheduler/jobs	列出所有作业
GET	/scheduler/jobs/{id}	获取作业详情
PUT	/scheduler/jobs/{id}	更新作业
DELETE	/scheduler/jobs/{id}	删除作业

最佳实践

计划优化

避开高峰时段：

• ❌ 每分钟的第 0 秒或第 30 秒
• ❌ 第 0 分钟、第 30 分钟或每隔 5 分钟
• ❌ 每小时整点
• ❌ UTC 午夜（最繁忙时段）

使用不规则时间：

• ✅ 使用 01:12:17，而不是 01:00:00
• ✅ 使用 01:38:37，而不是 01:30:00

异步作业

1. 立即返回 202 Accepted - 不要阻塞请求
2. 存储请求头 - x-sap-job-id、x-sap-job-schedule-id、x-sap-job-run-id、x-sap-scheduler-host
3. 完成后更新运行日志 - 使用一次 API 调用提交最终状态
4. 处理超时 - 默认 30 分钟，最长可配置为 7 天

一次性计划

• 仅用于测试/验证
• 执行后自动停用
• 立即执行时使用 "time": "now"

快速入门：身份验证

Standard Plan（OAuth 2.0）

# Get access token
curl -X POST "<uaa_url>/oauth/token" \
  -H "Authorization: Basic $(echo -n '<clientid>:<clientsecret>' | base64)" \
  -d "grant_type=client_credentials"

# Use token in API calls
curl -X GET "https://jobscheduler-rest.<landscape>/scheduler/jobs" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json"

xs-security.json 配置

{
  "xsappname": "<app-name>",
  "scopes": [{
    "name": "$XSAPPNAME.JOBSCHEDULER",
    "description": "Job Scheduler Scope",
    "grant-as-authority-to-apps": ["$XSSERVICENAME(<jobscheduler-instance>)"]
  }]
}

创建作业示例

POST /scheduler/jobs
{
  "name": "myJob",
  "description": "Process daily reports",
  "action": "https://myapp.cfapps.eu10.hana.ondemand.com/api/process",
  "active": true,
  "httpMethod": "POST",
  "schedules": [{
    "active": true,
    "description": "Daily at 6 AM",
    "repeatAt": "6.00am",
    "startTime": {"date": "2025-01-01", "format": "YYYY-MM-DD"}
  }]
}

Node.js 客户端库

要求：Node.js 14.x 或更高版本

npm install @sap/[email protected]

const JobSchedulerClient = require('@sap/jobs-client');
const scheduler = new JobSchedulerClient.Scheduler();

// Create job
scheduler.createJob({ url: vcapServices.jobscheduler[0].credentials.url }, {
  name: 'myJob',
  action: 'https://myapp.../process',
  active: true,
  httpMethod: 'GET',
  schedules: [{ cron: '* * * * 0 0 0', active: true }]
}, (err, result) => { /* handle */ });

速率限制

限制类型	响应代码	标头
超出客户端限制	429	retry-after（秒）
超出绝对限制	503	throttling（毫秒）

限制会叠加，可能同时生效。

服务行为

中断恢复

中断时长	行为
< 20 分钟	立即运行所有错过的执行
>= 20 分钟	仅运行最近一次错过的执行

自动停用触发条件

• 一次性计划已执行
• 不存在有效的未来日期
• 作业/计划已达到 endTime
• 操作端点连续 10 天以上无法访问

参考文件

可用的详细指南

1. references/concepts.md - 计划类型、格式、生命周期、异步模式、多租户
2. references/rest-api.md - 完整的 REST API 参考，包含所有端点
3. references/setup-guide.md - 前置条件、服务实例创建
4. references/security.md - OAuth 2.0、XSUAA 作用域、凭据轮换
5. references/integrations.md - Cloud ALM、Alert Notification Service
6. references/troubleshooting.md - 常见问题、错误场景、监控
7. references/operations.md - 仪表板、备份/恢复、服务行为
8. references/changelog.md - 版本历史、功能更新（2021-2025）

可用模板

1. templates/job-creation.json - 作业创建请求模板
2. templates/xs-security.json - XSUAA 配置模板

常见陷阱

设置：

• ❌ 在绑定 Job Scheduling 之前未绑定 XSUAA
• ❌ 未通过 grant-as-authority-to-apps 授予作用域
• ❌ 对操作端点使用 HTTP 而非 HTTPS

调度：

• ❌ 使用 Linux cron 格式（服务使用 SAP cron）
• ❌ 在高峰时段（00:00、00:30 等）安排任务
• ❌ 忘记使用 UTC 时区（唯一支持的时区）

异步作业：

• ❌ 未立即返回 202 Accepted
• ❌ 忘记调用 Update Run Log API
• ❌ 多次更新状态，而非仅进行一次最终更新

多租户：

• ❌ 对 SaaS 租户令牌使用 tenantId 过滤器（返回 400）
• ❌ 未将 Job Scheduling 添加为应用程序依赖项

外部资源

SAP 文档

• SAP Help Portal：https://help.sap.com/docs/job-scheduling
• SAP Developer Center：https://developers.sap.com/

支持

• 组件：BC-CP-CF-JBS
• SAP Trust Center：平台状态验证
• Guided Answers：自助故障排除

更新和维护

来源：SAP BTP Job Scheduling Service 文档

更新此技能：

1. 检查 GitHub 仓库中的文档更新
2. 查看 What's New 部分，了解变更
3. 更新受影响的参考文件
4. 如果配置有变更，则更新模板
5. 更新“上次验证”日期

建议每季度审查：每 3 个月检查一次更新

下次审查：2026-02-27

随附资源

参考文件

1. references/concepts.md - 调度类型、格式、生命周期、异步模式、多租户（12K 行）
2. references/rest-api.md - 完整的 REST API 参考，包含所有端点（20K 行）
3. references/setup-guide.md - 前提条件、服务实例创建（9K 行）
4. references/security.md - OAuth 2.0、XSUAA 作用域、凭据轮换（11K 行）
5. references/integrations.md - Cloud ALM、Alert Notification Service（8K 行）
6. references/troubleshooting.md - 常见问题、错误场景、监控（9K 行）
7. references/operations.md - 仪表板、备份/恢复、服务行为（8K 行）
8. references/changelog.md - 版本历史、功能更新（2021-2025）（9K 行）

模板

1. templates/job-creation.json - 作业创建请求模板，附带示例
2. templates/xs-security.json - 用于 OAuth 作用域的 XSUAA 配置模板

---

许可证：GPL-3.0 维护者：Eduard Jiglau | [email protected] | sap-ai-skills.com | https://github.com/secondsky/sap-skills