# 接続メタデータとプレビュー 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` \$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` – ブール。

  このフィールドを null にできるかどうかを示します。
+ `IsRetrievable` – ブール。

  このフィールドを SQL クエリの Select 句に追加できるかどうか、または取得可能かどうかを示します。
+ `IsFilterable` – ブール。

   データをクエリするときに、このフィールドを SQL ステートメントのフィルター句 (`WHERE` 句) で使用できるかどうかを示します。
+ `IsPartitionable` – ブール。

  特定のフィールドを SaaS に対して行われたクエリのパーティション化に使用できるかどうかを示します。
+ `IsCreateable` – ブール。

  このフィールドを送信先書き込みの一部として作成できるかどうかを示します。
+ `IsUpdateable` – ブール。

  このフィールドを送信先書き込みの一部として更新できるかどうかを示します。
+ `IsUpsertable` – ブール。

  このフィールドを送信先書き込みの一部として upsert できるかどうかを示します。
+ `IsDefaultOnCreate` – ブール。

  オブジェクトの作成時にこのフィールドが自動的に入力されるかどうかを示します ([作成時刻] のタイムスタンプなど)。
+ `SupportedValues` – .

  フィールドのサポートされている値のリスト。
+ `SupportedFilterOperators` – UTF-8 文字列の配列。

  このフィールドのサポートされているフィルター演算子を示します。
+ `CustomProperties` – 

  返される可能性のあるキーのオプションのマップ。

## 操作
<a name="aws-glue-api-catalog-connections-connections-metadata-actions"></a>
+ [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)
<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 ～ 2,048 バイト長。[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 ～ 2,048 バイト長。[Custom string pattern #11](aws-glue-api-common.md#regex_11) に一致。

  継続トークン (現在のセグメントが最後ではない場合に表示されます)。

**エラー**
+ `EntityNotFoundException`
+ `OperationTimeoutException`
+ `InvalidInputException`
+ `GlueEncryptionException`
+ `ValidationException`
+ `FederationSourceException`
+ `AccessDeniedException`

## DescribeEntity アクション (Python: describe\$1entity)
<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 ～ 2,048 バイト長。[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 ～ 2,048 バイト長。[Custom string pattern #11](aws-glue-api-common.md#regex_11) に一致。

  継続トークン (現在のセグメントが最後ではない場合に表示されます)。

**エラー**
+ `EntityNotFoundException`
+ `OperationTimeoutException`
+ `InvalidInputException`
+ `GlueEncryptionException`
+ `ValidationException`
+ `FederationSourceException`
+ `AccessDeniedException`

## GetEntityRecords アクション (Python: get\$1entity\$1records)
<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 ～ 2,048 バイト長。[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 ～ 2,048 バイト長。[Custom string pattern #11](aws-glue-api-common.md#regex_11) に一致。

  継続トークン (現在のセグメントが最後ではない場合に表示されます)。

**エラー**
+ `EntityNotFoundException`
+ `OperationTimeoutException`
+ `InvalidInputException`
+ `GlueEncryptionException`
+ `ValidationException`
+ `FederationSourceException`
+ `AccessDeniedException`