使用本地版本或任何云版本的 ABAP SDK for Google Cloud 进行应用开发

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

本文档面向 SAP ABAP 开发者。

如需查看本地或任何云版本的 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 设计和 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

导入参数

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

参数名称	类型	必需/可选	说明
`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 APIs 使用错误模型，可在不同的 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 触发的典型错误消息及其解决方法，请参阅问题排查指南。

日志记录

借助 ABAP SDK for Google Cloud，您可以使用嵌入式日志记录框架来记录错误消息。SDK 传输文件附带日志对象 ZGOOG 和子对象 ZABAP_SDK，您可以将其用作日志配置的默认对象。

作为开发者，您可以在实例化 API 客户端桩的同时传递自己的自定义日志对象和子对象。这需要额外配置来向 SDK 指示使用自定义日志对象，而不是默认日志对象和子对象。

以下示例展示了传递了自定义日志对象和子对象的调用代码：

TRY.
    CREATE OBJECT lo_api_class
      EXPORTING
        iv_key_name   = 'CLIENT_KEY'
        iv_log_obj    = 'ZSD'            "Application Log Object
        iv_log_subobj = 'ZSD_SALES_ORDERS'. "Subobject
  CATCH /goog/cx_sdk INTO DATA(lo_exception).
      DATA(lv_msg) = lo_exception->get_text( ).
      MESSAGE lv_msg TYPE 'E'.
ENDTRY.

如需详细了解如何配置日志记录和创建自定义日志对象，请参阅应用日志记录。

数据类型映射

下表提供了 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_BOOL	布尔值，可以是“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（含）。

演示计划

ABAP SDK for Google Cloud 附带了几个演示计划，向您展示如何使用 SDK 使用 Google 服务。演示程序位于软件包 /GOOG/DEMO 中。

演示计划涵盖各种 Google 服务，例如：

Document AI
Pub/Sub
Cloud Translation
Cloud Storage
Secret Manager

演示计划是了解如何使用 ABAP SDK for Google Cloud 的不错方法。它们也是测试配置的好方法。包含演示的计划文档提供了有关每个演示的更多详细信息。

如需访问演示程序，请执行以下步骤：

在 SAP GUI 中，执行事务代码 /GOOG/SDK_IMG。

或者，执行事务代码 SPRO，然后点击 SAP Reference IMG。
转到 ABAP SDK for Google Cloud > 演示。

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

默认情况下，ABAP SDK for Google Cloud 负责编组和解组 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 作为导入参数。借助此参数，您可以使用 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 的默认编组和解组逻辑。

自定义转换逻辑会在运行时调用。使用自定义转换时，系统会跳过 SDK 附带的默认序列化和反序列化逻辑。

命名空间

所有 Google 提供的代码都位于预留的命名空间 /GOOG/ 下。

代码向导

代码向导可帮助您加速 ABAP SDK for Google Cloud 提供的 API 客户端存根的所有公共方法开发。代码向导类似于 ABAP 开发中使用的 pattern 选项。但是，除了 ABAP pattern 之外，代码向导还提供帮助：

生成所有必需的数据声明。
在代码中提供用于提交方法导入参数的占位符。
生成基本响应和异常处理。
以选择 ABAP 7.5 语法以及添加和移除用于打开和关闭 HTTP 连接的块这种形式提供额外的自定义和功能。
为生成的代码提供复制选项。

代码向导仅提供了一个代码帧，您可以根据要求进行修改。代码向导支持 SAP S/4HANA 和 SAP ECC 语法。

如需访问代码向导，请执行以下步骤：

在 SAP GUI 中，执行事务代码 /GOOG/SDK_IMG。

或者，执行事务代码 SPRO，然后点击 SAP Reference IMG。
转到 ABAP SDK for Google Cloud > 实用程序 > 代码向导。

以下示例展示了为 Pub/Sub 客户端桩 /GOOG/CL_PUBSUB_V1 的 API 方法 CREATE_TOPICS 创建的样板代码：


 DATA:
   lv_p_projects_id TYPE string,
   lv_p_topics_id   TYPE string,
   ls_input         TYPE /goog/cl_pubsub_v1=>ty_041.

 TRY.

* Open HTTP Connection
     DATA(lo_client) = NEW /goog/cl_pubsub_v1( iv_key_name = 'client_key' ).

* Populate relevant parameters
* lv_p_projects_id = 'string_value'.
* lv_p_topics_id = 'string_value'.
* ls_input = .

* Call API method
     CALL METHOD lo_client->create_topics
       EXPORTING
         iv_p_projects_id = lv_p_projects_id
         iv_p_topics_id   = lv_p_topics_id
         is_input         = ls_input
       IMPORTING
*        es_raw           =
         es_output        = DATA(ls_output)
         ev_ret_code      = DATA(lv_ret_code)
         ev_err_text      = DATA(lv_err_text)
         es_err_resp      = DATA(ls_err_resp).

     IF /goog/cl_http_client=>is_success( lv_ret_code ).
       MESSAGE 'Success' TYPE 'S'.
     ELSE.
       MESSAGE lv_err_text TYPE 'E'.
     ENDIF.

* Close HTTP Connection
     lo_client->close( ).

   CATCH /goog/cx_sdk INTO DATA(lo_exception).
     MESSAGE lo_exception->get_text( ) TYPE 'E'.
 ENDTRY.

获取支持

如果您在解决 ABAP SDK for Google Cloud 问题时需要帮助，请执行以下操作：

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