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

# 從 REST API 讀取
<a name="rest-api-reading"></a>

 註冊 REST API ConnectionType 並建立 AWS Glue 連線後，您可以從 AWS Glue ETL 任務中的 REST API 讀取資料。透過此連線，您可以處理外部 REST API 資料以及相同任務中的其他來源。您需要連線名稱和實體名稱才能讀取資料。

下列範例示範如何使用 Python 從 REST API 資料來源讀取：

```
rest_read = glueContext.create_dynamic_frame.from_options(
    connection_type="rest",
    connection_options={
        "connectionName": "{{connection-name}}",
        "ENTITY_NAME": "{{entity-name}}",
        "CONNECTION_TYPE": "{{REST-connection-type}}"
    }
)
```

## 篩選資料
<a name="rest-api-filtering"></a>

 您可以將篩選條件述詞下推至來源 REST API，以減少傳輸的資料量。REST API 連接器支援兩種篩選模式：
+ **QUERY\_PARAMS** – 每個篩選條件都會成為個別的 URL 查詢參數。例如：`?created[gte]=1704067200&created[lte]=1717200000`
+ **FILTER\_STRING** – 所有篩選條件合併為單一查詢參數。例如：`?search=status eq "ACTIVE" and lastUpdated gt "2024-01-01"`

 若要在您的 AWS Glue ETL 任務中套用篩選條件述詞，請使用 `FILTER_PREDICATE` 連線選項：

```
rest_read = glueContext.create_dynamic_frame.from_options(
    connection_type="rest",
    connection_options={
        "connectionName": "{{connection-name}}",
        "ENTITY_NAME": "{{entity-name}}",
        "CONNECTION_TYPE": "{{REST-connection-type}}",
        "FILTER_PREDICATE": "status = \"ACTIVE\" AND lastUpdated >= \"2024-01-01T00:00:00.000Z\""
    }
)
```

**FilterConfiguration 屬性**  
 使用 `FilterConfiguration` 物件在 ConnectionType 註冊中設定篩選行為。下表說明可用的屬性：


| 屬性 | Type | Description | 
| --- | --- | --- | 
| `FilterMode` | String | 必要。 `QUERY_PARAMS` 或 `FILTER_STRING`。 | 
| `OperatorMappings` | Map | 將邏輯運算子映射至 API 特定的語法。 | 
| `DateTimeFormat` | String | DateTime 格式模式或 `EPOCH_SECONDS`/`EPOCH_MILLIS`。 | 
| `StripQuotes` | Boolean | 指定是否從輸入值分割周圍的引號。預設：`true`。 | 
| `BetweenConfiguration` | 物件 | 預設 BETWEEN 處理組態。 | 
| `FilterStringConfiguration` | 物件 | `FILTER_STRING` 模式特定的設定。 | 

**FilterStringConfiguration 屬性**  
下表說明 `FILTER_STRING` 模式的屬性：


| 屬性 | Type | Description | 
| --- | --- | --- | 
| `FilterStringKey` | String | 必要. 查詢參數索引鍵 （例如 "search" 或 "filter")。 | 
| `QuoteStringValues` | Boolean | 指定是否要以引號包裝字串和 DateTime 值。 | 
| `QuoteCharacter` | String | 引號字元。預設：`"` | 

**BetweenConfiguration 屬性**  
下表說明 BETWEEN 處理屬性：


| 屬性 | Mode | 說明 | 
| --- | --- | --- | 
| `LowBoundKey` | QUERY\_PARAMS | 低界限的金鑰範本。支援`{FIELD}`預留位置。 | 
| `HighBoundKey` | QUERY\_PARAMS | 高界限的金鑰範本。省略 以捨棄高邊界。 | 
| `Template` | FILTER\_STRING | 具有 `{FIELD}`、`{LOW}`、 `{HIGH}` 預留位置的範本。 | 

**支援的運算子**  
 篩選條件述詞中支援下列運算子：`EQUAL_TO`、`GREATER_THAN`、`LESS_THAN``GREATER_THAN_OR_EQUAL_TO`、`LESS_THAN_OR_EQUAL_TO`、`NOT_EQUAL_TO`、、`CONTAINS``BETWEEN`、、`AND`、、`OR`、。

**欄位層級覆寫**  
 您可以在結構描述定義`FilterOverrides`中使用 來設定每個欄位篩選行為。可用的覆寫屬性如下：
+ `FieldName` – 覆寫篩選條件輸出中使用的欄位名稱。
+ `OperatorMappings` – 欄位層級運算子覆寫。
+ `BetweenConfiguration` – 每個欄位間隔覆寫。
+ `DateTimeFormat` – 每個欄位的 DateTime 格式覆寫。

