<< English version is here >>
本ブログは、How to extend SAP S/4HANA on SAP Cloud Platformのブログシリーズの第3回目となるSAP Cloud PlatformからのSAP S/4HANAのAPIの使い方編になります。
前回のブログでは、SAP S/4HANAのAPIの探し方として、SAP API Business HubでのODataやSOAP APIの検索、BAPI ExplorerでのBAPIの検索方法について解説してきました。今回はこれらのAPIを使うにあたり、どのようなツールや方法があるのかに注目し、特にSAP Cloud SDKについて解説していきます。
また、2020年5月1日に更新されたSAP S/4HANA Cloud EX (旧STE)の拡張ガイドライン (SAP Note 2920697) の通り、SAP API Business Hubにて公開されているAPIやイベントを利用した拡張方法が優先度の高いものとなっています。
SAP S/4HANAの拡張開発をする上で、APIを利用する開発パターンは主に下記があります。
上記パターンにおいて、各APIに対する対応は下表の通りです。
上記3つのパターンは同列の選択肢というわけではなく、それぞれ開発レイヤーの異なるものですので、あくまで開発要件、開発技術を選定した上での使い分けとなります。中でも、SAP Cloud SDKはサーバーサイドアプリケーションの開発において、非常に効率良くSAP S/4HANAのAPIを呼び出すことができるツールです。次章では、このSAP Cloud SDKについて具体的にご紹介いたします。
SAP Cloud SDKは、SAP S/4HANAやSAP SuccessFactors等の拡張開発をより効率的にさせる、Java・JavaScript(Typescript)向けのライブラリと、CI/CDのJenkinsパイプラインテンプレートで構成されます。
ライブラリはJavaやNode.jsの任意のプロジェクトで利用することもできまし、JavaであればSpring Boot、JavaScriptであればNode.jsのExpressやNest.jsなどのフレームワークと組み合わせて利用することができます。そのため、開発者は使い慣れた開発言語・フレームワークを選択した上で、SAPソリューションとの連携部分にSAP Cloud SDKライブラリを適用することが可能です。もちろんSAP Cloud Platform独自の開発フレームワークのSAP Cloud Application Programming Model (CAP)とも連携可能です。
また、SAP Cloud SDKはODataのラッパーライブラリですので、開発者は実際のODataを意識せずにアプリケーションを効率的に開発ができます。(SAP Cloud SDKの内部でOData APIを呼び出しています)
SAP Cloud SDKの具体的な使い方は、SAP Tutorial Navigatorにて多くの情報がステップバイステップで紹介されています。本章では、学習する上で基本となる情報や、わかりやすい利点を中心に、Business Partner APIを例に触れていきます。
SAP Cloud SDKの中心とも言えるのが、VDMという仮想データモデルです。この名称だけではイメージがし辛いかと思いますが、VDMはSAP S/4HANAのODataのメタデータ(APIの設計書)がクラス化されたものです。例えば、Business PartnerのODataのメタデータは下記になります。(一部を抜粋)
上記は一部の項目ですが、このAPIを呼び出すアプリケーション側で、これらの項目を定義していくかと思うと気が遠くなりますよね。これに対してSAP Cloud SDKでは、Business Partner APIを構成している項目(プロパティやデータ型)を下記のようにクラスとして提供をしています。(下記はSAP Cloud SDK for JavaScriptのAPIドキュメント)
つまり、VDMが提供されるおかげで、ソースコード内ではBusiness Partner APIを利用するために必要な膨大な項目(プロパティやデータ型)を、独自に定義することなく扱うことができます。また、コーディングの際には利用可能なメソッド・プロパティがコード補完されるため、記述ミスを減らし開発効率の向上に貢献します。もしもSAP Cloud SDKを利用しない場合、上記Business Partner APIの中から必要な項目を自身で定義することになりますのでこの違いは大きいかと思います。下記はSAP Cloud SDK for JavaScriptを利用したVS Codeでのコーディングの例になります。
少しずつVDMのイメージは沸いてきましたでしょうか。上記のBusiness Partnerや他の豊富なOData APIと対応するVDMが、Javascript版であればNode.jsのパッケージとして用意されていますので、それをインポートするだけで簡単に使えるようになるわけです。
SAP Cloud SDKを利用することで、API呼び出し時の認証・認可も簡単に実装することができます。
そして、SAP Cloud SDKを使うことで、このDestinationサービスと連携することができるため、ソースコード内では下記のようにDestinationの名称を指定するだけで(destinationName)、認証に関するコーディングは完了です。どのような認証タイプであっても、Destinationサービスで設定したものをソースコード側では指定するだけという非常に便利な機能になります。
※ 上記は、Business Partner APIを使い、項目を絞らず全件データを取得するシンプルな例です
SAP S/4HANAのAPIを呼び出すためのCRUD (Create/Read/Update/Delete) 処理もシンプルです。インポートしたSAP Cloud SDKのクラス(今回の例ではBusinessPartnerやBusinessPartnerAddress)から、requestBuilderメソッドを使うのが基本の形です。(BusinessPartnerクラスにはDelete処理はないため、BusinessPartnerAddressクラスを使用します)
また、SAP Cloud SDKの各VDMモジュールからどのクラスを利用するかは、ODataを使いなれている方であれば、元となるODataのエンティティをSAP API Business Hubで確認しておくとスムーズかと思います。(ODataのエンティティ名とSAP Cloud SDKのクラス名はほぼ同じです)
以降では、Tutorial Navigatorの "Build an Address Manager with the SAP Cloud SDK's OData Virtual Data Model" を参考にCRUD処理のポイントを解説していきます。(ソースコードは概要を理解し易いように簡素化しています)
照会処理では、getAllメソッドを使います。さらに、ODataの特徴であるSQLクエリのような下記のメソッドも組み合わせて利用が可能です。(詳細はこちらのAPIガイド)
これらを"."(ドット)で繋ぐメソッドチェーンの形式で記述するのがお作法になります。
登録処理は、createメソッドを使います。このcreateメソッドに登録対象のデータをパラメーターとして渡す形になります。このパラメーターは、インポートしたBusinessPartnerクラスのbuilderメソッドを使ってインスタンス化しておきます。
他のUpdateやDelete処理でも同様ですが、通常ODataを使ってデータを更新する際には、処理の順序として先にCSRFトークンを取得し、そのトークンをHTTPヘッダーに付与した上で更新処理を行う必要があります。(CSRFへのセキュリティ対策) 一方で、SAP Cloud SDKはこのような処理も自動的に行ってくれるため実装の手間が削減されます。
更新処理は、updateメソッドを使いますが、使い方は登録処理とほとんど同じです。ODataでは、データ取得時と更新時とで差異があった場合、古いデータで更新されないようにバージョン識別子(ETag)を持っており、バージョンが一致しない場合には処理要求は拒否されます。このバージョン識別子の処理はVDMが自動的に行ってくれますが、ignoreVersionIdentifierメソッドを追加することで、バージョン比較を無視し強制的に処理させることもできます。
削除処理は、deleteメソッドを使います。パラメーターには、対象エントリーのIDを渡します。下記例のBusinessPartnerAddressのDeleteメソッドでは、ビジネスパートナーIDとアドレスIDを指定する必要があります。
上記では、基本的なCRUD処理について触れましたが、ODataでは複数のCRUD処理を1つのPOST処理で実行するBatchリクエストが使えます。SAP Cloud SDKでは、このBatchリクエストにも対応しています。また、上記内容はSAP Cloud SDK for JavaScriptについてのコード例でしたが、Java版でも同様のことが可能です。さらにJava版ではSAP Cloud SDK自体のリリースが先行していることもあり、JavaScript版にない機能も多くあります。例えば、ODataではなくBAPIを呼ぶことのできるBAPIRequestというクラス(Ver2.xではBAPIQuery)も提供されています。
SAP Cloud SDK for JavaScriptには、開発プロジェクトを開始する際に便利な機能を提供するSAP Cloud SDK ClientというNode.jsパッケージもあります。下記のようにパッケージをインストール後、プロジェクトを生成することで、基本的なプロジェクトディレクトリーの生成や、SAP Cloud SDKを利用するのに必要な依存関係も追加してくれます。また、Cloud Foundryアプリケーションへの認証機能を提供するApp Routerの生成も可能です。
空のディレクトリで上記の初期化コマンドを実行した場合は、Nest.jsベースで初期化するかの確認がありますが、Nest.jsベースで行うことをお奨めします。Nest.jsは...
上記の他にも様々な特徴がありますが、SAPが公開しているSAP Cloud SDKの学習コンテンツもNest.jsベースのプロジェクトでガイドがされていますので、合わせてキャッチアップ頂ければと思います。
また、SAP Cloud SDK for Javaの場合には、MavenのArchetypeを指定することで、SAP Cloud SDKを組み込んだSpringやTomEEなどのプロジェクトテンプレートを生成することができます。
すべての情報の入り口。概要情報や始め方、リリースノート、APIガイドなどの情報へつながります。
SAP Cloud SDKに関するステップバイステップのチュートリアルコンテンツやSAP Blog情報を豊富に提供しています。
本ブログの3.3章 CRUD処理にて参考としているチュートリアルです。SAP S/4HANAのODataを利用したSAP Cloud SDK開発を基礎から網羅的に紹介していますのでお奨めです。
以上SAP Cloud PlatformでのSAP S/4HANA拡張のAPI利用編になりますが、いかがでしたでしょうか。冒頭でも触れました通り、APIの利用方法はSAP Cloud SDKだけでなくCloud Platform Integrationなどシナリオに応じて選択肢がありますので、今後ご紹介できればと思います。
次回は、SAP Enterprise Messagingを利用したイベント連携編になりますので、どうぞご期待ください。
1. はじめに
本ブログは、How to extend SAP S/4HANA on SAP Cloud Platformのブログシリーズの第3回目となるSAP Cloud PlatformからのSAP S/4HANAのAPIの使い方編になります。
- SAP Cloud Platformでの拡張開発概要
- SAP S/4HANAのAPIの探し方
- SAP S/4HANAのAPIの使い方 << Here
- APIが存在しない場合の対応
- SAP S/4HANAとのイベント連携
前回のブログでは、SAP S/4HANAのAPIの探し方として、SAP API Business HubでのODataやSOAP APIの検索、BAPI ExplorerでのBAPIの検索方法について解説してきました。今回はこれらのAPIを使うにあたり、どのようなツールや方法があるのかに注目し、特にSAP Cloud SDKについて解説していきます。
また、2020年5月1日に更新されたSAP S/4HANA Cloud EX (旧STE)の拡張ガイドライン (SAP Note 2920697) の通り、SAP API Business Hubにて公開されているAPIやイベントを利用した拡張方法が優先度の高いものとなっています。
2. アプリケーションからの主なAPI利用パターン
SAP S/4HANAの拡張開発をする上で、APIを利用する開発パターンは主に下記があります。
上記パターンにおいて、各APIに対する対応は下表の通りです。
| SAP Cloud SDK | Cloud Platform Integration | SAPUI5 | |
| OData | ○ (VDM) | ○ (ODataアダプタ) | ○ (ODataモデル) |
| SOAP | ○ (VDM) | ○ (SOAPアダプタ) | ○ (XMLモデル) |
| BAPI | ○ (VDM, Javaのみ) | ○ (RFCアダプタ) | × |
| IDoc | × | ○ (IDocアダプタ) | × |
上記3つのパターンは同列の選択肢というわけではなく、それぞれ開発レイヤーの異なるものですので、あくまで開発要件、開発技術を選定した上での使い分けとなります。中でも、SAP Cloud SDKはサーバーサイドアプリケーションの開発において、非常に効率良くSAP S/4HANAのAPIを呼び出すことができるツールです。次章では、このSAP Cloud SDKについて具体的にご紹介いたします。
3. SAP Cloud SDK
SAP Cloud SDKは、SAP S/4HANAやSAP SuccessFactors等の拡張開発をより効率的にさせる、Java・JavaScript(Typescript)向けのライブラリと、CI/CDのJenkinsパイプラインテンプレートで構成されます。
ライブラリはJavaやNode.jsの任意のプロジェクトで利用することもできまし、JavaであればSpring Boot、JavaScriptであればNode.jsのExpressやNest.jsなどのフレームワークと組み合わせて利用することができます。そのため、開発者は使い慣れた開発言語・フレームワークを選択した上で、SAPソリューションとの連携部分にSAP Cloud SDKライブラリを適用することが可能です。もちろんSAP Cloud Platform独自の開発フレームワークのSAP Cloud Application Programming Model (CAP)とも連携可能です。
また、SAP Cloud SDKはODataのラッパーライブラリですので、開発者は実際のODataを意識せずにアプリケーションを効率的に開発ができます。(SAP Cloud SDKの内部でOData APIを呼び出しています)
SAP Cloud SDKの具体的な使い方は、SAP Tutorial Navigatorにて多くの情報がステップバイステップで紹介されています。本章では、学習する上で基本となる情報や、わかりやすい利点を中心に、Business Partner APIを例に触れていきます。
3.1 VDM (Virtual Data Model)
SAP Cloud SDKの中心とも言えるのが、VDMという仮想データモデルです。この名称だけではイメージがし辛いかと思いますが、VDMはSAP S/4HANAのODataのメタデータ(APIの設計書)がクラス化されたものです。例えば、Business PartnerのODataのメタデータは下記になります。(一部を抜粋)
上記は一部の項目ですが、このAPIを呼び出すアプリケーション側で、これらの項目を定義していくかと思うと気が遠くなりますよね。これに対してSAP Cloud SDKでは、Business Partner APIを構成している項目(プロパティやデータ型)を下記のようにクラスとして提供をしています。(下記はSAP Cloud SDK for JavaScriptのAPIドキュメント)
つまり、VDMが提供されるおかげで、ソースコード内ではBusiness Partner APIを利用するために必要な膨大な項目(プロパティやデータ型)を、独自に定義することなく扱うことができます。また、コーディングの際には利用可能なメソッド・プロパティがコード補完されるため、記述ミスを減らし開発効率の向上に貢献します。もしもSAP Cloud SDKを利用しない場合、上記Business Partner APIの中から必要な項目を自身で定義することになりますのでこの違いは大きいかと思います。下記はSAP Cloud SDK for JavaScriptを利用したVS Codeでのコーディングの例になります。
少しずつVDMのイメージは沸いてきましたでしょうか。上記のBusiness Partnerや他の豊富なOData APIと対応するVDMが、Javascript版であればNode.jsのパッケージとして用意されていますので、それをインポートするだけで簡単に使えるようになるわけです。
3.2 認証の抽象化
SAP Cloud SDKを利用することで、API呼び出し時の認証・認可も簡単に実装することができます。
そして、SAP Cloud SDKを使うことで、このDestinationサービスと連携することができるため、ソースコード内では下記のようにDestinationの名称を指定するだけで(destinationName)、認証に関するコーディングは完了です。どのような認証タイプであっても、Destinationサービスで設定したものをソースコード側では指定するだけという非常に便利な機能になります。
function getBusinessPartners(){
return BusinessPartner.requestBuilder()
.getAll()
.execute({
destinationName: 'S4HANA1909-Dev' // Destinationサービスで設定した名称
});
}※ 上記は、Business Partner APIを使い、項目を絞らず全件データを取得するシンプルな例です
3.3 CRUD処理
SAP S/4HANAのAPIを呼び出すためのCRUD (Create/Read/Update/Delete) 処理もシンプルです。インポートしたSAP Cloud SDKのクラス(今回の例ではBusinessPartnerやBusinessPartnerAddress)から、requestBuilderメソッドを使うのが基本の形です。(BusinessPartnerクラスにはDelete処理はないため、BusinessPartnerAddressクラスを使用します)
また、SAP Cloud SDKの各VDMモジュールからどのクラスを利用するかは、ODataを使いなれている方であれば、元となるODataのエンティティをSAP API Business Hubで確認しておくとスムーズかと思います。(ODataのエンティティ名とSAP Cloud SDKのクラス名はほぼ同じです)
以降では、Tutorial Navigatorの "Build an Address Manager with the SAP Cloud SDK's OData Virtual Data Model" を参考にCRUD処理のポイントを解説していきます。(ソースコードは概要を理解し易いように簡素化しています)
3.3.1 Read
照会処理では、getAllメソッドを使います。さらに、ODataの特徴であるSQLクエリのような下記のメソッドも組み合わせて利用が可能です。(詳細はこちらのAPIガイド)
- select: 取得したい項目を指定 (ODataの$selectに相当)
- top: 取得したい件数を指定 (ODataの$topに相当)
- filter: 取得条件を指定( SQLのWhere句やODataの$filterに相当)
- orderBy: ソート順を指定 (ODataの$orderbyに相当)
これらを"."(ドット)で繋ぐメソッドチェーンの形式で記述するのがお作法になります。
// SAP Cloud SDKの"Business Partner Service"VDMから、"BusinessPartner"クラスをインポート
import { BusinessPartner } from '@sap/cloud-sdk-vdm-business-partner-service';
BusinessPartner.requestBuilder()
.getAll() // 照会処理のメソッド
.top(10) // 最初の10件を取得
.select( // 指定した項目を取得
BusinessPartner.BUSINESS_PARTNER,
BusinessPartner.FIRST_NAME,
BusinessPartner.LAST_NAME
)
.filter( // 取得条件としてBPカテゴリを指定
BusinessPartner.BUSINESS_PARTNER_CATEGORY.equals('1')
)
.execute({ // 認証情報を指定。SAP CPのDestinationサービスの宛先名を指定。(URL,ID,Passの直接指定も可能)
destinationName: 'S/4HANA1909-Dev'
});
}3.3.2 Create
登録処理は、createメソッドを使います。このcreateメソッドに登録対象のデータをパラメーターとして渡す形になります。このパラメーターは、インポートしたBusinessPartnerクラスのbuilderメソッドを使ってインスタンス化しておきます。
import { BusinessPartner, BusinessPartnerAddress } from '@sap/cloud-sdk-vdm-business-partner-service';
// インポートしたBusinessPartnerクラスからbulderメソッドを使って、登録用データを生成
const businessPartner = BusinessPartner.builder()
.firstName('Susumu')
.lastName('Honna')
.businessPartnerCategory('1')
.toBusinessPartnerAddress([
BusinessPartnerAddress.builder() // 1回のAPIコールで関連エンティティのアドレス情報も登録する"Deep create"も可能。
.country('JP')
.postalCode('1020083')
.cityName('Chiyoda')
.streetName('Kojimachi')
.build()
])
.build();
// 照会処理と同じように、requestBuilderメソッドを使って登録処理を実行
BusinessPartner.requestBuilder()
.create(businessPartner) // createメソッドに事前に作成した登録用データをパラメーターとして渡す
.execute({
destinationName: 'S/4HANA1909-Dev'
});他のUpdateやDelete処理でも同様ですが、通常ODataを使ってデータを更新する際には、処理の順序として先にCSRFトークンを取得し、そのトークンをHTTPヘッダーに付与した上で更新処理を行う必要があります。(CSRFへのセキュリティ対策) 一方で、SAP Cloud SDKはこのような処理も自動的に行ってくれるため実装の手間が削減されます。
3.3.3 Update
更新処理は、updateメソッドを使いますが、使い方は登録処理とほとんど同じです。ODataでは、データ取得時と更新時とで差異があった場合、古いデータで更新されないようにバージョン識別子(ETag)を持っており、バージョンが一致しない場合には処理要求は拒否されます。このバージョン識別子の処理はVDMが自動的に行ってくれますが、ignoreVersionIdentifierメソッドを追加することで、バージョン比較を無視し強制的に処理させることもできます。
import { BusinessPartner } from '@sap/cloud-sdk-vdm-business-partner-service';
// インポートしたBusinessPartnerクラスからbulderメソッドを使って、更新用データを生成
const businessPartner = BusinessPartner.builder()
// 更新用データを定義(省略)
.build();
// 登録処理と同じように、requestBuilderメソッドを使って更新処理を実行
BusinessPartner.requestBuilder()
.update(businessPartner) // updateメソッドに事前に作成した更新用データをパラメーターとして渡す
.ignoreVersionIdentifier() // (任意) バックエンドのODataのバージョン識別子との比較をせず強制的に更新する場合
.execute({
destinationName: 'S/4HANA1909-Dev'
});
3.3.4 Delete
削除処理は、deleteメソッドを使います。パラメーターには、対象エントリーのIDを渡します。下記例のBusinessPartnerAddressのDeleteメソッドでは、ビジネスパートナーIDとアドレスIDを指定する必要があります。
import { BusinessPartnerAddress } from '@sap/cloud-sdk-vdm-business-partner-service';
// 削除対象のビジネスパートナーIDとアドレスIDを定義
const businessPartnerId = "1";
const addressId = "2";
// 更新処理と同じように、requestBuilderメソッドを使って削除処理を実行
BusinessPartnerAddress.requestBuilder()
.update(businessPartnerId, addressId) // deleteメソッドに削除対象データをパラメーターとして渡す
.execute({
destinationName: 'S/4HANA1909-Dev'
});
3.4 その他の便利機能
上記では、基本的なCRUD処理について触れましたが、ODataでは複数のCRUD処理を1つのPOST処理で実行するBatchリクエストが使えます。SAP Cloud SDKでは、このBatchリクエストにも対応しています。また、上記内容はSAP Cloud SDK for JavaScriptについてのコード例でしたが、Java版でも同様のことが可能です。さらにJava版ではSAP Cloud SDK自体のリリースが先行していることもあり、JavaScript版にない機能も多くあります。例えば、ODataではなくBAPIを呼ぶことのできるBAPIRequestというクラス(Ver2.xではBAPIQuery)も提供されています。
3.5 SAP Cloud SDK Client
SAP Cloud SDK for JavaScriptには、開発プロジェクトを開始する際に便利な機能を提供するSAP Cloud SDK ClientというNode.jsパッケージもあります。下記のようにパッケージをインストール後、プロジェクトを生成することで、基本的なプロジェクトディレクトリーの生成や、SAP Cloud SDKを利用するのに必要な依存関係も追加してくれます。また、Cloud Foundryアプリケーションへの認証機能を提供するApp Routerの生成も可能です。
$ npm install -g @sap-cloud-sdk/cli
$ sap-cloud-sdk init project-name空のディレクトリで上記の初期化コマンドを実行した場合は、Nest.jsベースで初期化するかの確認がありますが、Nest.jsベースで行うことをお奨めします。Nest.jsは...
- TypeScript製のNode.jsのフレームワーク(オープンソース)
- TypeScriptはJavaScriptにクラスベースのオブジェクト指向を加えたスーパーセットであるため、サーバーサイドのJavaScriptアプリケーション開発向き
- SAP Cloud SDKもTypeScriptで開発されている
- Node.jsで一般的なフレームワークであるExpressベースであるため、Expressの豊富な機能を利用することも可能
上記の他にも様々な特徴がありますが、SAPが公開しているSAP Cloud SDKの学習コンテンツもNest.jsベースのプロジェクトでガイドがされていますので、合わせてキャッチアップ頂ければと思います。
また、SAP Cloud SDK for Javaの場合には、MavenのArchetypeを指定することで、SAP Cloud SDKを組み込んだSpringやTomEEなどのプロジェクトテンプレートを生成することができます。
4. 追加情報
SAP Cloud SDK Official Page
すべての情報の入り口。概要情報や始め方、リリースノート、APIガイドなどの情報へつながります。
SAP Cloud SDK Official Tutorials, Community & Resources
SAP Cloud SDKに関するステップバイステップのチュートリアルコンテンツやSAP Blog情報を豊富に提供しています。
Build an Address Manager with the SAP Cloud SDK's OData Virtual Data Model (SAP Tutorial Navigator)
本ブログの3.3章 CRUD処理にて参考としているチュートリアルです。SAP S/4HANAのODataを利用したSAP Cloud SDK開発を基礎から網羅的に紹介していますのでお奨めです。
以上SAP Cloud PlatformでのSAP S/4HANA拡張のAPI利用編になりますが、いかがでしたでしょうか。冒頭でも触れました通り、APIの利用方法はSAP Cloud SDKだけでなくCloud Platform Integrationなどシナリオに応じて選択肢がありますので、今後ご紹介できればと思います。
次回は、SAP Enterprise Messagingを利用したイベント連携編になりますので、どうぞご期待ください。
- SAP Managed Tags:
