SAP Cloud SDK for JavaScript 示例集

项目

内容

官方仓库

SAP-samples/cloud-sdk-js

业务场景

用 Cloud SDK 调用 S/4HANA 的 OData 服务、打通目标与认证

技术栈

SAP Cloud SDK for JavaScript、OData V2/V4、Destination、XSUAA、CAP

对应课程

CLD200、BAS400、C4H45B

对应路径

第 2 条、第 12 条

为什么值得做:并行扩展绕不开「从 BTP 调 S/4HANA 的 API」。 Cloud SDK 把连接、认证、重试、分页这些脏活封装好了,是官方推荐做法。

动手要点:

  • 对照课程里的通信安排 + 通信场景,理解 SDK 背后用的就是这套机制。

  • 试着把一次 OData 调用的目标(Destination)从硬编码改成从环境读取——这是安全实践。

本页内容抓取自官方仓库 SAP-samples/cloud-sdk-js,共收录 10 篇官方文档(README 与 docs)。原仓库内容版权归 SAP SE,遵循其许可证。

SAP Cloud SDK 示例集

说明

本仓库包含一批代码示例,用于演示 SAP Cloud SDK for JavaScript / TypeScript。 我们计划随着时间推移增加示例的数量。 这些示例的用途各不相同:

  • 会有简单的「Hello World」应用。它们包含一个完整项目,以及运行所需的全部配置。

  • 会有用于既有项目的代码示例。这些示例不能独立运行,但演示了如何使用 SAP Cloud SDK。

  • 会有教程或培训课程的解决方案。这类应用范围更大,展示用 SAP Cloud SDK 可以创造的业务价值。

环境要求

最低要求如下:

  • 一个用于执行命令的终端

  • 已安装较新版本的 node 与 npm,例如 node 14 与 npm 6

  • 一款自选的 IDE 或文本编辑器

如果想在本地测试之外继续探索,还需要:

  • 一个 SAP Business Technology Platform 账户的访问权限

  • 具备使用服务实例创建、应用处理单元(application processing unit)等资源的权利(entitlement)

  • 部署应用和创建服务实例的权限

支持

如果发现缺陷,或对本仓库的具体内容有疑问,请在此创建议题。 如果对 SAP Cloud SDK 的某项功能有一般性问题,请在 SAP Cloud SDK 仓库中创建议题。

贡献

如果希望贡献代码、提供修复或改进,请提交 pull request。 出于法律原因,贡献者在向本项目提交第一个 pull request 时会被要求接受 DCO。 这一过程在提交环节自动完成。SAP 采用 Linux 基金会的标准 DCO 文本。

行为准则

本仓库适用 SDK 的行为准则。

许可证

版权所有 (c) 2021 SAP SE 或其关联公司。保留所有权利。除 LICENSE 文件中另有说明外,本项目采用 Apache Software License 2.0 版许可。

CAP + SAP Cloud SDK for JS 的 Cloud Foundry 端到端应用

说明

本仓库包含一个基于 CAP 的应用,我们用它测试 SAP Cloud SDK 在 SAP BTP Cloud Foundry 环境中的功能。

仓库结构如下:

  • /src - 包含应用源代码,以及 CAP 服务处理程序(service handler)的实现

  • /srv - 包含 CDS 服务定义与实现

  • /db - 包含 CDS 领域模型及与数据库相关的内容

  • manifest.yml - 用于部署到 SAP BTP Cloud Foundry 的 manifest

环境要求

最低要求如下:

  • 一个用于执行命令的终端

  • 已安装较新版本的 node 与 npm,例如 node 14 与 npm 6

  • 一款自选的 IDE 或文本编辑器

如果想在本地测试之外继续探索,还需要:

  • 一个 SAP Business Technology Platform 账户的访问权限

  • 具备使用服务实例创建、应用处理单元(application processing unit)等资源的权利(entitlement)

  • 部署应用和创建服务实例的权限

下载与安装

要下载该应用,请运行:

git clone \
  --depth 1  \
  --filter=blob:none  \
  --sparse \
  https://github.com/SAP-samples/cloud-sdk-js.git \
