ABAP SDK for Google Cloud の SAP BTP エディションを使用したアプリケーション開発

このドキュメントでは、ABAP SDK for Google Cloud の SAP BTP エディションを使用して SAP アプリケーションを開発する際に有用な情報とリソースを紹介します。

このドキュメントは、SAP ABAP のデベロッパーを対象としています。

ABAP SDK for Google Cloud の SAP BTP エディションが提供するクライアントライブラリの完全なリストについては、ABAP SDK for Google Cloud クライアントライブラリをご覧ください。

単一ウィンドウでのインタラクション

ABAP SDK for Google Cloud で有効になっている各 Google Cloud API は、/GOOG/CLIENT パッケージに含まれる ABAP クラスによって表されます。ABAP クラスは複数のパブリックメソッドで構成され、それぞれのパブリックメソッドが Google Cloud API メソッドに対応しています。また、パブリックメソッドは IMPORTING パラメータと EXPORTING パラメータで構成されています。ABAP クラスにはカスタムデータ型も含まれています。これは、IMPORTING パラメータと EXPORTING パラメータの作成とマッピングに使用できます。これらのカスタムデータ型は API スキーマ定義にマッピングされます。

ターゲットの Google Cloud API を操作するたびに、対応する ABAP クラスが唯一のインタラクションポイントとして機能します。Google では、このコンセプトを「単一ウィンドウでのインタラクション」と呼んでいます。これにより、Google Cloud API とのインタラクションに存在する複雑さが見えなくなり、インターフェースが簡略化されます。このシンプルなインターフェースにより、基盤となる SDK の機能を気にすることなく、SDK を使用したビジネスソリューションの開発に集中できます。

単一ウィンドウでのインタラクション

インタラクションの流れ

API メソッドを呼び出す場合、インタラクションの流れは次のようになります。

API に接続します。
ABAP タイプを使用して入力リクエストを作成します。
API メソッドを呼び出します。
エラーと例外を解析します。
ABAP タイプを使用してレスポンスを読み取ります。

デベロッパーのインタラクション

API クライアントスタブ

一般的な API クライアントのスタブクラスは、次のセクションで構成されています。

API スキーマにマッピングされる ABAP タイプ。ABAP タイプは、入力リクエストの作成とレスポンスの解析に使用します。
内部または外部で使用する定数と属性。
API リソースとのインタラクションを行う API メソッド。

クラス構造

機能

ABAP SDK for Google Cloud には次の機能があります。

HTTP 通信: SDK は API エンドポイントと HTTP 接続を確立します。
リクエストのマーシャリング: SDK は、ABAP タイプのデータを JSON ペイロードに変換し、リクエスト本文として送信します。
エラーと例外の処理: SDK は、API から返された戻りコードとエラーメッセージを処理し、必要に応じて例外を発生させます。
レスポンスの復元: SDK は、レスポンス本文の JSON ペイロードを対応する ABAP タイプに変換します。
ローカルエラーのロギング: SDK は、ロギングフレームワークを使用してエラーメッセージをロギングします。

API の設計と Google API Explorer

Google が公開している API はリソース指向の設計に基づいています。Google の API の設計について詳しくは、API 設計ガイドをご覧ください。

ABAP SDK for Google Cloud を使用すると、Google が公開している REST ベースの API との統合が可能になります。

API Explorer は、コードを記述することなく Google Cloud API メソッドを試すことができるツールです。このツールを使用すると、対応する ABAP メソッドに渡す API と必須入力パラメータを確認できます。

コードの構造

ABAP SDK for Google Cloud を使用して ABAP プログラムを作成する際に使用するコード構造について説明します。

コンストラクタ

まず、使用する API クラスをインスタンス化します。API クラスのコンストラクタは、次の例のようなパターンになります。

    METHODS constructor
      IMPORTING
        !iv_key_name   TYPE /goog/keyname OPTIONAL "Google Cloud Key Name
        !iv_log_obj    TYPE balobj_d OPTIONAL      "Application log: Object name
        !iv_log_subobj TYPE balsubobj OPTIONAL.    "Application log: Subobject
      RAISING
        /goog/cx_sdk .                 "Exception Classes

importing パラメータ

次の表には、メソッドコンストラクタの importing パラメータを示します。

