# 连接到 REST API
<a name="connecting-to-data-rest-api"></a>

 AWS Glue 允许您配置可用于将 AWS Glue 连接到任何基于 REST API 的数据来源的 AWS Glue ConnectionType。这可以用作 ETL 作业中的数据来源。您可以运行这些作业，在基于 REST API 的数据来源和 AWS 服务或其他受支持的应用程序之间传输数据。

**Topics**
+ [

# AWS Glue 支持 REST API
](rest-api-support.md)
+ [

# 包含用于注册连接类型和创建/使用连接的 API 操作的策略
](rest-api-configuring-iam-permissions.md)
+ [

# 配置 REST API ConnectionType
](rest-api-configuring.md)
+ [

# 配置 REST API 连接
](rest-api-configuring-connections.md)
+ [

# 教程：创建 REST API ConnectionType 和连接
](rest-api-example.md)
+ [

# 限制
](rest-api-limitations.md)

# AWS Glue 支持 REST API
<a name="rest-api-support"></a>

AWS Glue 支持 REST API，如下所示：

**是否支持作为来源？**  
可以。您可以使用 AWS Glue ETL 作业从基于 REST API 的数据来源查询数据。

**是否支持作为目标？**  
否。

# 包含用于注册连接类型和创建/使用连接的 API 操作的策略
<a name="rest-api-configuring-iam-permissions"></a>

 以下示例 IAM 策略描述了在 AWS Glue ETL 作业中注册、创建、管理和使用 REST API 连接所需的权限。如果您要创建新角色，请创建包含以下内容的策略：

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "glue:RegisterConnectionType",
                "glue:ListConnectionTypes",
                "glue:DescribeConnectionType",
                "glue:CreateConnection",
                "glue:RefreshOAuth2Tokens",
                "glue:ListEntities",
                "glue:DescribeEntity"
            ],
            "Resource": "*"
        }
    ]
}
```

您还可以使用以下 IAM 策略授予访问权限：
+ [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – 授予对各种 AWS Glue 进程代表您运行所需的资源的访问权限。这些资源包括 AWS Glue、Amazon S3、IAM、CloudWatch Logs 和 Amazon EC2。如果您遵循此策略中指定的资源的命名约定，则 AWS Glue 进程具有所需的权限。此策略通常附加到在定义爬网程序、作业和开发终端节点时指定的角色。
+ [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess)：当策略所附加到的身份使用 AWS 管理控制台时，授予对 AWS Glue 资源的完全访问权限。如果遵循此策略中指定的资源的命名约定，则用户具有完全控制台功能。此策略通常附加到 AWS Glue 控制台的用户。

如果在创建 REST API 连接时提供网络选项，则还必须在 IAM 角色中包含下面的操作：

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:DescribeSecret",
                "secretsmanager:GetSecretValue",
                "secretsmanager:PutSecretValue",
                "ec2:CreateNetworkInterface",
                "ec2:DescribeNetworkInterfaces",
                "ec2:DeleteNetworkInterface"
            ],
            "Resource": "*"
        }
    ]
}
```

# 配置 REST API ConnectionType
<a name="rest-api-configuring"></a>

 在使用 AWS Glue 从基于 REST API 的数据来源传输数据之前，您必须满足以下要求：

## 最低要求
<a name="rest-api-configuring-min-requirements"></a>

