使用 SAP BTP 版本的 ABAP SDK for Google Cloud 进行应用开发

本文档为您提供了有用的信息和资源，可帮助您使用 SAP BTP 版本的 ABAP SDK for Google Cloud 开发 SAP 应用。

本文档面向 SAP ABAP 开发者。

如需查看 SAP BTP 版本的 ABAP SDK for Google Cloud 提供的客户端库的完整列表，请参阅 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 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 使用 logging 框架记录错误消息。

API 设计和 Google APIs 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 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 方法的部分：

导入参数

API 方法可以具有以下导入参数。这些参数是可选的，您可以根据需要使用的 API 方法的要求传递参数。

导出参数

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 (ADT) 的 ABAP 开发工具进行开发时，这些注释可以提供类类型的说明。

API 返回代码、错误和异常

如果在调用 ABAP 类的 API 方法时发生错误，则 ABAP SDK for Google Cloud 会使用 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 Maps Platform API，如果您使用无效输入调用 API，则该 API 将返回 HTTP 成功状态代码 2XX 以及错误消息和错误状态，而不是 HTTP 错误状态代码（4XX 或 5XX）。API 响应中的此错误消息和错误状态可帮助您排查问题并修复无效输入。

对于此类 Google Maps Platform API，除了返回代码 ev_ret_code 之外，还要检查 API 响应中返回的错误消息和错误状态，具体方法是在 API 调用之后调用 IS_STATUS_OK 方法。以下代码段展示了如何使用 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 返回的常见错误及其原因，请参阅错误代码。

• 捕获详细错误：如需使用 ABAP SDK for Google Cloud 捕获详细的错误信息，请使用 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 的值。

如需了解 ABAP SDK for Google Cloud 触发的典型错误消息及其解决方法，请参阅问题排查指南。

日志记录

SAP BTP 版本的 ABAP SDK for Google Cloud 可让您使用嵌入式日志记录框架来记录错误消息。SDK 附带了日志对象 /GOOG/LOG_OBJECT 和子对象 /GOOG/LOG_SUBOBJECT，可用于创建默认日志配置。如需详细了解如何创建默认日志配置，请参阅配置日志记录。

您可以使用 Google SDK:Application Logs Display 应用查看应用日志。如需了解详情，请参阅查看日志。

数据类型映射

下表提供了 Google API Discovery Service 支持的 type 和 format 值以及相应 ABAP 数据类型的完整列表。

如需详细了解 Google API Discovery Service 支持的 type 和 format 值，请参阅类型和格式摘要。

API 请求和响应的序列化和反序列化

默认情况下，SAP BTP 版本的 ABAP SDK for Google Cloud 负责对 API 请求和响应进行编组和解组。Google Cloud API 的每个 ABAP 类都嵌入了 ABAP 类型，以构成方法的输入和输出。如需实现请求和响应的自定义转换，您可以将增强点与 SDK 附带的 SAP Business Add In (BAdI) 定义结合使用。

实现自定义转换

SDK 附带的增强点 /GOOG/ES_TRANSFORM_JSON 包含以下 BAdI 定义：

• /GOOG/BADI_SERIALIZE_JSON：用于实现自定义序列化逻辑。
• /GOOG/BADI_DESERIALIZE_JSON：用于实现自定义反序列化逻辑。

您可以在这些 BAdI 的实现中编写特定的转换逻辑。这些 BAdI 的接口使用 IV_METHOD_NAME 作为导入参数。您可以使用此参数和 IF….ENDIF 代码块来隔离每个 API 和 API 方法的转换逻辑。在您的实现块中，将导出参数 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 Customer Care 联系。如需了解如何与 Customer Care 团队联系，请参阅获取 Google Cloud 上的 SAP 支持。