本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 适用于 SAP ABAP 的 SDK 概念
<a name="concepts"></a>

本节涵盖的基本概念 适用于 SAP ABAP 的 AWS SDK。

**Topics**
+ [API 类](#api-classes)
+ [其他对象](#additional-objects)
+ [结构类](#structure-classes)
+ [数组](#arrays)
+ [映射](#maps)
+ [更高级别的函数](#higher-level-functions)

## API 类
<a name="api-classes"></a>

每个都分配了一个 AWS 服务 由三个字母组成的首字母缩略词或`TLA`。此服务由 `/AWS1/IF_<TLA>` 格式的接口表示。我们称之为服务接口。API 类在 `/AWS1/API_<TLA>` 软件包中。服务接口由每个 AWS 操作的一个方法组成（我们将这些方法称为操作方法）。要查看的完整模块列表 适用于 SAP ABAP 的 AWS SDK TLAs，请参阅 [适用于 SAP ABAP 的 AWS SDK -模块列表](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/tla.html)。

每种操作方法有多个 `IMPORTING` 参数，但最多只有一个 `RETURNING` 参数。这些参数通常会作为对象，具有复杂的构造函数和一套 `GET…()` 方法。在许多情况下，对象将包含嵌套对象、递归引用、对象表和表格等。这是因为传递 AWS 服务 的是深层的 XML 和 JSON 结构，这些结构不能用一组扁平的参数来表示。

`RETURNING`参数始终是一个类，即使该类只包含一个属性。

## 其他对象
<a name="additional-objects"></a>

每个 API 包中不仅有 API 主类，还有各种相关的存储库和数据字典对象。
+ 每个结构类型对象的类。
+ 表中出现的任意原始数据类型的类。例如，当服务返回字符串表时，ABAP API 会将其作为对象表，其中每个对象都是用来封装字符串的包装程序类。这样，包装程序类就能隐藏关于表示空字符串（无法在 ABAP 中进行本地表示）的详细信息。
+ 适用于服务定义的特定错误的异常类
+ 适用于每种原始数据类型的数据元素。每种数据类型都有数据元素，可自行记录。
+ 适用于内部处理的其他对象，例如对 XML 和 JSON 负载进行序列化和反序列化操作的 XSLT 转换。

## 结构类
<a name="structure-classes"></a>

服务发送和接收的大部分 AWS 数据都由 AWS SDK 表示为类。这些类代表了数据结构，同时也隐藏了存储内部的详细信息。这些类尤其会隐藏表示*此字段没有值*的 SDK 方式。

 一共有三种方法可应对结构类中的每个字段。

 **`GET_field( )`** 

`GET_field( )` 法 
+ 返回字段值，或者
+ 如果字段中没有值，则返回默认值，可设为可选参数。

例如，可以考虑以下打印存储桶位置限制的代码。

```
DATA(lo_location) = go_s3->getbucketlocation( iv_bucket = CONV string( gv_bucket ) ).
WRITE: / 'Bucket Location: ', 
   lo_location->get_locationconstraint( ). 
```

如果存储桶完全没有位置限制（如 `us-east-1`），则 `GET_LOCATIONCONSTRAINT( )` 将返回空字符串。如果字段中没有值，则可以覆盖此行为并指定所需值。

```
DATA(lo_location) = go_s3->getbucketlocation( iv_bucket = CONV string( gv_bucket ) ).
WRITE: / 'Bucket Location: ', 
   lo_location->get_locationconstraint( iv_value_if_missing = 'assuming us-east-1' ). 
```

如果 `getbucketlocation()` 未在结果中返回位置，则此程序将写入 `Bucket Location: assuming us-east-1`。

如果缺失请求值，请参阅以下代码示例，采用 GET( ) 法返回特定结果。

```
data(lo_location) = go_s3->GETBUCKETLOCATION(
   new /AWS1/CL_S3_GET_BUCKET_LOC_REQ( iv_bucket = gv_bucket )
).
write: / 'Location constraint: ', 
         lo_location->GET_LOCATIONCONSTRAINT( 'NopeNopeNope'  ).
```

此时，如果没有位置限制，`GET_LOCATIONCONSTRAINT( )` 将返回 `NopeNopeNope`。

 **`HAS_field( )`** 

`HAS_field( )` 法用于确定字段中是否存在值。请参阅以下示例。

```
if NOT lo_location->HAS_LOCATIONCONSTRAINT( ).
   write: / 'There is no location constraint'.
endif.
```

如果已知某个字段始终有值，则无需使用 `HAS_field( )` 法。

 **`ASK_field( )`** 

如果字段中没有值，则 `ASK_field( )` 法会返回值或引发异常。这种方法能够轻松处理大量字段，并在字段不含值时摆脱逻辑，采用其他方法。

```
TRY.
    WRITE: / 'Location constraint: ', lo_location->ask_locationconstraint( ).
CATCH /aws1/cx_rt_value_missing.
    WRITE: / 'Never mind, there is no location  constraint'.
ENDTRY.
```

请注意，`/AWS1/CX_RT_VALUE_MISSING` 是静态异常，如果不捕获此异常，就会收到警告。

 **最佳实践** 

通常可以采用 `GET_field( )` 法，将空字符串作为空白字符串，这也是三个选项中最接近 ABAP 的方法。但这种方法难以分辨字段到底是空白值还是没有值。如需通过区分缺失数据和空白数据来建立业务逻辑，则采用 `HAS` 法或 `ASK` 法。

## 数组
<a name="arrays"></a>

数组用 ABAP 标准对象表进行表示。

JSON 数组中可包含 NULL 值，如以下数组：`[‘cat’, ‘dog’, null, ‘horse’]`。这是稀疏数组。稀疏数组在 ABAP 中表示为对象引用的内部表，而 `null` 值在表中表示为 ABAP `null` 真实值。迭代稀疏表时，必须检查 `null` 值，以免接触 `null` 对象或产生 `CX_SY_REF_IS_INITIAL` 异常。 AWS 服务中其实很少出现稀疏数组。

使用 ABAP 7.40 新构造可以轻松初始化对象数组。以此次启动一个分配了多个安全组的 Amazon EC2 实例为例：

```
ao_ec2->runinstances(
    iv_imageid                   = lo_latest_ami->get_imageid( )
    iv_instancetype              = 't2.micro'
    iv_maxcount                  = 1
    iv_mincount                  = 1
    it_securitygroupids          = VALUE /aws1/cl_ec2secgrpidstrlist_w=>tt_securitygroupidstringlist(
                                    ( NEW /aws1/cl_ec2secgrpidstrlist_w( 'sg-12345678' ) )
                                    ( NEW /aws1/cl_ec2secgrpidstrlist_w( 'sg-55555555' ) )
                                    ( NEW /aws1/cl_ec2secgrpidstrlist_w( 'sg-99999999' ) )                                                                        
                                )
    iv_subnetid                  = ao_snet->get_subnetid( )
    it_tagspecifications         = make_tag_spec( 'instance' )
)
```

## 映射
<a name="maps"></a>

JSON 映射在 ABAP 中表示为 `Hashed Tables`，其中每个表行都只有两个组件。
+  `KEY`：表中的 `UNIQUE KEY` 字符串。
+  `VALUE`：含值对象。

映射是 AWS SDK 使用真实结构而不是类的极少数案例之一。这是必要的，因为 ABAP 哈希表不能将对象引用作为键字段，而且 AWS 映射键始终是非空字符串。

## 更高级别的函数
<a name="higher-level-functions"></a>

上一节中[API 类](#api-classes)描述的完全反映了该 AWS 服务， APIs 并将它们表示 APIs 为熟悉的 ABAP 类。在某些情况下，SDK 还包括更高级别的函数，这些函数在 API 类之上构建，以简化某些操作。为了方便程序员而包含更高级别的函数，并且不会取代较低级别的 API 类。

如果 SDK 包含模块的更高级别的函数，则它们包含在同一个传输中，并且可以通过名为的工厂类进行访问`/AWS1/CL_TLA_L2_FACTORY`。工厂类包括为模块创建各种更高级别的客户端的方法，这些客户端与 API [文档](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html)中的 API 的其余部分一起记录在案。