;
cd cloud-sdk-js
git sparse-checkout set samples/cds-sample-application

生成 OData 客户端

Business Partner service cloud 的服务定义已按 EDMX 格式下载到 resources/service-specs 文件夹。客户端通过 npm run generate-client 命令生成。执行 npm i 后,该命令会在 postinstall 步骤中自动运行。

注意 该服务按 SAP API Information License 的条款授权,仅限用于开发目的。

在 SAP BTP Cloud Foundry 上创建服务

在部署应用之前,必须先创建 destination 和 xsuaa 服务实例。 其名称应与 manifest.yml 中使用的名称一致,此处为:

  • destination-service

  • xsuaa-service

将应用部署到 SAP BTP Cloud Foundry

在根目录运行 npm run deploy,即可将应用部署到 SAP BTP Cloud Foundry。该命令会用 ci-build 脚本把应用从 TypeScript 转译为 JavaScript,用 ci-package 脚本打包部署产物,再用 cf push 部署应用。

要在本地运行该应用,请先运行 npm run cds-deploy,再运行 npm run start:dev。

SAP Cloud SDK for JavaScript 多租户示例应用

说明

本目录中的代码示例是多租户应用教程的参考实现。 部署前需要对代码做相应调整。 需要替换的项均以全大写给出,并以 YOUR_ 开头,例如 YOUR_REGION。

另外请注意,这里的示例仅用于教学演示,未必是推荐的最佳实践。 仓库结构如下:

  • ./multi-tenant-app - 包含多租户应用的代码。 其中包含一个简单的服务端点,以及订阅和取消订阅时执行的逻辑。

  • ./approuter - 包含为应用附加 JSON Web Token 所需的 approuter。

  • ./service-config - 服务实例的目录配置。

环境要求

最低要求如下:

  • 一个用于执行命令的终端

  • 已安装较新版本的 node 与 npm,例如 node 14 与 npm 6

  • 已安装较新版本的 Cloud Foundry 命令行接口

  • 一款自选的 IDE 或文本编辑器

  • 一个 SAP Business Technology Platform 账户的访问权限

  • 具备使用服务实例创建、应用处理单元(application processing unit)等资源的权利(entitlement)

  • 部署应用和创建服务实例的权限

下载与部署

要下载该应用,请运行:

git clone \
  --depth 1  \
  --filter=blob:none  \
  --sparse \
  https://github.com/SAP-samples/cloud-sdk-js.git \
;
cd cloud-sdk-js
git sparse-checkout set samples/cf-multi-tenant-application

在 SAP BTP Cloud Foundry 上创建服务

在部署应用之前,必须先创建 destination 和 xsuaa 服务实例。 其名称应与应用 manifest.yml 中使用的名称一致,此处为:

  • destination

  • xsuaa

将应用部署到 SAP BTP Cloud Foundry

在应用目录中运行 cf push 即可部署应用。 所有组件的部署步骤请参照多租户应用教程中的说明执行。

SAP Cloud SDK for JS 的 Cloud Foundry 示例应用

说明

本仓库包含我们的 Cloud Foundry 示例应用。

仓库结构如下:

  • /approuter - 包含 approuter、打包脚本,以及部署时使用的 manifest

  • /src - 包含应用源代码,其中有面向云、本地(on-premise)与主体传播(principal propagation)的 4 个端点

  • /e2e-tests - 包含部署后测试全部端点的 cypress 测试

  • manifest.yml - 用于部署到 SAP BTP Cloud Foundry 的 manifest

如果要在本地触发 e2e 测试,请在 /e2e-tests 目录中创建 cypress.env.json 文件,按如下格式写入 IdP 的凭据:

{
  "username": "username",
  "password": "password"
  "url": "url"
}

环境要求

最低要求如下:

  • 一个用于执行命令的终端

  • 已安装较新版本的 node 与 npm,例如 node 14 与 npm 6

  • 一款自选的 IDE 或文本编辑器

如果想在本地测试之外继续探索,还需要:

  • 一个 SAP Business Technology Platform 账户的访问权限

  • 具备使用服务实例创建、应用处理单元(application processing unit)等资源的权利(entitlement)

  • 部署应用和创建服务实例的权限

