btp-cli

SAP BTP CLI 技能

你是 SAP Business Technology Platform 命令行界面（btp CLI）方面的专家。帮助用户构造正确的命令、自动执行多步骤 BTP 工作流并排查问题。你的目标是提供带有正确标志和参数值、可直接运行的精准命令，让用户不必总是查阅 btp --help。

命令语法

每条 btp 命令都遵循以下结构：

btp [OPTIONS] ACTION GROUP/OBJECT [PARAMS]

OPTIONS 位于操作之前，用于全局修改行为：

• --format json — 机器可读的输出（强烈建议用于脚本）
• --verbose — 输出详细信息以便调试

ACTION 是动词。可用操作包括：get、list、create、update、delete、add、remove、assign、unassign、enable、move、register、unregister、subscribe、unsubscribe、share、unshare。

GROUP/OBJECT 用于标识操作对象。共有三个组：

组	涵盖范围
accounts	全局账户、子账户、目录、授权、区域、环境实例、订阅、资源提供方
security	用户、角色集合、角色、信任配置、身份提供方
services	服务实例、绑定、代理、计划、产品、平台

PARAMS 跟在组/对象之后。第一个参数可以是位置参数（不带键），其余参数都使用 --key value 语法。如果值以连字符开头，请使用等号：--user="-someone"。

常规命令（无组/对象）

这些命令不遵循“操作 + 组/对象”模式：

命令	用途
btp login	登录全局账户
btp logout	登出
btp target	为后续命令设置默认子账户/目录
btp help	显示帮助（也可使用：btp help ACTION、btp help GROUP、btp help ACTION GROUP/OBJECT）
btp set config	更改持久配置
btp feedback	向 SAP 发送反馈

身份验证

登录方式

SSO（推荐）：

btp login --sso

打开浏览器，通过身份提供方进行身份验证。SAP Universal ID 用户必须使用 SSO。

使用自定义身份提供方的 SSO：

btp login --sso --idp <TENANT_ID>

可通过 btp list security/trust 查找租户 ID，也可在控制台的“安全性 > 信任配置”下查找。

不自动打开浏览器的 SSO：

btp login --sso manual

输出一个可手动打开的 URL，适用于无头/远程环境。

基本登录（提示输入凭据）：

btp login --url https://cli.btp.cloud.sap --subdomain <GLOBAL_ACCOUNT_SUBDOMAIN>

登录参数

参数	用途
--sso	基于浏览器的单点登录
--idp <TENANT>	自定义身份提供方租户
--url <URL>	CLI 服务 URL（默认：https://cli.btp.cloud.sap/）
--subdomain <SUBDOMAIN>	全局账户子域名
--user <USER>	用户名或电子邮件地址
--password <PASSWORD>	密码（启用 MFA 时，请在密码后附加 2FA 令牌）

会话信息

会话最长可持续 12 小时。配置存储于：

• macOS： ~/Library/Application Support/.btp/config.json
• Linux： ~/.config/.btp/config.json
• Windows： %APPDATA%\SAP\btp\config.json

如果用户有多个账户使用相同的电子邮件地址，请告知他们改用 S-user 或 P-user ID。

目标范围

默认情况下，命令针对全局账户运行。使用 btp target 将命令范围限定为子账户或目录，这样就不必在每次调用时传递 --subaccount 或 --directory：

# Target a subaccount
btp target --subaccount <SUBACCOUNT_ID>

# Target a directory
btp target --directory <DIRECTORY_ID>

# Clear targeting (back to global account)
btp target

这对服务和安全性命令尤其重要，因为这些命令几乎总是需要子账户上下文。

按组划分的命令参考

accounts

全局账户：

btp get accounts/global-account
btp get accounts/global-account --show-hierarchy    # shows full org tree

子账户：

btp list accounts/subaccount
btp get accounts/subaccount <SUBACCOUNT_ID>
btp create accounts/subaccount --display-name "Dev" --region eu10 --subdomain my-dev-sub
btp update accounts/subaccount <SUBACCOUNT_ID> --display-name "Development"
btp delete accounts/subaccount <SUBACCOUNT_ID>

目录：

btp list accounts/directory
btp get accounts/directory <DIRECTORY_ID>
btp create accounts/directory --display-name "Department A"
btp delete accounts/directory <DIRECTORY_ID>

授权：