パラメータ名	タイプ	必須 / 省略可	説明
`iv_key_name`	`/GOOG/KEYNAME`	必須	Google Cloud との接続に使用する構成のクライアントキーを指定します。クライアントキーの構成については、認証をご覧ください。
`iv_log_object`	`balobj_d`	省略可	SDK によって生成されたエラーを格納するアプリケーションログオブジェクトを指定します。ロギング構成については、アプリケーションロギングをご覧ください。
`iv_log_subobject`	`balsubobj`	省略可	SDK によって生成されたエラーを格納するアプリケーションログサブオブジェクトを指定します。ロギング構成については、アプリケーションロギングをご覧ください。

API メソッド

Google Cloud APIs はリソース指向の設計になっています。API メソッドは、API によって公開されたリソースに対するアクションとなります。

たとえば、Topics が Pub/Sub API によって公開されるリソースの場合、topics.get は、トピックの構成を取得するために Topics リソースに実行されるアクションを表す API メソッドです。

ABAP クラスメソッドを API メソッドにマッピングするには、<resource>.<method_verb> というパターンでメソッドの説明を参照します。

たとえば、Pub/Sub メソッドの説明は pubsub.projects.topics.get です。

projects.topics: リソース名。
get: メソッドアクション。

メソッドの説明が表示されている SAP UI

API アクションにマッピングする ABAP メソッドの名前は、<method_verb>_<resource> というパターンになります。

たとえば、Pub/Sub の ABAP メソッド名は GET_TOPICS です。

GET: メソッドアクション。
TOPICS: リソース名。

ABAP メソッドは、REST API メソッドに対応する次のセクションで構成されています。

メソッド名

importing パラメータ

API メソッドには、次の importing パラメータを指定できます。これらのパラメータは省略可能です。使用する API メソッドの要件に応じてパラメータを渡すことができます。

パラメータ名タイプカテゴリ説明

パラメータ名	タイプ	カテゴリ	説明
`iv_q_NAME` （`0` から `n`）	文字列	クエリパラメータ	クエリパラメータは、API エンドポイントの `?` の後に追加されます。並べ替え、ページ分け、フィルタの定義に使用されます。 `0` から `n` のクエリパラメータが存在する可能性があります。
`iv_p_NAME` （`0` から `n`）	文字列	パスパラメータ	パスパラメータはエンドポイントの一部です。特定の REST API リソースを指すために使用されます。 `0` から `n` のパスパラメータが存在する可能性があります。
`is_input` （`0` から `1`）	TY_`CODE` （クラスタイプ）	入力構造パラメータ	リクエスト本文として渡されるデータは、入力構造を使用してマッピングできます。 REST API は、リクエスト本文として JSON ペイロードを受け入れます。このパラメータは、API クラスの JSON ペイロードに変換される完全なパラメータです。デベロッパーが JSON を扱う必要はありません。データをマッピングする ABAP タイプには、利用可能なクラスタイプを参照してください。たとえば、`/GOOG/CL_PUBSUB_V1=>TY_041` タイプは REST リソースの Topic にマッピングされ、これが JSON ペイロードとして `CREATE_TOPICS` メソッドに渡されます。 1 つのメソッドに複数のリクエスト本文パラメータを指定することはできません。リクエスト本文のないメソッドもあります。

iv_q_NAME

（0 から n）

文字列

クエリパラメータ

クエリパラメータは、API エンドポイントの ? の後に追加されます。

並べ替え、ページ分け、フィルタの定義に使用されます。

0 から n のクエリパラメータが存在する可能性があります。

iv_p_NAME

（0 から n）

文字列

パスパラメータ

パスパラメータはエンドポイントの一部です。

特定の REST API リソースを指すために使用されます。

0 から n のパスパラメータが存在する可能性があります。

is_input

（0 から 1）

TY_CODE （クラスタイプ）

入力構造パラメータ

リクエスト本文として渡されるデータは、入力構造を使用してマッピングできます。

REST API は、リクエスト本文として JSON ペイロードを受け入れます。このパラメータは、API クラスの JSON ペイロードに変換される完全なパラメータです。デベロッパーが JSON を扱う必要はありません。

データをマッピングする ABAP タイプには、利用可能なクラスタイプを参照してください。たとえば、/GOOG/CL_PUBSUB_V1=>TY_041 タイプは REST リソースの Topic にマッピングされ、これが JSON ペイロードとして CREATE_TOPICS メソッドに渡されます。

