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

# 連線中繼資料和預覽 API
<a name="aws-glue-api-catalog-connections-connections-metadata"></a>

下列連線 API 說明用於描述連線中繼資料的操作。

## 資料類型
<a name="aws-glue-api-catalog-connections-connections-metadata-objects"></a>
+ [實體結構](#aws-glue-api-catalog-connections-connections-metadata-Entity)
+ [欄位結構](#aws-glue-api-catalog-connections-connections-metadata-Field)

## 實體結構
<a name="aws-glue-api-catalog-connections-connections-metadata-Entity"></a>

所指定 `ConnectionType` 支援的實體。

**欄位**
+ `EntityName` – UTF-8 字串。

  實體的名稱。
+ `Label` – UTF-8 字串。

  用於實體的標籤。
+ `IsParentEntity` – 布林值。

  布林值，有助於判斷是否有可列出的子物件。
+ `Description` – UTF-8 字串。

  實體的描述。
+ `Category` – UTF-8 字串。

  回應中存在的實體類型。此值取決於來源連線。例如，這是 Salesforce 的 `SObjects`，及 Amazon Redshift 等來源的 `databases`、`schemas` 或 `tables`。
+ `CustomProperties` – 

  連接器可能為實體傳回的選用金鑰映射。

## 欄位結構
<a name="aws-glue-api-catalog-connections-connections-metadata-Field"></a>

`Field` 物件具有與連接器中欄位關聯的不同屬性的相關資訊。

**欄位**
+ `FieldName` – UTF-8 字串。

  欄位的唯一識別碼。
+ `Label` – UTF-8 字串。

  用於欄位的可讀取標籤。
+ `Description` – UTF-8 字串。

  欄位的描述。
+ `FieldType` – UTF-8 字串 (有效值：`INT` \| `SMALLINT` \| `BIGINT` \| `FLOAT` \| `LONG` \| `DATE` \| `BOOLEAN` \| `MAP` \| `ARRAY` \| `STRING` \| `TIMESTAMP` \| `DECIMAL` \| `BYTE` \| `SHORT` \| `DOUBLE` \| `STRUCT`)。

  欄位中的資料類型。
+ `IsPrimaryKey` – 布林值。

  指出此欄位是否可以用作所指定實體的主索引鍵。
+ `IsNullable` – 布林值。

  指出此欄位是否可為 null。
+ `IsRetrievable` – 布林值。

  指出是否可以在 SQL 查詢的 Select 子句中新增此欄位，或是否可以擷取。
+ `IsFilterable` – 布林值。

   指出此欄位是否可以在查詢資料時用於 SQL 陳述式的篩選條件子句 (`WHERE` 子句)。
+ `IsPartitionable` – 布林值。

  指出所指定欄位是否可用於分區對 SaaS 進行的查詢。
+ `IsCreateable` – 布林值。

  指示此欄位是否可以作為目的地寫入的一部分進行建立。
+ `IsUpdateable` – 布林值。

  指出此欄位是否可以作為目的地寫入的一部分進行更新。
+ `IsUpsertable` – 布林值。

  指出此欄位是否可以作為目的地寫入的一部分進行更新插入。
+ `IsDefaultOnCreate` – 布林值。

  指出此欄位是否在建立物件時自動填入，例如在時間戳記建立。
+ `SupportedValues` – .

  此欄位的支援值清單。
+ `SupportedFilterOperators` – UTF-8 字串陣列。

  指出此欄位的支援篩選條件運算子。
+ `CustomProperties` – 

  可傳回的選用金鑰映射。

## 作業
<a name="aws-glue-api-catalog-connections-connections-metadata-actions"></a>
+ [ListEntities 動作 (Python：list\_entities)](#aws-glue-api-catalog-connections-connections-metadata-ListEntities)
+ [DescribeEntity 動作 (Python：describe\_entity)](#aws-glue-api-catalog-connections-connections-metadata-DescribeEntity)
+ [GetEntityRecords 動作 (Python：get\_entity\_records)](#aws-glue-api-catalog-connections-connections-metadata-GetEntityRecords)

## ListEntities 動作 (Python：list\_entities)
<a name="aws-glue-api-catalog-connections-connections-metadata-ListEntities"></a>

傳回連線類型支援的可用實體。

**請求**
+ `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。這可以是 null，根據預設， AWS 帳戶 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\_entity)
<a name="aws-glue-api-catalog-connections-connections-metadata-DescribeEntity"></a>

提供有關與連線類型搭配使用的實體的詳細資訊，以及所選實體中每個欄位的資料模型描述。

 回應包含組成實體的所有欄位。

**請求**
+ `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。這可以是 null，根據預設， AWS 帳戶 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\_entity\_records)
<a name="aws-glue-api-catalog-connections-connections-metadata-GetEntityRecords"></a>

此 API 用於查詢來自指定連線類型或原生 Amazon S3 型 AWS Glue 資料目錄的預覽資料。

以 JSON Blob 陣列傳回記錄。每個記錄都會根據 `DescribeEntity` API 定義的欄位類型，使用 Jackson JsonNode 進行格式化。

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。這可以是 null，根據預設， AWS 帳戶 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，也不可以大於 1,000。

  限制透過請求擷取的記錄數目。
+ `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`