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

SAP BTP edition v1.0

• SAP BTP エディション v1.0
• オンプレミスまたは任意のクラウド エディション v1.7

このドキュメントでは、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 メソッドを呼び出す場合、インタラクションの流れは次のようになります。

1. API に接続します。
2. ABAP タイプを使用して入力リクエストを作成します。
3. API メソッドを呼び出します。
4. エラーと例外を解析します。
5. 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: メソッド アクション。

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

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 に設定してください。

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

1. /GOOG/BADI_SERIALIZE_JSON のために、次のように拡張実装を作成します。

   • API リクエストを変換するには、実装クラスを使用して BAdI /GOOG/BADI_SERIALIZE_JSON の実装を作成します。
   • API レスポンスを変換するには、実装クラスを使用して BAdI /GOOG/BADI_DESERIALIZE_JSON の実装を作成します。

2. 変換をプログラミングする必要のある API メソッドのメソッド ID を特定します。メソッド ID は、次の要素を連結したものです。

   • クラス属性定数 C_SERVICE_NAME の値。
   • 文字 #。
   • 変換を実装する必要がある API クラスメソッドの説明。

   たとえば、メッセージを Pub/Sub トピックにパブリッシュするための変換をプログラミングするときのメソッド ID は pubsub:v1#pubsub.projects.topics.publish となります。

3. BAdI のメソッド実装で、次のことを行います。

   1. そのメソッド ID のカスタム変換を IF….ENDIF block の下でプログラミングします。

   2. エクスポート パラメータ EV_HANDLED を X に設定します。

      EV_HANDLED が X に設定されていない場合は、SDK のデフォルトのマーシャリングとアンマーシャリングのロジックが適用されます。

4. 実装クラスの API State を Use System-Internally (Contract C1) としてマークします。カスタム変換ロジックは実行時に呼び出されます。SDK 付属のデフォルトのシリアル化と逆シリアル化のロジックがスキップされます。

名前空間

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

サポートを利用する

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

• ABAP SDK for Google Cloud トラブルシューティング ガイドをご覧ください。

• Cloud フォーラムのコミュニティで ABAP SDK for Google Cloud について質問し、ディスカッションに参加します。

• 入手可能なすべての診断情報を収集し、Cloud カスタマーケアにお問い合わせください。カスタマーケアへのお問い合わせについては、Google Cloud での SAP に関するサポートを受けるをご覧ください。