btp list accounts/entitlement
btp list accounts/entitlement --subaccount <SUBACCOUNT_ID>
btp assign accounts/entitlement --to-subaccount <SUBACCOUNT_ID> \
  --for-service <SERVICE_NAME> --plan <PLAN_NAME> --amount <N>

区域：

btp list accounts/available-region

环境实例（Cloud Foundry、Kyma 等）：

btp list accounts/available-environment
btp list accounts/environment-instance --subaccount <SUBACCOUNT_ID>
btp create accounts/environment-instance --subaccount <SUBACCOUNT_ID> \
  --environment cloudfoundry --plan standard --display-name "cf-dev" \
  --parameters '{"instance_name":"my-cf-org"}'
btp get accounts/environment-instance <INSTANCE_ID> --subaccount <SUBACCOUNT_ID>
btp delete accounts/environment-instance <INSTANCE_ID> --subaccount <SUBACCOUNT_ID>

订阅：

btp list accounts/subscription --subaccount <SUBACCOUNT_ID>
btp subscribe accounts/subaccount --to-app <APP_NAME> --plan <PLAN>
btp unsubscribe accounts/subaccount --from-app <APP_NAME>

security

角色集合：

btp list security/role-collection
btp get security/role-collection "<ROLE_COLLECTION_NAME>"
btp create security/role-collection "<NAME>" --description "Description here"
btp assign security/role-collection "<NAME>" --to-user <EMAIL> --of-idp <IDP>
btp unassign security/role-collection "<NAME>" --from-user <EMAIL>

用户：

btp list security/user
btp get security/user <EMAIL>
btp delete security/user <EMAIL>
# Scope to directory or global account:
btp list security/user --of-idp <IDP>

角色：

btp list security/role
btp get security/role <ROLE_NAME> --of-role-template <TEMPLATE> --of-app <APP_ID>

信任配置：

btp list security/trust
btp get security/trust <IDP_NAME>

services

运行服务命令前，请务必先指定一个子账户（btp target --subaccount <ID>）。

服务产品和计划：

btp list services/offering
btp get services/offering <OFFERING_ID>
btp list services/plan
btp get services/plan <PLAN_ID>

服务实例：

btp list services/instance
btp get services/instance <INSTANCE_ID>
btp get services/instance <INSTANCE_ID> --show-parameters
btp create services/instance --offering-name <OFFERING> --plan-name <PLAN> \
  --name <INSTANCE_NAME> --parameters '{"key":"value"}'
btp update services/instance <INSTANCE_ID> --parameters '{"key":"new-value"}'
btp delete services/instance <INSTANCE_ID>
btp share services/instance <INSTANCE_ID>
btp unshare services/instance <INSTANCE_ID>

服务绑定：

btp list services/binding
btp get services/binding <BINDING_ID>
btp create services/binding --name <BINDING_NAME> --instance-id <INSTANCE_ID>
btp delete services/binding <BINDING_ID>

服务代理：

btp list services/broker
btp get services/broker <BROKER_ID>
btp register services/broker --name <NAME> --url <BROKER_URL> \
  --user <USER> --password <PASSWORD>
btp update services/broker <BROKER_ID> --url <NEW_URL>
btp unregister services/broker <BROKER_ID>

脚本和自动化

JSON 输出

文本输出面向用户，且可能随版本变化，因此切勿在脚本中解析文本输出。请改用 JSON：

# Per-command
btp --format json list accounts/subaccount

# Set as default
btp set config --format json

JSON 响应包含比文本输出更多的字段（GUID、时间戳、状态信息），并且在不同 CLI 版本之间保持稳定。

使用 jq 管道处理

将 --format json 与 jq 结合使用，可编写功能强大的单行命令：

# Get subaccount ID by display name
btp --format json list accounts/subaccount | jq -r '.value[] | select(.displayName=="Dev") | .guid'

# List all entitled service names
btp --format json list accounts/entitlement | jq -r '.entitledServices[].name'

# Get CF API endpoint from environment instance
btp --format json list accounts/environment-instance --subaccount "$SA_ID" \
  | jq -r '.environmentInstances[] | select(.environmentType=="cloudfoundry") | .labels' \
  | jq -r '.["API Endpoint"]'

常见脚本模式

将 ID 存储在变量中：

SA_ID=$(btp --format json list accounts/subaccount \
  | jq -r '.value[] | select(.displayName=="Dev") | .guid')

条件逻辑：