1 つのメソッドに複数のリクエスト本文パラメータを指定することはできません。リクエスト本文のないメソッドもあります。

exporting パラメータ

API メソッドでは、次の exporting パラメータがサポートされています。

パラメータ名	タイプ	カテゴリ	説明
`es_raw`	data	未加工の出力	このパラメータには、API メソッドから返される JSON レスポンス（エラーまたは成功）が格納されます。このパラメータを文字列型の変数にマッピングして、JSON レスポンスの文字列を取得します。レスポンスが他のタイプの場合（`/goog/cl_storage_v1->get_objects( )` のファイル出力が xstring の場合など）、パラメータは適切な値を返します。このパラメータは、高度なトラブルシューティングのシナリオや高度な API のシナリオで使用します。
`es_output`	TY_`CODE`（クラスタイプ）	出力構造	JSON レスポンスは、シリアル化解除されて ABAP 構造に変換され、この型の付いた exporting パラメータを使用して返されます。これは、ABAP 構造を使用して API レスポンスを読み取る際のメインの方法として使用できます。
`ev_ret_code`	I（整数）	戻りコード	API メソッドの実行が機能を正常に実行できたかどうかの確認に使用できる戻りコード。詳細については、API 戻りコード、エラー、例外をご覧ください。
`ev_err_text`	文字列	エラーテキスト	メソッド呼び出しが失敗すると、このパラメータにエラーメッセージが格納されます。これは、エラーの原因を追究する際に使用します。詳細については、API 戻りコード、エラー、例外をご覧ください。
`ev_err_resp`	エラーの種類 = CHAR 60 エラーの説明 = STRING	エラーレスポンス	パラメータはエラーに関する追加情報を返します。詳細については、API 戻りコード、エラー、例外をご覧ください。

クラスタイプ

Google Cloud APIs では、データ交換の基本的な形式として JSON を使用します。ABAP SDK for Google Cloud は、Google Cloud APIs で想定される JSON スキーマにマッピングされる ABAP タイプを提供します。

これらの ABAP タイプと関連テーブルのタイプは、SDK が提供するすべての API クラスでクラスタイプとして使用できます。

次の例は、Pub/Sub API クラス /GOOG/CL_PUBSUB_V1 のクラスタイプを示しています。

クラスタイプ

/GOOG/CL_PUBSUB_V1 の下にある TY_041 クラスタイプの説明は、REST リソース Topic にマッピングされます。これは JSON ペイロードとして CREATE_TOPICS メソッドに渡されます。

ABAP Doc コメントは、すべてのクライアント API クラスに追加されます。開発に SAP NetWeaver 用 ABAP 開発ツール（ADT）を使用する場合、これらのコメントにクラスタイプの説明が含まれます。

API 戻りコード、エラー、例外

ABAP クラスの API メソッドが呼び出されたときにエラーが発生した場合は、ABAP SDK for Google Cloud は、SDK の exporting パラメータを使用するか、例外を発生させて、呼び出し側のプログラムにエラー情報を渡します。

戻りレスポンス名

API 戻りコードとエラー

Google Cloud APIs が使用するエラーモデルでは、どの API でも一貫したエクスペリエンスが提供されます。Google Cloud APIs のメソッドが SDK から呼び出された場合、次のパラメータに API の戻りコードとメッセージが含まれます。

ev_ret_code: レスポンスの戻りコードまたはエラーコード。
ev_error_text: レスポンスのエラーメッセージ（ある場合）。
es_raw: API メソッドの呼び出しに失敗した場合の未加工のエラーレスポンス。

API 呼び出しのステータスを確認するには、IS_SUCCESS メソッドを使用します。ev_ret_code の値から、API の呼び出しが成功したかどうかを判断できます。一般的に、ev_ret_code = 2XX の場合、メソッド呼び出しは成功したとみなされます。他の値の場合、メソッド呼び出しは失敗とみなされます。

IF lo_client->is_success( ev_ret_code ).
   "Success: Implement custom code
   ELSE
   "Handle the HTTP error status code
ENDIF.

