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

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 パラメータ

次の表では、メソッド コンストラクタのインポート パラメータを示しています。

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 メソッドの要件に応じてパラメータを渡すことができます。

exporting パラメータ

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

クラスタイプ

Google Cloud APIs では、データ交換の基本的な形式として JSON を使用します。ABAP SDK for Google Cloud は、Google Cloud API で想定される 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 のエクスポート パラメータを使用するか、例外を発生させることで呼び出し側のプログラムにエラー情報を渡します。

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 パラメータのフィールドの説明を示します。

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 の値によって異なります。

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 の値については、型と形式の概要をご覧ください。

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 を調べ、SDK を使用して SAP アプリケーション ランドスケープにイノベーションをもたらす方法を確認します。この SDK を使用すると、高度な AI と ML 機能の 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 に関するサポートを受けるをご覧ください。