以下是最低要求：
+  您已配置并注册了 AWS Glue REST API 连接类型。请参阅[连接到 REST API](https://docs.aws.amazon.com/glue/latest/dg/rest-api-connections.html)。
+  如果使用 OAuth2 客户端凭证、授权码或者 JWT，请相应地配置客户端应用程序。

 如果满足这些要求，就可以将 AWS Glue 连接到基于 REST API 的数据来源。通常情况下，REST API 端不需要进行其他配置。

# 配置 REST API 连接
<a name="rest-api-configuring-connections"></a>

 要配置 AWS Glue REST API 连接器，您需要配置 AWS Glue 连接类型。此连接类型包含有关 REST 数据来源如何运行和解释身份验证、请求、响应、分页、验证和实体/元数据等属性的详细信息。有关 AWS Glue REST 连接类型所需属性的完整列表，请参阅 [RegisterConnectionType](https://docs.aws.amazon.com/glue/latest/webapi/API_DescribeConnectionType.html) API 和[连接到 REST API](https://docs.aws.amazon.com/glue/latest/dg/rest-api-connections.html) 的步骤。

 创建 REST API 连接器时，需要以下策略以允许相关操作：

```
{
    "Version":"2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "glue:RegisterConnectionType",
                "glue:ListConnectionTypes",
                "glue:DescribeConnectionType",
                "glue:CreateConnection",
                "secretsmanager:DescribeSecret",
                "secretsmanager:GetSecretValue",
                "secretsmanager:PutSecretValue",
                "ec2:CreateNetworkInterface",
                "ec2:DescribeNetworkInterfaces",
                "ec2:DeleteNetworkInterface"
            ],
            "Resource": "*"
        }
    ]
}
```

# 教程：创建 REST API ConnectionType 和连接
<a name="rest-api-example"></a>

**连接到 Foo REST API**

 我们将为 Foo REST API 创建 AWS Glue REST API 连接类型和相应的 AWS Glue 连接。此 API 具有下面的属性（可从 REST API 文档中检索）。
+  **实例 URL**：https://foo.cloud.com/rest/v1。
+  **身份验证类型**：OAuth2（客户端凭证）。
+  **REST 方法**：GET。
+  **分页类型**：在请求的查询参数中放置“limit”和“offset”属性的偏移量。
+ **支持的实体**：
  +  **Bar**：相对路径 [/bar.json]。
  +  **Baz**：相对路径 [/baz.json]。

 获得所有详细信息后，我们就可以开始创建与 Foo REST API 的 AWS Glue 连接了。

**要创建 REST API 连接，请执行下列操作**：

1.  使用 AWS API、CLI 或 SDK 调用 RegisterConnectionType API 来在 AWS Glue 中创建 REST API 连接类型。这将在 AWS Glue 中创建新的 ConnectionType 资源。

   ```
   {
       "ConnectionType": "REST-FOO-CONNECTOR",
       "IntegrationType": "REST",
       "Description": "AWS Glue Connection Type for the FOO REST API",
       "ConnectionProperties": {
           "Url": {
               "Name": "Url",
               "Required": true,
               "DefaultValue": "https://foo.cloud.com/rest/v1",
               "PropertyType": "USER_INPUT"
           }
       },
       "ConnectorAuthenticationConfiguration": {
           "AuthenticationTypes": ["OAUTH2"],
           "OAuth2Properties": {
               "OAuth2GrantType": "CLIENT_CREDENTIALS"
           }
       },
       "RestConfiguration": {
           "GlobalSourceConfiguration": {
           "RequestMethod": "GET",
           "ResponseConfiguration": {
               "ResultPath": "$.result",
               "ErrorPath": "$.error.message"
           },
           "PaginationConfiguration": {
               "OffsetConfiguration": {
                   "OffsetParameter": {
                       "Key": "offset",
                       "PropertyLocation": "QUERY_PARAM"
                   },
                   "LimitParameter": {
                       "Key": "limit",
                       "PropertyLocation": "QUERY_PARAM",
                       "DefaultValue": "50"
                   }
               }
           }
       },
       "ValidationEndpointConfiguration": {
           "RequestMethod": "GET",
           "RequestPath": "/bar.json?offset=1&limit=10"
       },
       "EntityConfigurations": {
           "bar": {
               "SourceConfiguration": {
                   "RequestMethod": "GET",
                   "RequestPath": "/bar.json",
                   "ResponseConfiguration": {
                       "ResultPath": "$.result",
                       "ErrorPath": "$.error.message"
                   }
               },
               "Schema": {
                   "name": {
                       "Name": "name",
                       "FieldDataType": "STRING"
                   },
                   "description": {
                       "Name": "description",
                       "FieldDataType": "STRING"
                   },
                   "id": {
                       "Name": "id",
                       "FieldDataType": "STRING"
                   },
                   "status": {
                       "Name": "status",
                       "FieldDataType": "STRING"
                   }
               }
           }
       }
   }
   }
   ```

1.  在 AWS Secrets Manager 中，创建密钥。密钥应包含关联应用程序的使用者密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
**注意**  
您必须在 AWS Glue 中为每个连接创建密钥

1.  使用 AWS API、CLI 或 SDK 调用 CreateConnection API 来创建 AWS Glue 连接。

   1.  将步骤 1 中的 REST 连接类型名称引用为“ConnectionType”。

   1.  提供 InstanceUrl 以及在 AWS Glue ConnectionType 注册过程中定义的任何其他 ConnectionProperties。

   1.  从配置的身份验证类型中进行选择。REST API Foo 使用授权类型为 ClientCredentials 的 OAuth2。

   1.  提供 **SecretArn** 和配置的其他 **AuthenticationProperties**。例如，我们已将 `OAUTH2` 配置为 AuthenticationType，因此我们将在 CreateConnectionInput 中设置“OAuth2Properties”。这将需要“OAuth2GrantType”、“TokenUrl”和“OAuth2ClientApplication”等属性。

1.  发出 CreateConnection 请求，这将创建 AWS Glue 连接。

   ```
   {
       "ConnectionInput": {
           "Name": "ConnectionFooREST",
           "ConnectionType": "REST-FOO-CONNECTOR",
           "ConnectionProperties": {},
           "ValidateCredentials": true,
           "AuthenticationConfiguration": {
               "AuthenticationType": "OAUTH2",
               "SecretArn": "arn:aws:secretsmanager:<region>:<accountId>:secret:<secretId>",
               "OAuth2Properties": {
                   "OAuth2GrantType": "CLIENT_CREDENTIALS",
                   "TokenUrl": "https://foo.cloud.com/oauth/token",
                   "OAuth2ClientApplication": {
                       "UserManagedClientApplicationClientId": "your-managed-client-id"
                   }
               }
           }
       }
   }
   ```

# 限制
<a name="rest-api-limitations"></a>

下面是 REST API 连接器的限制
+  REST API 连接器只能通过 AWS API、CLI 或者 SDK 使用。不能通过控制台配置 REST 连接器。
+  AWS Glue REST ConnectionType 只能配置为从基于 REST API 的数据来源读取数据。该连接只能用作 AWS Glue ETL 作业中的来源。
+  不支持筛选和分区。
+  不支持选择字段。