下载与安装

要下载该应用,请运行:

git clone \
  --depth 1  \
  --filter=blob:none  \
  --sparse \
  https://github.com/SAP-samples/cloud-sdk-js.git \
;
cd cloud-sdk-js
git sparse-checkout set samples/cf-sample-application

生成 OData 客户端

以下 EDMX 格式的服务定义已下载到 resources/service-specs 文件夹:

这些客户端通过 npm run generate-client 命令生成。执行 npm i 后,该命令会在 postinstall 步骤中自动运行。

注意 这些服务按 SAP API Information License 的条款授权,仅限用于开发目的。

在 SAP BTP Cloud Foundry 上创建服务

在部署应用和 approuter 之前,必须先创建 destination、xsuaa 和 connectivity 服务实例。 其名称应与 manifest.yml 中使用的名称一致,此处为:

- sample-destination-service
- sample-xsuaa-service
- sample-connectivity-service

将 approuter 与应用部署到 SAP BTP Cloud Foundry

  1. 将 <REPLACE-ME> 的所有出现位置改为实际取值,包括目标(destination)、你的子域名(Subdomain)等。

  2. 修改 approuter 目录中的 xs-app.json,使其使用与你的子账户关联的 IdP,或完全不使用 IdP。

  3. 在根目录以及 approuter 目录中分别运行 npm run deploy,将应用部署到 SAP BTP Cloud Foundry。

  4. approuter 和应用都部署完成后,打开 approuter 的 URL 访问已部署的应用。

代码占位符

如果运行结果不符合预期,请搜索 <REPLACE-ME>,因为所有需要调整的部分都含有该占位符。

SAP Cloud SDK for JS 的 Kubernetes 端到端应用

本目录的结构如下:

  • ./application 包含我们的 Helm 示例应用

  • ./helm-chart 包含我们用来部署该应用的 Helm chart

  • ./sap-btp-operator 包含 SAP BTP Operator 的 Helm chart,以及自签名 issuer、与本应用相关的全部服务,还有供该 helm chart 使用的简单 values.yaml

下载与安装

要下载该应用,请运行:

git clone \
  --depth 1  \
  --filter=blob:none  \
  --sparse \
  https://github.com/SAP-samples/cloud-sdk-js.git \
;
cd cloud-sdk-js
git sparse-checkout set samples/helm-sample-application

要部署该应用,请遵循应用目录中的说明。

SAP Cloud SDK for JS 的 Kubernetes 端到端应用

本仓库包含我们的端到端应用,我们用它测试 SDK 在 Kubernetes 环境中的功能。 该应用与我们位于此处的 Helm chart 一起部署。

仓库结构如下:

  • /approuter - 包含 approuter、打包脚本,以及部署时使用的 Dockerfile

  • /pipeline - 包含流水线所用的 Dockerfile,其中含有运行流水线所需的全部工具

  • /src - 包含应用源代码,其中有面向云、本地(on-premise)与主体传播(principal propagation)的 4 个端点

  • /e2e-tests - 包含部署后测试全部端点的 cypress 测试

  • ./github/workflows - 包含构建、打包、部署并测试该应用的流水线

  • Dockerfile - 将应用打包为 Docker 镜像,以便在 Kubernetes 中使用

如果要在本地触发 e2e 测试,请在 /e2e-tests 目录中创建 cypress.env.json 文件,按如下格式写入 IdP 的凭据:

{
  "username": "username",
  "password": "password"
  "url": "url"
}

环境要求

最低要求如下:

  • 一个用于执行命令的终端

  • 已安装较新版本的 node 与 npm,例如 node 14 与 npm 6

  • 一款自选的 IDE 或文本编辑器

如果想在本地测试之外继续探索,还需要:

  • 一个 SAP Business Technology Platform 账户的访问权限

  • 具备使用服务实例创建、应用处理单元(application processing unit)等资源的权利(entitlement)

  • 创建服务实例的权限

  • 一个 Docker 仓库的访问权限

  • 一个运行以下组件的 Kubernetes 集群:

    • SAP BTP Operator

    • SAP Connectivity Proxy

下载与安装

