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

# 連線至 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 和 Connection](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>

 您必須先符合下列要求，才能使用 從 REST API 型資料來源 AWS Glue 傳輸資料：

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

以下是最低需求：
+  您已設定並註冊 AWS Glue REST API 連線類型。請參閱[連線至 REST APIs](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 APIs](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 和 Connection
<a name="rest-api-example"></a>

**連線至 Foo REST API**

 我們將為 Foo AWS Glue REST API 建立 REST API ConnectionType 和對應的 AWS Glue 連線。此 API 具有下列屬性 （可從 REST API 文件擷取）。
+  **執行個體 URL**：https：//https://foo.cloud.com/rest/v1。
+  **身分驗證類型**：OAuth2 （用戶端登入資料）。
+  **REST 方法**：GET。
+  **分頁類型**：在請求的查詢參數中放置屬性 "limit" 和 "offset" 的位移。
+ **支援的實體**：
  +  **長條**：相對路徑 【/bar.json】。
  +  **Baz**：相對路徑 【/baz.json】。

 取得所有詳細資訊後，我們可以開始建立與 Foo REST API 的 AWS Glue 連線。

**若要建立 REST API 連線**：

1.  使用 API、CLI 或 SDK 呼叫 RegisterConnectionType API， AWS Glue 在 中建立 REST AWS API 連線類型。這將在 中建立新的 ConnectionType 資源 AWS Glue。

   ```
   {
       "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.  使用 API、CLI 或 SDK 呼叫 CreateConnection AWS API 來建立 AWS Glue 連線。

   1.  參考步驟 1 中的 REST 連線類型名稱做為「ConnectionType」。

   1.  提供 InstanceUrl 和在 ConnectionType 註冊程序期間定義的任何其他 ConnectionProperties。 AWS Glue ConnectionType 

   1.  從設定的身分驗證類型中選擇。REST API Foo 使用 OAuth2 搭配 ClientCredentials 授予類型。

   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 任務中用作 SOURCE。
+  不支援篩選和分割。
+  不支援欄位選擇。