一部の Google Maps Platform API では、無効な入力で API を呼び出すと、HTTP エラーステータスコード（4XX または 5XX）ではなく、HTTP 成功ステータスコード 2XX がエラーメッセージとエラーステータスとともに返されます。API レスポンスのこのエラーメッセージとエラーステータスは、問題のトラブルシューティングと無効な入力の修正に役立ちます。

このような Google Maps Platform API では、戻りコード ev_ret_code に加えて、API 呼び出しの後で IS_STATUS_OK メソッドを呼び出して、API レスポンスで返されるエラーメッセージとエラーステータスを確認します。次のスニペットは、IS_STATUS_OK メソッドの使用方法の例を示しています。

IF lo_client->is_status_ok( ).
  "Success: Implement custom code
  ELSE
  "Handle the HTTP error status code
ENDIF.

es_err_resp パラメータは、エラーに関する追加情報を提供します。次の表に、es_err_resp パラメータのフィールドの説明を示します。

フィールド	値
`es_err_resp-error_description`	API から受信したエラーメッセージ。この値は `ev_error_text` パラメータと同じです。
`es_err_resp-error`	SAP HTTP クライアントから返された HTTP ステータスの説明。

Google Cloud APIs から返されるエラー

次のガイダンスを使用して、Google Cloud APIs から返されるエラーを処理します。

一般的なエラーコード: Google Cloud APIs から返される一般的なエラーとその原因については、エラーコードをご覧ください。
詳細なエラーをキャプチャする: ABAP SDK for Google Cloud で詳細なエラー情報を取得するには、SDK クラスメソッドのエクスポートパラメータ es_raw を使用し、このパラメータを String 型の変数にマッピングします。この変数は、詳細なエラーメッセージと API で発生した特定の違反を含む JSON レスポンスを格納します。
エラーの詳細を表示する: 詳細なエラー情報を表示するには、次のいずれかの方法を使用します。
- デバッガ: 詳しい分析を行うために、ABAP デバッガツールを使用して、JSON レスポンスが格納されている変数の内容を確認します。
- SAP GUI: ABAP クラス cl_demo_output=>display( lv_response ) を使用して、レポートプログラム内のエラーを視覚的に表します。レポートプログラムで API メソッドを使用していてプログラムの実行がフォアグラウンドモードである場合は、ABAP クラス cl_demo_output=>display_json( lv_response ) を使用します。
  
  次のコードスニペットでは、エラーが発生した場合に API レスポンスを表示する方法を示します。
```
DATA lv_response  TYPE string,
  TRY.
      lo_translate = NEW #( iv_key_name = 'DEMO_TRANSLATE' ).
      lo_translate->translate_translations
        EXPORTING
          is_input    = ls_input
        IMPORTING
          es_raw      = lv_response
          es_output   = ls_output
          ev_ret_code = lv_ret_code
          ev_err_text = lv_err_text
          es_err_resp = ls_err_resp.
      IF lo_translate->is_error( lv_ret_code ) = abap_true.
        " Display API response in case of an error
        cl_demo_output=>display_json( lv_response ).
      ENDIF.
    CATCH /goog/cx_sdk INTO lo_exception.
      lv_err_text = lo_exception->get_text( ).
  ENDTRY.
```
API 固有のドキュメント: 一部の Google Cloud APIs については、詳細なエラー情報とトラブルシューティングのガイダンスが個別のドキュメントに記載されています。API に関連するエラーを解決するには、Pub/Sub、Document AI、Cloud Storage など、該当する API のドキュメントをご覧ください。

例外

API メソッドの呼び出し中に予期しないエラー（SDK 構成の誤りや HTTP 通信の失敗など）が発生すると、SDK は /GOOG/CX_SDK タイプのクラス例外を発生させます。作成するコードには、この例外をキャッチし、適切なエラー処理を実行するロジックを記述する必要があります。

例外の処理

エラーメッセージを取得するには、例外クラスの get_text メソッドを呼び出します。例外クラスから返されるエラーメッセージの形式は次のとおりです。

/GOOG/MSG : Return_Code - Error_Message

エラーの原因と解決手順は Return_Code の値によって異なります。

