使用 SAP BTP 版的 ABAP SDK for Google Cloud 開發應用程式

本文件提供實用資訊和資源，協助您使用 Google Cloud 適用的 ABAP SDK 的 SAP BTP 版本開發 SAP 應用程式。

本文件適用於 SAP ABAP 開發人員。

如需 SAP BTP 版 ABAP SDK for Google Cloud 提供的用戶端程式庫完整清單，請參閱「ABAP SDK for Google Cloud 用戶端程式庫」。

單一互動視窗

在 ABAP SDK for Google Cloud 中啟用的每個 Google Cloud API 都會以 ABAP 類別表示，並包含在 /GOOG/CLIENT 套件中。ABAP 類別包含多個公開方法，且每個公開方法都對應至Google Cloud API 方法。每個公開方法都包含 IMPORTING 參數和 EXPORTING 參數。ABAP 類別也包含自訂資料類型，可用於建構及對應 IMPORTING 和 EXPORTING 參數。這些自訂資料類型會對應至 API 架構定義。

對於與目標 Google Cloud API 的每項互動，其對應的 ABAP 類別會充當唯一的互動點。我們稱這項概念為「單一互動視窗」，可隱藏與Google Cloud API 互動時的所有基礎複雜性，並提供簡化的介面。這個簡化的介面可讓您專注於使用 SDK 開發的業務解決方案，而不必擔心底層 SDK 功能。

互動流程

如要呼叫 API 方法，請遵循以下互動流程：

1. 連結至 API。
2. 使用 ABAP 類型建構輸入要求。
3. 呼叫 API 方法。
4. 剖析錯誤和例外狀況。
5. 使用 ABAP 類型讀取回應。

API 用戶端存根

一般 API 用戶端 Stub 類別包含下列部分：

• 對應至 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。

Google 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

匯入參數

下表說明方法建構函式的匯入參數：

API 方法

在 Google Cloud API 的資源導向設計中，API 方法是指可在 API 發布的資源上執行的動作。

舉例來說，如果 Topics 是 Pub/Sub API 發布的資源，topics.get 就是 API 方法，代表在資源 Topics 上執行的動作，以取得主題的設定。

如要將 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 方法的部分組成：

匯入參數

API 方法可包含下列匯入參數。這些參數為選用，您可以根據要使用的 API 方法需求傳遞參數。

匯出參數

API 方法支援下列匯出參數：

類別

Google Cloud API 會使用 JSON 做為資料交換的主要格式。Google Cloud 適用的 ABAP SDK 提供 ABAP 類型，可對應至 Google Cloud API 預期的 JSON 結構定義。

這些 ABAP 類型和相關資料表類型可做為類別類型，用於 SDK 提供的每個 API 類別。

以下範例顯示 Pub/Sub API 類別 /GOOG/CL_PUBSUB_V1 的類別類型。

/GOOG/CL_PUBSUB_V1 下方的類別類型 TY_041 說明會對應至 REST 資源 Topic，並以 JSON 酬載的形式傳遞至 CREATE_TOPICS 方法。

ABAP Doc 註解會新增至所有用戶端 API 類別。使用 ABAP Development Tools for SAP NetWeaver (ADT) 進行開發時，這些註解會提供類型類型的說明。

API 傳回代碼、錯誤和例外狀況

如果在呼叫 ABAP 類別的 API 方法時發生錯誤，Google Cloud 的 ABAP SDK 會使用 SDK 匯出參數或擲回例外狀況，將錯誤資訊傳遞至呼叫程式。

API 傳回碼和錯誤

Google Cloud API 使用錯誤模型，可在不同 API 中提供一致的體驗。從 SDK 呼叫 Google Cloud API 方法時，下列參數會包含 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 地圖平台 API，如果您呼叫的 API 有無效輸入內容，API 會傳回 HTTP 成功狀態碼 2XX，並附上錯誤訊息和錯誤狀態，而非 HTTP 錯誤狀態碼 (4XX 或 5XX)。API 回應中的錯誤訊息和錯誤狀態可協助您排解問題，並修正無效的輸入內容。

