使用 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 方法，您可以使用以下互动流程：

连接到 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 使用 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

导入参数

下表介绍了方法构造函数的导入参数：

参数名称	类型	必需/可选	说明
`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 界面

映射到 API 操作的 ABAP 方法的名称遵循以下格式：<method_verb>_<resource>。

例如，Pub/Sub 的 ABAP 方法名称为：GET_TOPICS

GET：方法操作。
TOPICS：资源名称。

ABAP 方法包含以下映射到 REST API 方法的部分：

方法名称

导入参数

API 方法可以具有以下导入参数。这些参数是可选的，您可以根据需要使用的 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 资源：主题，该资源会以 JSON 载荷形式传递给 `CREATE_TOPICS` 方法。一个方法最多可以有一个请求正文参数。某些方法没有请求正文。

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 资源：主题，该资源会以 JSON 载荷形式传递给 CREATE_TOPICS 方法。

一个方法最多可以有一个请求正文参数。某些方法没有请求正文。

导出参数

API 方法支持以下导出参数：

参数名称	类型	类别	说明
`es_raw`	数据	原始输出	此参数包含 API 方法返回的 JSON 响应（错误或成功）。将此参数映射到字符串类型的变量以接收 JSON 响应字符串。如果响应是任何其他类型（例如，`/goog/cl_storage_v1->get_objects( )` 中文件输出的 xstring），则参数会返回适当的值。将此参数用于高级问题排查场景或高级 API 场景。
`es_output`	TY_`CODE` （类类型）	输出结构	JSON 响应会反序列化为 ABAP 结构，并使用此类型化导出参数返回。您可以将此用作使用 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 (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 中的字段。

字段	值
`es_err_resp-error_description`	从 API 收到的错误消息。此值与参数 `ev_error_text` 相同。
`es_err_resp-error`	从 SAP HTTP 客户端返回的 HTTP 状态说明。

处理 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 的值。

`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 触发的典型错误消息及其解决方法，请参阅问题排查指南。

日志记录

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 值，请参阅类型和格式摘要。

类型值	格式值	ABAP 数据类型	含义
任意		TYPE REF TO DATA	该属性可以是任何类型。由 JSON 架构规范定义。
数组		TABLE TYPE WITH NON UNIQUE KEYS	一个 JavaScript 值数组。items 属性指示数组值的架构。由 JSON 架构规范定义。
布尔值		ABAP_BOOLEAN	布尔值，可以是“true”或“false”。由 JSON 架构规范定义。
整数	int32	INT4	32 位带符号整数。最小值为 -2147483648，最大值为 2147483647（含）。
整数	uint32	INT4	32 位无符号整数。最小值为 0，最大值为 4294967295（含）。
数字	双精度	`/GOOG/NUM_DOUBLE`（字符串）	双精度 64 位 IEEE 754 浮点。
数字	float	`/GOOG/NUM_FLOAT`（字符串）	单精度 32 位 IEEE 754 浮点。
对象		TYPES	JavaScript 对象。由 JSON 架构规范定义。
字符串		STRING	任意字符串。由 JSON 架构规范定义。
字符串	字节	STRING	填充的 base64 编码字节字符串，使用网址和文件名安全字母表（有时称为“网络安全”或“base64url”）进行编码。由 RFC 4648 定义。
字符串	日期	STRING	RFC 3339 日期，格式为 YYYY-MM-DD。在 JSON 架构规范中定义。
字符串	date-time	STRING	采用世界协调时间 (UTC) 的 RFC 3339 时间戳。格式为 yyyy-MM-ddTHH:mm:ss.SSSZ。毫秒部分（“.SSS”）是可选的。在 JSON 架构规范中定义。
字符串	google-datetime	STRING	采用世界协调时间 (UTC) 的 RFC 3339 时间戳。格式为 yyyy-MM-ddTHH:mm:ss.SSSZ。毫秒部分（“.SSS”）是可选的。
字符串	google-duration	STRING	字符串以后缀“s”（表示秒）结尾，后跟秒，其中纳秒表示小数秒。英文句点始终用作小数点，而不是英文逗号。
字符串	google-fieldmask	STRING	以逗号分隔的字符串名称。字段名称以驼峰式命名规则表示。
字符串	int64	STRING	64 位带符号整数。最小值为 -9223372036854775808，最大值为 9223372036854775807（含）。
字符串	uint64	STRING	64 位无符号整数。其最小值为 0，最大值为 (2^64)-1（含）。

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。

如需实现自定义转换，请按照以下步骤操作：

对于 /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 问题时需要帮助，请执行以下操作：

参阅 ABAP SDK for Google Cloud 问题排查指南。
在 Cloud 论坛上提出问题并与社区讨论 ABAP SDK for Google Cloud。
收集所有可用的诊断信息，并与 Cloud Customer Care 联系。如需了解如何与 Customer Care 团队联系，请参阅获取 Google Cloud 上的 SAP 支持。