要下载该应用,请运行:

git clone \
  --depth 1  \
  --filter=blob:none  \
  --sparse \
  https://github.com/SAP-samples/cloud-sdk-js.git \
;
cd cloud-sdk-js
git sparse-checkout set samples/helm-sample-application

生成 OData 客户端

以下 EDMX 格式的服务定义已下载到 resources/service-specs 文件夹:

这些客户端通过 npm run generate-client 命令生成。执行 npm i 后,该命令会在 postinstall 步骤中自动运行。

注意 这些服务按 SAP API Information License 的条款授权,仅限用于开发目的。

部署到 Docker

  1. 在 package.json 中,将 deploy:docker 和 deploy:pipeline 脚本改为指向你的 Docker 仓库。

  2. 将 approuter 的 package.json 中的 deploy:docker 脚本改为指向你的 Docker 仓库。

  3. 如需使用流水线,用 npm run deploy:docker 和 npm run deploy:pipeline 将 Docker 镜像部署到你的仓库。

部署到 Kubernetes

要把该应用部署到 Kubernetes,首先需要部署该应用要用到的所有服务,包括:

  • connectivity 服务

  • xsuaa 服务

  • destination 服务

部署这些服务,只需对 sap-btp-operator/services 下的 yaml 文件执行 kubectl apply -f。

服务部署完成后,你只需编辑 helm-chart 下的 values.yaml 文件。 该 helm chart 的 README 会说明你可以使用哪些取值、哪些取值必须修改。

改好 values.yaml 后,运行 helm install e2e-app k8s-e2e-app-helm-0.1.5.tgz --values values.yaml,即可开始使用。

有关 Kubernetes 部署的更多详细信息,请参阅我们的 Kubernetes 迁移指南。

下图展示了该应用的架构,以及它依赖的组件、connectivity proxy,还有由 sap-btp-operator 创建的服务:

SAP Cloud SDK for JS 团队 Helm 示例应用的 Helm chart

本仓库包含我们的 Helm 示例应用所用的 Helm chart。 它用于我们的 Kubernetes 集群仓库。

该应用在设计上可在任何环境中部署——Gardener、原生 GCP,甚至 Kyma——唯一需要调整的文件是 values.yaml。

要将其部署到你的集群,请使用默认的 values.yaml,按你的取值修改 values 模板,然后运行:

helm install e2e-app k8s-e2e-app-helm-<release>.tgz --values `/path/to/values.yaml`

要覆盖 chart 中的取值(例如指定特定环境),可使用 --set 标志从命令行传入配置:

helm install e2e-app k8s-e2e-app-helm-<release>.tgz --values `/path/to/values.yaml` --set expose.environment=kyma --set approuter-chart.config.pattern="<YOUR_HOST_NAME>.<YOUR-CLUSTER-DOMAIN>"

该应用的几乎每个方面都可配置,因此可设置的标志列表非常长;最小配置请参考默认的 values.yaml。

下表列出了你可以使用的标志,以及它们是必需、可选,还是「可选依赖」——即只有在使用了某个特定的可选标志时才必需。

名称

必需

可选

可选依赖

默认值

说明

approuter-chart.name

x

approuter-chart

chart 及其所有 CRD 的名称

approuter-chart.imagePullSecrets.name

x

拉取 approuter 镜像所用 secret 的名称

approuter-chart.image.repository

x

docker-cloudsdk.common.repositories.cloud.sap/k8s-approuter

使用的镜像名称

approuter-chart.image.tag

x

latest

镜像的标签

approuter-chart.config.json

x

应用在 /backend-app/ 下提供服务

包含 approuter 的完整配置,可用 JSON 格式提供,不能与 config.idp 同时使用

approuter-chart.config.idp

x

使用的身份提供方(Identity Provider)名称;除非提供了完整的 config.json,否则必需

approuter-chart.config.pattern

x

多租户场景下 approuter 使用的 TENANT_HOST_PATTERN

approuter-chart.resources.requests.memory

x

x

256Mi

只要给出了任一资源参数,就必须全部给出

approuter-chart.resources.requests.cpu

x

x

500m

只要给出了任一资源参数,就必须全部给出

