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

從 REST API 讀取

註冊 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"
    }
)

篩選資料

您可以將篩選條件述詞下推至來源 REST API，以減少傳輸的資料量。REST API 連接器支援兩種篩選模式：

若要在您的 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 註冊中設定篩選行為。下表說明可用的屬性：

FilterStringConfiguration 屬性

下表說明 FILTER_STRING 模式的屬性：

BetweenConfiguration 屬性

下表說明 BETWEEN 處理屬性：

支援的運算子

篩選條件述詞中支援下列運算子：EQUAL_TO、GREATER_THAN、LESS_THANGREATER_THAN_OR_EQUAL_TO、LESS_THAN_OR_EQUAL_TO、NOT_EQUAL_TO、、CONTAINSBETWEEN、、AND、、OR、。

欄位層級覆寫

您可以在結構描述定義FilterOverrides中使用 來設定每個欄位篩選行為。可用的覆寫屬性如下：

範例：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"

分區查詢

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

Spark 任務參數

下列連線選項控制分割行為：

欄位型分區

以欄位為基礎的分割會根據指定的欄位將資料分割為範圍。下列範例會分割 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 個分割區，工作分配方式如下：

在 RegisterConnectionType 中設定分割區支援

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

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

分割區支援下列FieldDataType值：