`Return_Code` の値	エラーの原因	解決策
`461`	インストールと構成で特定の手順が行われていないか、完了していないことを通知する場合、ABAP SDK for Google Cloud は特別な戻りコード `461` を使用します。対応する `Error_Message` でエラーの詳細を確認できます。	SDK のインストールと構成の手順が正しく行われていることを確認してください。
その他の値	この戻りコードは、標準の SAP HTTP クライアントクラスからの最後の HTTP エラーです。このエラーは、SAP ICM が Google REST API メソッドを呼び出すときに通信の問題が発生したことを示します。	ネットワーク、ファイアウォール、SAP ICM の設定をチェックし、構成で Google Cloud APIs への HTTP 呼び出しが許可されていることを確認してください。

ABAP SDK for Google Cloud でトリガーされる一般的なエラーメッセージとその解決策については、トラブルシューティングガイドをご覧ください。

ロギング

ABAP SDK for Google Cloud の SAP BTP エディションでは、埋め込みロギングフレームワークを使用してエラーメッセージを記録できます。ログオブジェクト /GOOG/LOG_OBJECT とサブオブジェクト /GOOG/LOG_SUBOBJECT は、デフォルトのログ構成の作成に使用できる SDK に付属しています。デフォルトのログ構成の作成の詳細については、ロギングの構成をご覧ください。

アプリケーションログは、Google SDK:Application Logs Display アプリを使用して表示できます。詳しくは、ログを表示するをご覧ください。

データ型マッピング

次の表に、Google API Discovery Service でサポートされている type 値と format 値、それに対応する ABAP データ型を示します。

Google APIs Discovery Service でサポートされている type と format の値については、型と形式の概要をご覧ください。

Type 値	Format 値	ABAP データ型	意味
any		TYPE REF TO DATA	このプロパティには任意の型を指定できます。JSON スキーマ仕様で定義されています。
array		TABLE TYPE WITH NON UNIQUE KEYS	JavaScript 配列。items プロパティは配列値のスキーマを示します。JSON スキーマ仕様で定義されています。
boolean		ABAP_BOOLEAN	ブール値（true または false）。JSON スキーマ仕様で定義されています。
integer	int32	INT4	32 ビット符号付き整数。最小値は -2,147,483,648、最大値は 2,147,483,647 です。
integer	uint32	INT4	32 ビット符号なし整数。最小値は 0、最大値は 4,294,967,295 です。
number	double	`/GOOG/NUM_DOUBLE`（文字列）	倍精度 64 ビット IEEE 754 浮動小数点。
number	float	`/GOOG/NUM_FLOAT`（文字列）	単精度 32 ビット IEEE 754 浮動小数点。
object		TYPES	JavaScript オブジェクト。JSON スキーマ仕様で定義されています。
string		STRING	任意の文字列。JSON スキーマ仕様で定義されています。
string	byte	STRING	パディングされた Base64 エンコードのバイト文字列。URL およびファイル名セーフ型でエンコードされます（ウェブセーフ、base64url と呼ばれることもあります）。RFC 4648 で定義されています。
string	date	STRING	RFC 3339 の日付（YYYY-MM-DD 形式）。JSON スキーマ仕様で定義されています。
string	date-time	STRING	RFC 3339 タイムスタンプ（UTC 時間）。形式は yyyy-MM-ddTHH:mm:ss.SSSZ です。ミリ秒部分（.SSS）は省略可能です。JSON スキーマ仕様で定義されています。
string	google-datetime	STRING	RFC 3339 タイムスタンプ（UTC 時間）。形式は yyyy-MM-ddTHH:mm:ss.SSSZ です。ミリ秒部分（.SSS）は省略可能です。
string	google-duration	STRING	文字列の最後は秒数で、末尾に秒を表す s が付きます。ナノ秒は、小数点以下の秒数で表します。小数点にはカンマではなく、ピリオドを使用します。
string	google-fieldmask	STRING	フィールド名がカンマで区切られた文字列。フィールド名は、小文字のキャメルケースで表します。
string	int64	STRING	64 ビット符号付き整数。最小値は -9,223,372,036,854,775,808、最大値は 9,223,372,036,854,775,807 です。
string	uint64	STRING	64 ビット符号なし整数。最小値は 0、最大値は (2^64)-1 です。

API リクエストとレスポンスのシリアル化とシリアル化解除

デフォルトでは、ABAP SDK for Google Cloud の SAP BTP エディションによって、API リクエストとレスポンスのマーシャリングとアンマーシャリングが行われます。Google Cloud API の各 ABAP クラスには、メソッドの入力と出力を形成するための ABAP 型が組み込まれています。リクエストとレスポンスのカスタム変換を実装するには、SDK 付属の拡張スポットと SAP ビジネスアドイン（BAdI）定義を使用します。