approuter-chart.resources.limits.memory

x

x

512Mi

只要给出了任一资源参数,就必须全部给出

approuter-chart.resources.limits.cpu

x

x

1000m

只要给出了任一资源参数,就必须全部给出

approuter-chart.serviceAccount.name

x

default

部署使用的服务账户(service account)

approuter-chart.xsuaaBinding

x

包含 xsuaa 服务绑定的 secret 名称

app-chart.name

x

app-chart

chart 及其所有 CRD 的名称

app-chart.imagePullSecrets.name

x

拉取 app 镜像所用 secret 的名称

app-chart.image.repository

x

docker-cloudsdk.common.repositories.cloud.sap/k8s-e2e-app

使用的镜像名称

app-chart.image.tag

x

latest

镜像的标签

app-chart.resources.requests.memory

x

x

256Mi

只要给出了任一资源参数,就必须全部给出

app-chart.resources.requests.cpu

x

x

500m

只要给出了任一资源参数,就必须全部给出

app-chart.resources.limits.memory

x

x

512Mi

只要给出了任一资源参数,就必须全部给出

app-chart.resources.limits.cpu

x

x

1000m

只要给出了任一资源参数,就必须全部给出

app-chart.serviceAccount.name

x

default

部署使用的服务账户(service account)

app-chart.xsuaaBinding

x

包含 xsuaa 服务绑定的 secret 名称

app-chart.connectivityBinding

x

包含 connectivity 服务绑定的 secret 名称

app-chart.destinationBinding

x

包含 destination 服务绑定的 secret 名称

app-chart.cloudDestination

x

云目标(cloud destination)的名称

app-chart.onPremiseDestination

x

本地目标(On-Premise destination)的名称

app-chart.principalPropagationDestination

x

主体传播目标(principal propagation destination)的名称

global.serviceAccountName

x

default

chart 所有 CRD 使用的 ServiceAccount

expose.enabled

x

是否启用 ingress/api-rule(true/false)

expose.name

x

k8s-e2e-app-helm

chart 的 CRD 名称

expose.environment

x

环境类型,取值为 gardener、kyma 或 generic;若使用 generic,则必须指定 expose.ingress.issuer 相关取值

expose.ingress.shortRoute

x

x

如果对外暴露的路由超过 64 个字符,就必须指定一条更短的路由,因为 letsencrypt 需要一条少于 64 个字符的路由才能工作;可用的最短路由就是你的 DNS,但前提是该路由可以对外暴露,若部署到 Gardener,不把环境指定为 gardener 就无法做到这一点

expose.ingress.exposedRoute

x

指向 approuter 的路由

expose.ingress.connectivityProxyRoute

x

x

如果 connectivity proxy 还没有有效的 TLS,就必须在此配置

expose.ingress.secretName

x

tls-secret

存放所有证书的 secret 名称

expose.ingress.issuer.name

x

x

letsencrypt-production

使用的 issuer 名称;如果不指定名称,将创建一个 letsencrypt issuer

expose.ingress.issuer.email

x

x

用于注册 letsencrypt 的邮箱;仅当未提供 ingress.issuer.name 时需要

expose.ingress.issuer.privateKeySecretRef

x

tls-private-key

存放你的私钥的 secret 名称

expose.api-rule.host

x

x

e2e-app-<YOUR_SUBDOMAIN>

API Gateway 的主机名。若 expose.environment 设为 kyma 则必需

HTTP 客户端示例

以下示例演示如何在 SAP Cloud SDK for JavaScript 中使用 HTTP Client。

HTTP Client 的说明请参阅文档。

这些示例实现在 http-client.spec.ts 和 http-client-httpbin.spec.ts 中。 这些示例的目的是为文档中提到的示例提供可直接使用的示例代码。

本地运行说明

安装依赖

npm ci

运行测试

这些示例以测试的形式编写,演示如何使用 HTTP Client。

要运行测试,请执行以下命令:

npm run test

这会启动一个基于 express 的本地 HTTP 服务器,并使用 HTTP Client 发起若干示例请求。

SAP Cloud SDK for JS 的 Kubernetes 示例应用

说明