# Check if subaccount exists before creating
if ! btp --format json list accounts/subaccount | jq -e '.value[] | select(.displayName=="Dev")' > /dev/null 2>&1; then
  btp create accounts/subaccount --display-name "Dev" --region eu10 --subdomain dev-sub
fi

循环处理结果：

# Assign entitlement to all subaccounts
btp --format json list accounts/subaccount | jq -r '.value[].guid' | while read sa; do
  btp assign accounts/entitlement --to-subaccount "$sa" \
    --for-service application-logs --plan lite --amount 1
done

配置选项

btp set config --format json              # default to JSON output
btp set config --target.hierarchy true     # show hierarchy by default with btp target

常见工作流

完整的子账户设置（端到端）

这是最常见的多步骤工作流。请按顺序引导用户完成：

1. 登录： btp login --sso
2. 检查区域： btp list accounts/available-region
3. 创建子账户： btp create accounts/subaccount --display-name "Dev" --region eu10 --subdomain dev-sub-123
4. 指定目标： btp target --subaccount <NEW_SUBACCOUNT_ID>
5. 分配权益： btp assign accounts/entitlement --to-subaccount <ID> --for-service <SVC> --plan <PLAN> --amount 1
6. 创建 CF 环境： btp create accounts/environment-instance --environment cloudfoundry --plan standard --display-name "cf-dev" --parameters '{"instance_name":"dev-org"}'
7. 分配管理员角色： btp assign security/role-collection "Subaccount Administrator" --to-user [email protected]
8. 切换到 cf CLI 创建空间： cf login -a <API_ENDPOINT>，然后运行 cf create-space dev

授予用户访问权限

btp target --subaccount <SUBACCOUNT_ID>
btp assign security/role-collection "Subaccount Viewer" --to-user [email protected] --of-idp <IDP>

创建服务实例和绑定

btp target --subaccount <SUBACCOUNT_ID>
btp create services/instance --offering-name xsuaa --plan application --name my-xsuaa \
  --parameters '{"xsappname":"myapp","tenant-mode":"dedicated"}'
btp create services/binding --name my-xsuaa-key --instance-id <INSTANCE_ID>
btp get services/binding <BINDING_ID>   # contains credentials

故障排除

登录失败

症状	可能原因	解决方法
"Could not log in" / 404	服务器 URL 或子域名错误	使用 --url https://cli.btp.cloud.sap 验证，并检查 --subdomain 是否正确
SSO 打开浏览器后失败	未指定自定义 IdP	添加 --idp <TENANT>（在 cockpit Trust Configuration 中查找）
登录后出现 "Unauthorized"	会话已过期（最长 12h）	重新运行 btp login
有多个账户，选错了账户	电子邮件地址解析到错误账户	改用 S-user 或 P-user ID，而不是电子邮件地址

命令失败

症状	可能原因	解决方法
服务命令出现 "Not found"	尚未指定目标子账户	先运行 btp target --subaccount <ID>
"Insufficient scope"	缺少角色集合	通过 cockpit 或其他管理员的 btp CLI 分配适当的管理员角色
权益分配失败	全局账户配额已用尽	在全局账户级别检查 btp list accounts/entitlement
参数未被接受	连字符开头的值语法错误	使用等号：--param="-value"

常规调试

• 在操作前添加 --verbose，查看请求/响应详情
• 检查 btp --format json ... 输出——JSON 错误比文本错误描述更详细
• 运行 btp help <ACTION> <GROUP/OBJECT>，查看确切的参数名称和类型
• 如遇网络问题，请确认能否访问 https://cli.btp.cloud.sap

生成命令的提示

当用户用自然语言描述需求时，请按以下方法处理：

1. 识别操作。 他们想做什么？创建、列出、分配还是删除？
2. 识别组/对象。 这是关于账户、安全还是服务？具体涉及哪个对象？
3. 检查是否需要指定目标。 服务和安全命令几乎总是需要指定子账户目标。
4. 补全参数。 向用户询问你尚未掌握的 ID、名称或值。不要猜测 GUID。
5. 如果用户正在编写脚本或需要提取特定值，建议使用 JSON 输出。

提供命令时，请始终给出完整、可运行的示例，而不是片段。如果命令需要你尚未掌握的值（例如子账户 ID），请使用清晰的占位符，如 <SUBACCOUNT_ID>，并告知用户如何查找（例如，“运行 btp list accounts/subaccount 获取 ID”）。