# 连接元数据和预览 API
连接元数据

以下连接 API 介绍了用于描述连接元数据的操作。

## 数据类型
 —  数据类型  —
+ [元数据](#aws-glue-api-catalog-connections-connections-metadata-Entity)
+ [字段结构](#aws-glue-api-catalog-connections-connections-metadata-Field)

## 元数据
实体

给定 `ConnectionType` 支持的实体。

**Fields**
+ `EntityName` – UTF-8 字符串。

  在 中，将实体命名为 。
+ `Label` – UTF-8 字符串。

  用于实体的标签。
+ `IsParentEntity` – 布尔值。

  一个布尔值，有助于确定是否有可以列出的子对象。
+ `Description` – UTF-8 字符串。

  实体的描述。
+ `Category` – UTF-8 字符串。

  响应中存在的实体的类型。此值取决于源连接。例如，对于 Salesforce，这为 `SObjects`，对于 Amazon Redshift 等来源，这为 `databases`、`schemas` 或 `tables`。
+ `CustomProperties` – 

  连接器可为实体返回的可选键映射。

## 字段结构
字段

`Field` 对象包含与连接器中的某字段关联的不同属性的信息。

**Fields**
+ `FieldName` – UTF-8 字符串。

  字段的唯一标识符。
+ `Label` – UTF-8 字符串。

  用于该字段的可读标签。
+ `Description` – UTF-8 字符串。

  字段的描述。
+ `FieldType`：UTF-8 字符串（有效值：`INT` \$1 `SMALLINT` \$1 `BIGINT` \$1 `FLOAT` \$1 `LONG` \$1 `DATE` \$1 `BOOLEAN` \$1 `MAP` \$1 `ARRAY` \$1 `STRING` \$1 `TIMESTAMP` \$1 `DECIMAL` \$1 `BYTE` \$1 `SHORT` \$1 `DOUBLE` \$1 `STRUCT`）。

  字段中的数据类型。
+ `IsPrimaryKey` – 布尔值。

  指示此字段是否可用作给定实体的主键。
+ `IsNullable` – 布尔值。

  指示此字段是否可以为空。
+ `IsRetrievable` – 布尔值。

  指示此字段是否可以添加到 SQL 查询的 Select 子句中或者是否可以检索。
+ `IsFilterable` – 布尔值。

   指示在查询数据时是否可以在 SQL 语句的筛选条件子句（`WHERE` 子句）中使用此字段。
+ `IsPartitionable` – 布尔值。

  指示是否可以使用给定字段对向 SaaS 进行的查询进行分区。
+ `IsCreateable` – 布尔值。

  指示此字段是否可以作为目标写入的一部分创建。
+ `IsUpdateable` – 布尔值。

  指示此字段是否可以作为目标写入的一部分更新。
+ `IsUpsertable` – 布尔值。

  指示此字段是否可以作为目标写入的一部分更新插入。
+ `IsDefaultOnCreate` – 布尔值。

  指示在创建对象时（例如在时间戳时创建的）是否自动填充此字段。
+ `SupportedValues` – .

  该字段支持的值的列表。
+ `SupportedFilterOperators` – UTF-8 字符串数组。

  指示此字段的支持筛选运算符。
+ `CustomProperties` – 

  可能返回的可选键映射。

## 操作
 —  操作  —
+ [ListEntities 操作（Python：list\$1entities）](#aws-glue-api-catalog-connections-connections-metadata-ListEntities)
+ [DescribeEntity 操作（Python：describe\$1entity)](#aws-glue-api-catalog-connections-connections-metadata-DescribeEntity)
+ [GetEntityRecords 操作（Python：get\$1entity\$1records）](#aws-glue-api-catalog-connections-connections-metadata-GetEntityRecords)

## ListEntities 操作（Python：list\$1entities）
ListEntities (list\$1entities)

返回连接类型支持的可用实体。

**请求**
+ `ConnectionName` – UTF-8 字符串，长度不少于 1 个字节或超过 255 个字节，与 [Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine) 匹配。

  具有查询任何连接类型所需凭证的连接的名称。
+ `CatalogId` – 目录 id 字符串，长度不少于 1 个字节或超过 255 个字节，与 [Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine) 匹配。

  包含连接的目录的目录 ID。这可以为空，默认情况下，Amazon 账户 ID 就是目录 ID。
+ `ParentEntityName` – UTF-8 字符串。

  您想要列出子项的父实体的名称。此参数采用实体的完全限定路径来列出子实体。
+ `NextToken` – UTF-8 字符串，不少于 1 个字节或超过 2048 个字节，与 [Custom string pattern #11](aws-glue-api-common.md#regex_11) 匹配。

  延续标记 (如果这是延续调用，则包括)。
+ `DataStoreApiVersion` – UTF-8 字符串，长度不少于 1 个字节或超过 256 个字节，与 [Custom string pattern #23](aws-glue-api-common.md#regex_23) 匹配。

  SaaS 连接器的 API 版本。

**响应**
+ `Entities` – [实体](#aws-glue-api-catalog-connections-connections-metadata-Entity) 对象的数组。

  `Entity` 对象的列表。
+ `NextToken` – UTF-8 字符串，不少于 1 个字节或超过 2048 个字节，与 [Custom string pattern #11](aws-glue-api-common.md#regex_11) 匹配。

  延续令牌，如果当前片段不是最后一个片段则呈现。

**错误**
+ `EntityNotFoundException`
+ `OperationTimeoutException`
+ `InvalidInputException`
+ `GlueEncryptionException`
+ `ValidationException`
+ `FederationSourceException`
+ `AccessDeniedException`

## DescribeEntity 操作（Python：describe\$1entity)
DescribeEntity (describe\$1entity)

提供有关连接类型所使用的实体的详细信息以及所选实体中每个字段的数据模型的描述。

 响应包括构成实体的所有字段。

**请求**
+ `ConnectionName` – *必填：*UTF-8 字符串，长度不少于 1 个字节或超过 255 个字节，与 [Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine) 匹配。

  包含连接类型凭证的连接的名称。
+ `CatalogId` – 目录 id 字符串，长度不少于 1 个字节或超过 255 个字节，与 [Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine) 匹配。

  包含连接的目录的目录 ID。这可以为空，默认情况下，Amazon 账户 ID 就是目录 ID。
+ `EntityName` – *必填：*UTF-8 字符串。

  您想要从连接类型描述的实体的名称。
+ `NextToken` – UTF-8 字符串，不少于 1 个字节或超过 2048 个字节，与 [Custom string pattern #11](aws-glue-api-common.md#regex_11) 匹配。

  延续标记 (如果这是延续调用，则包括)。
+ `DataStoreApiVersion` – UTF-8 字符串，长度不少于 1 个字节或超过 256 个字节，与 [Custom string pattern #23](aws-glue-api-common.md#regex_23) 匹配。

  用于数据存储的 API 版本。

**响应**
+ `Fields` – [字段](#aws-glue-api-catalog-connections-connections-metadata-Field) 对象的数组。

  描述该连接器实体的字段。这是 `Field` 对象的列表。`Field` 与数据库中的列非常相似。`Field` 对象包含与连接器中的字段关联的不同属性的信息。
+ `NextToken` – UTF-8 字符串，不少于 1 个字节或超过 2048 个字节，与 [Custom string pattern #11](aws-glue-api-common.md#regex_11) 匹配。

  延续令牌，如果当前片段不是最后一个片段则呈现。

**错误**
+ `EntityNotFoundException`
+ `OperationTimeoutException`
+ `InvalidInputException`
+ `GlueEncryptionException`
+ `ValidationException`
+ `FederationSourceException`
+ `AccessDeniedException`

## GetEntityRecords 操作（Python：get\$1entity\$1records）
GetEntityRecords (get\$1entity\$1records)

此 API 用于从给定的连接类型或基于 Amazon S3 的原生 Amazon Glue Data Catalog 查询预览数据。

以 JSON blob 数组的形式返回记录。每条记录都使用 Jackson JsonNode 根据 `DescribeEntity` API 定义的字段类型进行格式化。

Spark 连接器根据与 `DescribeEntity` API 中相同的数据类型映射生成架构。Spark 连接器在返回行时会将数据转换为与架构匹配的适当数据类型。

**请求**
+ `ConnectionName` – UTF-8 字符串，长度不少于 1 个字节或超过 255 个字节，与 [Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine) 匹配。

  包含连接类型凭证的连接的名称。
+ `CatalogId` – 目录 id 字符串，长度不少于 1 个字节或超过 255 个字节，与 [Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine) 匹配。

  包含连接的目录的目录 ID。这可以为空，默认情况下，Amazon 账户 ID 就是目录 ID。
+ `EntityName` – *必填：*UTF-8 字符串。

  我们想要从给定的连接类型查询预览数据的实体的名称。
+ `NextToken` – UTF-8 字符串，不少于 1 个字节或超过 2048 个字节，与 [Custom string pattern #11](aws-glue-api-common.md#regex_11) 匹配。

  延续标记 (如果这是延续调用，则包括)。
+ `DataStoreApiVersion` – UTF-8 字符串，长度不少于 1 个字节或超过 256 个字节，与 [Custom string pattern #23](aws-glue-api-common.md#regex_23) 匹配。

  SaaS 连接器的 API 版本。
+ `ConnectionOptions` – 键值对的映射数组，不超过 100 对。

  每个键是一个 UTF-8 字符串，长度不少于 1 个字节，不超过 256 个字节，与 [Custom string pattern #18](aws-glue-api-common.md#regex_18) 匹配。

  每个值是一个 UTF-8 字符串，长度不少于 1 个字节，不超过 256 个字节，与 [Custom string pattern #17](aws-glue-api-common.md#regex_17) 匹配。

  查询数据所需的连接器选项。
+ `FilterPredicate`：UTF-8 字符串，长度不少于 1 个字节，不超过 100000 个字节。

  您可以在查询请求中应用的筛选谓词。
+ `Limit`：*必需：*数字（长度），不少于 1 或不超过 1000。

  限制通过请求提取的记录数。
+ `SelectedFields`：UTF-8 字符串数组，不少于 1 个字符串，不超过 1000 个字符串。

   我们想要作为预览数据的一部分提取的字段列表。

**响应**
+ `Records` – 结构数组。

  请求的 对象的列表。
+ `NextToken` – UTF-8 字符串，不少于 1 个字节或超过 2048 个字节，与 [Custom string pattern #11](aws-glue-api-common.md#regex_11) 匹配。

  延续令牌，如果当前片段不是最后一个片段则呈现。

**错误**
+ `EntityNotFoundException`
+ `OperationTimeoutException`
+ `InvalidInputException`
+ `GlueEncryptionException`
+ `ValidationException`
+ `FederationSourceException`
+ `AccessDeniedException`