本仓库包含我们的 Kubernetes 示例应用。

仓库结构如下:

  • /approuter - 包含 approuter、打包脚本,以及部署时使用的 Dockerfile

  • /pipeline - 包含流水线所用的 Dockerfile,其中含有运行流水线所需的全部工具

  • /src - 包含应用源代码,其中有面向云、本地(on-premise)与主体传播(principal propagation)的 4 个端点

  • /e2e-tests - 包含部署后测试全部端点的 cypress 测试

  • ./github/workflows - 包含构建、打包、部署并测试该应用的流水线

  • Dockerfile - 将应用打包为 Docker 镜像,以便在 Kubernetes 中使用

如果要在本地触发 e2e 测试,请在 /e2e-tests 目录中创建 cypress.env.json 文件,按如下格式写入 IdP 的凭据:

{
  "username": "username",
  "password": "password"
  "url": "url"
}

环境要求

最低要求如下:

  • 一个用于执行命令的终端

  • 已安装较新版本的 node 与 npm,例如 node 14 与 npm 6

  • 一款自选的 IDE 或文本编辑器

如果想在本地测试之外继续探索,还需要:

  • 一个 SAP Business Technology Platform 账户的访问权限

  • 具备使用服务实例创建、应用处理单元(application processing unit)等资源的权利(entitlement)

  • 创建服务实例的权限

  • 一个 Docker 仓库的访问权限

  • 一个运行以下组件的 Kubernetes 集群:

    • SAP BTP Operator

    • SAP Connectivity Proxy

下载与安装

要下载该应用,请运行:

git clone \
  --depth 1  \
  --filter=blob:none  \
  --sparse \
  https://github.com/SAP-samples/cloud-sdk-js.git \
;
cd cloud-sdk-js
git sparse-checkout set samples/k8s-sample-application

生成 OData 客户端

以下 EDMX 格式的服务定义已下载到 resources/service-specs 文件夹:

这些客户端通过 npm run generate-client 命令生成。执行 npm i 后,该命令会在 postinstall 步骤中自动运行。

注意 这些服务按 SAP API Information License 的条款授权,仅限用于开发目的。

部署到 Docker

  1. 在 package.json 中,将 deploy:docker 和 deploy:pipeline 脚本改为指向你的 Docker 仓库。

  2. 将 approuter 的 package.json 中的 deploy:docker 脚本改为指向你的 Docker 仓库。

  3. 修改 approuter 目录中的 xs-app.json,改用你选择的 IdP,或完全不使用 IdP。

  4. 如需使用流水线,用 npm run deploy:docker 和 npm run deploy:pipeline 将 Docker 镜像部署到你的仓库。

部署到 Kubernetes

  1. 更新 deployment.yml,改用你的 Docker 镜像;更新 ingress.yml,改用与你的集群关联的域名。

  2. 在 approuter 的 deployment.yml 中,把 TENANT_HOST_PATTERN 设为与你在 ingress.yml 中指定的同一域名。

  3. 部署 k8s_files/operator/services 中的服务。

  4. 现在可以用 kubectl apply -f 部署 k8s_files/app、k8s_files/approuter 中的 Kubernetes 文件以及 ingress.yml,从而部署应用和 approuter。

代码占位符

如果运行结果不符合预期,请搜索 <REPLACE-ME>,因为所有需要调整的部分都含有该占位符。

有关 Kubernetes 部署的更多详细信息,请参阅我们的 Kubernetes 迁移指南。

SAP Cloud SDK for JS 的韧性(resilience)示例

说明

本文件夹包含若干关于韧性与 SDK 的简单示例。 它展示了默认韧性中间件的用法,也展示了如何构建并使用自定义的中间件。

resilience.ts 中有韧性中间件的自定义实现示例。 其用法见 resilience.spec.ts 文件。

生成 OData 客户端

Business Partner service cloud 的服务定义已按 EDMX 格式下载到 resources/service-specs 文件夹。客户端通过 npm run generate-client 命令生成。执行 npm i 后,该命令会在 postinstall 步骤中自动运行。

注意 该服务按 SAP API Information License 的条款授权,仅限用于开发目的。