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

# 資料庫 API
<a name="aws-glue-api-catalog-databases"></a>

Database API 說明資料庫資料類型，以及用於建立、刪除、尋找、更新和列出資料庫的 API。

## 資料類型
<a name="aws-glue-api-catalog-databases-objects"></a>
+ [Database 結構](#aws-glue-api-catalog-databases-Database)
+ [DatabaseInput 結構](#aws-glue-api-catalog-databases-DatabaseInput)
+ [PrincipalPermissions 結構](#aws-glue-api-catalog-databases-PrincipalPermissions)
+ [DataLakePrincipal 結構](#aws-glue-api-catalog-databases-DataLakePrincipal)
+ [DatabaseIdentifier 結構](#aws-glue-api-catalog-databases-DatabaseIdentifier)
+ [FederatedDatabase 結構](#aws-glue-api-catalog-databases-FederatedDatabase)

## Database 結構
<a name="aws-glue-api-catalog-databases-Database"></a>

`Database` 物件代表了資料表的邏輯分組，這可能存放於 Hive 中繼存放區或 RDBMS。

**欄位**
+ `Name` – *必要：*UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，且需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  資料庫的名稱。為了相容於 Hive，它在存放時會折疊為小寫。
+ `Description` – 描述字串，長度不可超過 2048 個位元組，需符合[URI address multi-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-uri)。

  資料庫的描述。
+ `LocationUri` – 統一資源識別符 (uri)，長度不可小於 1 個位元組，也不可以超過 1024 個位元組，需符合[URI address multi-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-uri)。

  資料庫的位置 (例如 HDFS 路徑)。
+ `Parameters` – 金鑰值對的對應陣列。

  每個金鑰都是金鑰字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  每個值都是 UTF-8 字串，長度不可超過 512000 個位元組。

  這些金鑰值對會定義資料庫的參數和屬性。
+ `CreateTime` – 時間戳記。

  中繼資料資料庫在目錄中建立的時間。
+ `CreateTableDefaultPermissions` – 一個 [PrincipalPermissions](#aws-glue-api-catalog-databases-PrincipalPermissions) 物件陣列。

  為主體在資料表上建立一組預設許可。使用者 AWS Lake Formation。在正常 AWS Glue 的操作過程中不使用。
+ `TargetDatabase` – [DatabaseIdentifier](#aws-glue-api-catalog-databases-DatabaseIdentifier) 物件。

  描述資源連結的目標資料庫的 `DatabaseIdentifier` 結構。
+ `CatalogId` – 目錄 ID 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  資料庫存放所在 Data Catalog 的 ID。
+ `FederatedDatabase` – [FederatedDatabase](#aws-glue-api-catalog-databases-FederatedDatabase) 物件。

  參照 AWS Glue Data Catalog外部實體的 `FederatedDatabase` 結構。

## DatabaseInput 結構
<a name="aws-glue-api-catalog-databases-DatabaseInput"></a>

用於建立或更新資料庫的結構。

**欄位**
+ `Name` – *必要：*UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，且需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  資料庫的名稱。為了相容於 Hive，它在存放時會折疊為小寫。
+ `Description` – 描述字串，長度不可超過 2048 個位元組，需符合[URI address multi-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-uri)。

  資料庫的描述。
+ `LocationUri` – 統一資源識別符 (uri)，長度不可小於 1 個位元組，也不可以超過 1024 個位元組，需符合[URI address multi-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-uri)。

  資料庫的位置 (例如 HDFS 路徑)。
+ `Parameters` – 金鑰值對的對應陣列。

  每個金鑰都是金鑰字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  每個值都是 UTF-8 字串，長度不可超過 512000 個位元組。

  這些金鑰值對會定義資料庫的參數和屬性。

  這些金鑰值對會定義資料庫的參數和屬性。
+ `CreateTableDefaultPermissions` – 一個 [PrincipalPermissions](#aws-glue-api-catalog-databases-PrincipalPermissions) 物件陣列。

  為主體在資料表上建立一組預設許可。使用者 AWS Lake Formation。在正常 AWS Glue 的操作過程中不使用。
+ `TargetDatabase` – [DatabaseIdentifier](#aws-glue-api-catalog-databases-DatabaseIdentifier) 物件。

  描述資源連結的目標資料庫的 `DatabaseIdentifier` 結構。
+ `FederatedDatabase` – [FederatedDatabase](#aws-glue-api-catalog-databases-FederatedDatabase) 物件。

  參照 AWS Glue Data Catalog外部實體的 `FederatedDatabase` 結構。

## PrincipalPermissions 結構
<a name="aws-glue-api-catalog-databases-PrincipalPermissions"></a>

授予委託人的許可。

**欄位**
+ `Principal` – [DataLakePrincipal](#aws-glue-api-catalog-databases-DataLakePrincipal) 物件。

  獲授予許可的主體。
+ `Permissions` – UTF-8 字串陣列。

  授予主體的許可。

## DataLakePrincipal 結構
<a name="aws-glue-api-catalog-databases-DataLakePrincipal"></a>

 AWS Lake Formation 委託人。

**欄位**
+ `DataLakePrincipalIdentifier` – UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組。

   AWS Lake Formation 主體的識別符。

## DatabaseIdentifier 結構
<a name="aws-glue-api-catalog-databases-DatabaseIdentifier"></a>

描述資源連結的目標資料庫的結構。

**欄位**
+ `CatalogId` – 目錄 ID 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  資料庫存放所在 Data Catalog 的 ID。
+ `DatabaseName` – UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  目錄資料庫的名稱。
+ `Region` – UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  目標資料庫的區域。

## FederatedDatabase 結構
<a name="aws-glue-api-catalog-databases-FederatedDatabase"></a>

指向 AWS Glue Data Catalog外部實體的資料庫。

**欄位**
+ `Identifier` – UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 512 個位元組，且需符合 [Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  聯合資料庫的唯一識別碼。
+ `ConnectionName` – UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  連線到外部中繼存放區的名稱。
+ `ConnectionType` – UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  用於存取聯合資料庫的連線類型，例如 JDBC、ODBC 或其他支援的連線協定。

## 作業
<a name="aws-glue-api-catalog-databases-actions"></a>
+ [CreateDatabase 動作 (Python: create\$1database)](#aws-glue-api-catalog-databases-CreateDatabase)
+ [UpdateDatabase 動作 (Python: update\$1database)](#aws-glue-api-catalog-databases-UpdateDatabase)
+ [DeleteDatabase 動作 (Python: delete\$1database)](#aws-glue-api-catalog-databases-DeleteDatabase)
+ [GetDatabase 動作 (Python: get\$1database)](#aws-glue-api-catalog-databases-GetDatabase)
+ [GetDatabases 動作 (Python: get\$1databases)](#aws-glue-api-catalog-databases-GetDatabases)

## CreateDatabase 動作 (Python: create\$1database)
<a name="aws-glue-api-catalog-databases-CreateDatabase"></a>

在 Data Catalog 建立新的資料庫。

**請求**
+ `CatalogId` – 目錄 ID 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  用於建立資料庫的 Data Catalog 之 ID。如果未提供，預設會使用 AWS 帳戶 ID。
+ `DatabaseInput` – *必要：*[DatabaseInput](#aws-glue-api-catalog-databases-DatabaseInput) 物件。

  資料庫的中繼資料。
+ `Tags` – 金鑰值對的映射陣列，不超過 50 對。

  每個金鑰均為 UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 128 個位元組。

  每個值都是 UTF-8 字串，長度不可超過 256 個位元組。

  指派給資料庫的標籤。

**回應**
+ *無回應參數。*

**錯誤**
+ `InvalidInputException`
+ `AlreadyExistsException`
+ `ResourceNumberLimitExceededException`
+ `InternalServiceException`
+ `OperationTimeoutException`
+ `GlueEncryptionException`
+ `ConcurrentModificationException`
+ `FederatedResourceAlreadyExistsException`
+ `FederationSourceException`
+ `FederationSourceRetryableException`

## UpdateDatabase 動作 (Python: update\$1database)
<a name="aws-glue-api-catalog-databases-UpdateDatabase"></a>

更新 Data Catalog 中現有的資料庫定義。

**請求**
+ `CatalogId` – 目錄 ID 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  存放中繼資料資料庫的 Data Catalog 之 ID。如果未提供，預設會使用 AWS 帳戶 ID。
+ `Name` – *必要：*UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，且需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  目錄中要更新的資料庫之名稱。為了相容於 Hive，名稱必須轉換為小寫。
+ `DatabaseInput` – *必要：*[DatabaseInput](#aws-glue-api-catalog-databases-DatabaseInput) 物件。

  `DatabaseInput` 物件，可為目錄裡的中繼資料資料庫指定新定義。

**回應**
+ *無回應參數。*

**錯誤**
+ `EntityNotFoundException`
+ `InvalidInputException`
+ `InternalServiceException`
+ `OperationTimeoutException`
+ `GlueEncryptionException`
+ `ConcurrentModificationException`
+ `FederationSourceException`
+ `FederationSourceRetryableException`
+ `AlreadyExistsException`

## DeleteDatabase 動作 (Python: delete\$1database)
<a name="aws-glue-api-catalog-databases-DeleteDatabase"></a>

從 Data Catalog 移除指定的資料庫。

**注意**  
完成此操作後，您將無法再存取已刪除資料庫中的資料表 （以及可能屬於資料表的所有資料表版本和分割區） 和使用者定義的函數。 會由服務自行決定，以非同步方式及時 AWS Glue 刪除這些「孤立」資源。  
若要確保能夠立即刪除所有相關資源，請在呼叫 `DeleteDatabase` 之前，先使用 `DeleteTableVersion` 或 `BatchDeleteTableVersion`、`DeletePartition` 或 `BatchDeletePartition`、`DeleteUserDefinedFunction`，以及 `DeleteTable` 或 `BatchDeleteTable`，來刪除任何屬於資料庫的資源。

**請求**
+ `CatalogId` – 目錄 ID 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  資料庫存放所在 Data Catalog 的 ID。如果未提供，預設會使用 AWS 帳戶 ID。
+ `Name` – *必要：*UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，且需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  要刪除的資料庫之名稱。為了相容於 Hive，此項目必須完全使用小寫。

**回應**
+ *無回應參數。*

**錯誤**
+ `EntityNotFoundException`
+ `InvalidInputException`
+ `InternalServiceException`
+ `OperationTimeoutException`
+ `ConcurrentModificationException`
+ `FederationSourceException`
+ `FederationSourceRetryableException`

## GetDatabase 動作 (Python: get\$1database)
<a name="aws-glue-api-catalog-databases-GetDatabase"></a>

擷取指定資料庫的定義。

**請求**
+ `CatalogId` – 目錄 ID 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  資料庫存放所在 Data Catalog 的 ID。如果未提供，預設會使用 AWS 帳戶 ID。
+ `Name` – *必要：*UTF-8 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，且需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  要擷取的資料庫之名稱。為了相容於 Hive，名稱應完全小寫。

**回應**
+ `Database` – [資料庫](#aws-glue-api-catalog-databases-Database) 物件。

  Data Catalog 中所指定資料庫的定義。

**錯誤**
+ `InvalidInputException`
+ `EntityNotFoundException`
+ `InternalServiceException`
+ `OperationTimeoutException`
+ `GlueEncryptionException`
+ `FederationSourceException`
+ `FederationSourceRetryableException`

## GetDatabases 動作 (Python: get\$1databases)
<a name="aws-glue-api-catalog-databases-GetDatabases"></a>

擷取特定 Data Catalog 中所有已定義的資料庫。

**請求**
+ `CatalogId` – 目錄 ID 字串，長度不可小於 1 個位元組，也不可以超過 255 個位元組，需符合[Single-line string pattern](aws-glue-api-common.md#aws-glue-api-regex-oneLine)。

  用於擷取 `Databases` 的 Data Catalog 之 ID。如果未提供，預設會使用 AWS 帳戶 ID。
+ `NextToken` – UTF-8 字串。

  接續符記，如果這是接續呼叫。
+ `MaxResults` – 數字 (整數)，不可小於 1，也不可以大於 100。

  一次回應傳回資料庫的最大數量。
+ `ResourceShareType` – UTF-8 字串 (有效值：`FOREIGN` \$1 `ALL` \$1 `FEDERATED`)。

  可讓您指定要列出與帳戶共用的資料庫。允許的值為 `FEDERATED`、`FOREIGN` 或 `ALL`。
  + 如果設定為 `FEDERATED`，會列出與您的帳戶共用的聯合資料庫 (參照外部實體)。
  + 如果設定為 `FOREIGN`，會列出與您的帳戶共用的資料庫。
  + 如果設定為 `ALL`，將列出與您的帳戶共享的資料庫，以及您本機帳戶中的資料庫。
+ `AttributesToGet` – UTF-8 字串陣列。

  指定 `GetDatabases` 呼叫傳回的資料庫欄位。此參數不接受空白清單。請求必須包含 `NAME`。

**回應**
+ `DatabaseList` – *必要：*一個 [資料庫](#aws-glue-api-catalog-databases-Database) 物件。

  指定目錄中的 `Database` 物件清單。
+ `NextToken` – UTF-8 字串。

  為一種接續符記，用於將傳回的符記清單分頁，而如果清單目前的區段不是最後區段就會傳回。

**錯誤**
+ `InvalidInputException`
+ `InternalServiceException`
+ `OperationTimeoutException`
+ `GlueEncryptionException`
+ `EntityNotFoundException`
+ `FederationSourceException`
+ `FederationSourceRetryableException`