**範例：QUERY\_PARAMS 模式**  
 下列範例顯示 REST API `FilterConfiguration` 的 ，該 API 使用查詢參數搭配 運算子的括號標記法，以及日期值的 epoch 時間戳記：

```
"FilterConfiguration": {
    "FilterMode": "QUERY_PARAMS",
    "OperatorMappings": {
        "EQUAL_TO": "{FIELD}",
        "GREATER_THAN_OR_EQUAL_TO": "{FIELD}[gte]",
        "LESS_THAN_OR_EQUAL_TO": "{FIELD}[lte]"
    },
    "DateTimeFormat": "EPOCH_SECONDS",
    "BetweenConfiguration": {
        "LowBoundKey": "{FIELD}[gte]",
        "HighBoundKey": "{FIELD}[lte]"
    }
}
```

 使用此組態， 的輸入篩選條件`created >= 2024-01-01 AND created <= 2024-06-01`會產生 URL 查詢字串： `?created[gte]=1704067200&created[lte]=1717200000`

**範例：FILTER\_STRING 模式**  
 下列範例顯示 REST API `FilterConfiguration`的 ，該 API 使用單一篩選字串參數搭配空格填充運算子：

```
"FilterConfiguration": {
    "FilterMode": "FILTER_STRING",
    "OperatorMappings": {
        "EQUAL_TO": " eq ",
        "GREATER_THAN": " gt ",
        "GREATER_THAN_OR_EQUAL_TO": " ge ",
        "LESS_THAN": " lt ",
        "AND": " and ",
        "OR": " or "
    },
    "DateTimeFormat": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "BetweenConfiguration": {
        "Template": "{FIELD} ge {LOW} and {FIELD} le {HIGH}"
    },
    "FilterStringConfiguration": {
        "FilterStringKey": "search",
        "QuoteStringValues": true,
        "QuoteCharacter": "\""
    }
}
```

 使用此組態， 的輸入篩選條件`status = "ACTIVE" AND lastUpdated > 2024-01-01T00:00:00.000Z`會產生 URL 查詢字串： `?search=status eq "ACTIVE" and lastUpdated gt "2024-01-01T00:00:00.000Z"`

## 分區查詢
<a name="rest-api-partitioning"></a>

 您可以將資料讀取分割為跨Spark工作者的平行分割區，以改善輸送量。REST API 連接器支援以欄位為基礎的分割，這會根據指定的欄位將資料分割為範圍。

**Spark 任務參數**  
下列連線選項控制分割行為：
+ `PARTITION_FIELD` – 要分割的欄位。必須在結構描述`IsPartitionable: true`中標記。
+ `LOWER_BOUND` – 包含分割區範圍的下限。
+ `UPPER_BOUND` – 分割區範圍的上限。中繼分割區會排除此值。最後一個分割區包含它。
+ `NUM_PARTITIONS` – 平行分割區的數量。

**欄位型分區**  
 以欄位為基礎的分割會根據指定的欄位將資料分割為範圍。下列範例會分割 `lastUpdated` 欄位上的資料：

```
rest_read = glueContext.create_dynamic_frame.from_options(
    connection_type="rest",
    connection_options={
        "connectionName": "{{connection-name}}",
        "ENTITY_NAME": "{{entity-name}}",
        "CONNECTION_TYPE": "{{REST-connection-type}}",
        "PARTITION_FIELD": "lastUpdated",
        "LOWER_BOUND": "2024-01-01T00:00:00.000Z",
        "UPPER_BOUND": "2024-12-31T00:00:00.000Z",
        "NUM_PARTITIONS": "4"
    }
)
```

使用 `lastUpdated` 欄位上的 4 個分割區，工作分配方式如下：
+ 工作者 1： `lastUpdated >= "2024-01-01" AND lastUpdated < "2024-04-01"`
+ 工作者 2： `lastUpdated >= "2024-04-01" AND lastUpdated < "2024-07-01"`
+ 工作者 3： `lastUpdated >= "2024-07-01" AND lastUpdated < "2024-10-01"`
+ 工作者 4： `lastUpdated >= "2024-10-01" AND lastUpdated <= "2024-12-31"`

**在 RegisterConnectionType 中設定分割區支援**  
 若要啟用欄位型分割，請在結構描述定義中將欄位標記為可分割：

```
"Schema": {
    "lastUpdated": {
        "FieldDataType": "TIMESTAMP",
        "IsPartitionable": true
    }
}
```

分割區支援下列`FieldDataType`值：
+ `TIMESTAMP` – DateTime 分割。將範圍分割為時段。
+ `INTEGER` – 整數分割。將範圍分割為數值視窗。

**注意**  
 連接器使用 AND 結合分割區篩選條件與使用者篩選條件。如果您的篩選條件包含 LIMIT 子句，連接器會略過分割。如果分割區產生失敗，連接器會回到單一分割區，且任務仍然完成。