カスタム変換を実装する

SDK 付属の拡張スポット /GOOG/ES_TRANSFORM_JSON には、次の BAdI 定義が含まれています。

/GOOG/BADI_SERIALIZE_JSON: カスタムシリアル化ロジックを実装するため。
/GOOG/BADI_DESERIALIZE_JSON: カスタム逆シリアル化ロジックを実装するため。

これらの BAdI の実装の中で、具体的な変換ロジックをプログラミングできます。これらの BAdI のインターフェースには、IV_METHOD_NAME がインポートパラメータとして含まれています。このパラメータを使用すると、各 API と API メソッドの変換ロジックを IF….ENDIF ブロックを使用して分離できます。実装ブロックの中で、エクスポートパラメータ EV_HANDLED を X に設定してください。

カスタム変換を実装する手順は次のとおりです。

/GOOG/BADI_SERIALIZE_JSON のために、次のように拡張実装を作成します。
- API リクエストを変換するには、実装クラスを使用して BAdI /GOOG/BADI_SERIALIZE_JSON の実装を作成します。
- API レスポンスを変換するには、実装クラスを使用して BAdI /GOOG/BADI_DESERIALIZE_JSON の実装を作成します。
変換をプログラミングする必要のある API メソッドのメソッド ID を特定します。メソッド ID は、次の要素を連結したものです。
- クラス属性定数 C_SERVICE_NAME の値。
- 文字 #。
- 変換を実装する必要がある API クラスメソッドの説明。
たとえば、メッセージを Pub/Sub トピックにパブリッシュするための変換をプログラミングするときのメソッド ID は pubsub:v1#pubsub.projects.topics.publish となります。
BAdI のメソッド実装で、次のことを行います。
1. そのメソッド ID のカスタム変換を IF….ENDIF block の下でプログラミングします。
2. エクスポートパラメータ EV_HANDLED を X に設定します。
  
  EV_HANDLED が X に設定されていない場合は、SDK のデフォルトのマーシャリングとアンマーシャリングのロジックが適用されます。
実装クラスの API State を Use System-Internally (Contract C1) としてマークします。カスタム変換ロジックは実行時に呼び出されます。SDK 付属のデフォルトのシリアル化と逆シリアル化のロジックがスキップされます。

名前空間

Google 提供のコードはすべて予約済みの名前空間 /GOOG/ に配置されます。

リファレンスアーキテクチャ

リファレンスアーキテクチャを使用して ABAP SDK for Google Cloud を調べ、SDK を使用して SAP アプリケーションランドスケープにイノベーションをもたらす方法を確認しましょう。この SDK を使用すると、高度な AI と機械学習機能を持つ Vertex AI や、BigQuery、Pub/Sub、Cloud Storage などの他の Google Cloud サービスと統合できます。詳細については、ABAP SDK for Google Cloud のリファレンスアーキテクチャをご覧ください。

サポートを受ける

ABAP SDK for Google Cloud の問題を解決するには、次の操作を行います。

ABAP SDK for Google Cloud トラブルシューティングガイドをご覧ください。
Cloud フォーラムのコミュニティで ABAP SDK for Google Cloud について質問し、ディスカッションに参加します。
入手可能なすべての診断情報を収集し、Cloud カスタマーケアにお問い合わせください。カスタマーケアへのお問い合わせについては、Google Cloud での SAP に関するサポートを受けるをご覧ください。

ABAP SDK for Google Cloud の SAP BTP エディションを使用したアプリケーション開発

単一ウィンドウでのインタラクション

インタラクションの流れ

API クライアント スタブ

機能

API の設計と Google API Explorer

コードの構造

コンストラクタ

importing パラメータ

API メソッド

importing パラメータ

exporting パラメータ

クラスタイプ

API 戻りコード、エラー、例外

API 戻りコードとエラー

Google Cloud APIs から返されるエラー

例外

ロギング

データ型マッピング

API リクエストとレスポンスのシリアル化とシリアル化解除

カスタム変換を実装する

名前空間

リファレンス アーキテクチャ

サポートを受ける

API クライアントスタブ

リファレンスアーキテクチャ