本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於 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 中原生表示的 null 字串的詳細資訊。
+ 服務定義之任何特定錯誤的例外類別。
+ 每個基本資料類型的資料元素。每個資料類型都有自己的資料元素，以便自我記錄。
+ 用於內部處理的其他物件，例如用於序列化和還原序列化 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' ). 
```

現在，`Bucket Location: assuming us-east-1`如果 `getbucketlocation()`的結果未傳回位置，程式將會寫入 。

如果請求的值完全遺失，您可以要求 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( )`方法，因為它將 null 字串視為空字串，並且是三個選項中最近似 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 類別。在某些情況下，開發套件也包含更高層級的函數，這些函數在 API 類別之上建置，以簡化特定操作。為了方便程式設計人員，包含更高層級的函數，且不會取代較低層級的 API 類別。

如果 SDK 包含模組的更高層級函數，則它們會包含在相同的傳輸中，並且可以透過稱為 的工廠類別存取`/AWS1/CL_TLA_L2_FACTORY`。工廠類別包含為模組建立各種更高層級用戶端的方法，這些用戶端會與 API [文件](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html)一起記錄於 API 的其餘部分。