針對這類 Google 地圖平台 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 API 傳回的錯誤

請參考下列指南，處理Google Cloud API 傳回的錯誤：

• 常見錯誤代碼：如要瞭解Google Cloud API 傳回的常見錯誤及其原因，請參閱「錯誤代碼」。

• 擷取詳細錯誤：如要使用 Google Cloud 的 ABAP SDK 擷取詳細錯誤資訊，請使用 SDK 類別方法中的匯出參數 es_raw，並將此參數對應至 String 類型的變數。這個變數會保留 JSON 回應，其中包含詳細的錯誤訊息和 API 遇到的特定違規事項。

• 查看詳細錯誤：如要查看詳細錯誤資訊，請使用下列任一方法：

  • 偵錯工具：在 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 API 會在個別說明文件中提供詳細錯誤資訊和疑難排解指引。如要解決與 API 相關的錯誤，請參閱該 API 的說明文件，例如 Pub/Sub、Document AI 和 Cloud Storage。

例外狀況

當 API 方法呼叫期間發生非預期錯誤 (例如 SDK 設定不正確或 HTTP 通訊失敗) 時，SDK 會擲回 /GOOG/CX_SDK 類型的例外狀況。您必須在程式碼中擷取此例外狀況，並編寫適當的錯誤處理邏輯。

您可以呼叫例外狀況類別的 get_text 方法，取得錯誤訊息。例外狀況類別傳回的錯誤訊息格式如下：

/GOOG/MSG : Return_Code - Error_Message

錯誤原因和解決步驟取決於 Return_Code 的值。

如要瞭解在 Google Cloud 適用的 ABAP SDK 中觸發的常見錯誤訊息及其解決方法，請參閱疑難排解指南。

記錄

適用於 Google Cloud 的 ABAP SDK 的 SAP BTP 版本可讓您使用內嵌記錄架構記錄錯誤訊息。記錄物件 /GOOG/LOG_OBJECT 和子物件 /GOOG/LOG_SUBOBJECT 會隨 SDK 一併提供，您可以用來建立預設記錄設定。如要進一步瞭解如何建立預設記錄設定，請參閱「設定記錄功能」。

您可以使用 Google SDK:Application Logs Display 應用程式查看應用程式記錄。詳情請參閱「查看記錄」。

資料類型對應

下表列出 Google API Discovery Service 支援的 type 和 format 值完整清單，以及對應的 ABAP 資料類型。

如要進一步瞭解 Google API Discovery Service 支援的 type 和 format 值，請參閱「類型和格式摘要」。

對 API 要求和回應進行序列化和去序列化

根據預設，Google Cloud 適用的 ABAP SDK 的 SAP BTP 版本會負責排序和解序 API 要求和回應。每個 Google CloudAPI 的 ABAP 類別都內嵌 ABAP 類型，用於形成方法的輸入和輸出。如要實作要求和回應的自訂轉換，您可以使用增強點，搭配 SDK 隨附的 SAP Business Add In (BAdI) 定義。

實作自訂轉換

附加位置 /GOOG/ES_TRANSFORM_JSON 隨 SDK 一併提供，其中包含下列 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/ 下。

參考架構

透過參考架構探索 Google Cloud 適用的 ABAP SDK，瞭解 SDK 如何為 SAP 應用程式環境帶來創新。您可以使用 SDK 整合 Vertex AI，取得進階 AI 和機器學習功能，以及其他 Google Cloud服務，例如 BigQuery、Pub/Sub、Cloud Storage 等。詳情請參閱「ABAP SDK for Google Cloud 的參考架構」。

取得支援

如需協助解決 ABAP SDK for Google Cloud 的問題，請按照下列步驟操作：

• 請參閱 ABAP SDK for Google Cloud 疑難排解指南。

• 在 Cloud 論壇上向社群提問，並討論 ABAP 適用的 Google Cloud SDK。

• 收集所有可用的診斷資訊，並與 Cloud Customer Care 團隊聯絡。如要瞭解如何與 Customer Care 聯絡，請參閱「取得 SAP 支援 Google Cloud」一文。