本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon Keyspaces 中使用者定義的類型 (UDT)
使用者定義類型 (UDT) 是欄位和資料類型的群組，可用於在 Amazon Keyspaces 中定義單一資料欄。UDTs的有效資料類型都是支援的 Cassandra 資料類型，包括您已在相同金鑰空間中建立的集合和其他 UDTs。如需支援的 Cassandra 資料類型的詳細資訊，請參閱 [Cassandra 資料類型支援](cassandra-apis.md#cassandra-data-type)。
您可以在 Amazon Keyspaces 中使用使用者定義類型 (UDTs)，以更有效率的方式組織資料。例如，您可以使用巢狀集合建立 UDTs，以便在應用程式中實作更複雜的資料建模。您也可以使用凍結關鍵字來定義 UDTs。
UDTs 繫結至金鑰空間，並可供相同金鑰空間中的所有資料表和 UDTs 使用。您可以在單一區域和多區域金鑰空間中建立 UDTs。
您可以建立新的資料表或修改現有的資料表，並新增使用 UDT 的新資料欄。若要使用巢狀 UDT 建立 UDT，必須將巢狀 UDT 凍結。
若要檢閱每個金鑰空間支援多少 UDTs、支援的巢狀層級，以及與 UDTs 相關的其他預設值和配額，請參閱 [Amazon Keyspaces 中使用者定義類型 (UDTs) 的配額和預設值](quotas.md#quotas-udts)。
如需如何計算 UDTs 編碼大小的資訊，請參閱 [根據資料類型估計資料值的編碼大小](calculating-row-size.md#calculating-row-size-data-types)。
如需 CQL 語法的詳細資訊，請參閱 [使用者定義的類型 (UDTs)](cql.ddl.type.md)。
若要進一步了解 UDTs和時間點還原，請參閱 [使用使用者定義類型 (UDTs) 還原資料表的 PITR](PointInTimeRecovery_HowItWorks.md#howitworks_backup_udt)。
**Topics**
+ [設定 許可](configure-udt-permissions.md)
+ [建立 UDT](keyspaces-create-udt.md)
+ [檢視 UDTs](keyspaces-view-udt.md)
+ [刪除 UDT](keyspaces-delete-udt.md)
# 設定許可以在 Amazon Keyspaces 中使用使用者定義類型 (UDTs)
如同資料表，UDTs 會繫結至特定金鑰空間。但與資料表不同，您無法直接定義 UDTs許可。UDTs不會被視為 中的資源 AWS ，而且它們沒有 Amazon Resource Name (ARN) 格式的唯一識別符。相反地，若要授予 IAM 主體在 UDT 上執行特定動作的許可，您必須定義 UDT 所繫結之金鑰空間的許可。若要在多區域金鑰空間中使用 UDTs，需要額外許可。
若要能夠建立、檢視或刪除 UDTs，委託人，例如 IAM 使用者或角色，需要對 UDT 繫結的金鑰空間執行相同動作所需的相同許可。
如需 的詳細資訊 AWS Identity and Access Management，請參閱 [AWS Identity and Access Management 適用於 Amazon Keyspaces](security-iam.md)。
## 建立 UDT 的許可
若要在單一區域金鑰空間中建立 UDT，委託人需要金鑰空間的`Create`許可。
下列 IAM 政策為範例。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "cassandra:Create",
"Resource": [
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
]
}
]
}
```
若要在多區域金鑰空間中建立 UDT，除了`Create`許可之外，委託人還需要指定金鑰空間之 動作`CreateMultiRegionResource`的許可。
下列 IAM 政策為範例。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [ "cassandra:Create", "cassandra:CreateMultiRegionResource" ],
"Resource": [
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
]
}
]
}
```
## 檢視 UDT 的許可
若要在單一區域金鑰空間中檢視或列出 UDTs，委託人需要系統金鑰空間的讀取許可。如需詳細資訊，請參閱[`system_schema_mcs`](working-with-keyspaces.md#keyspace_system_schema_mcs)。
下列 IAM 政策為範例。
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"cassandra:Select",
"Resource":[
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/system*"
]
}
]
}
```
若要檢視或列出多區域金鑰空間UDTs，委託人需要動作`SELECT`和系統金鑰空間`SelectMultiRegionResource`的許可。如需詳細資訊，請參閱[`system_multiregion_info`](working-with-keyspaces.md#keyspace_system_multiregion_info)。
下列 IAM 政策為範例。
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action": ["cassandra:Select", "cassandra:SelectMultiRegionResource"],
"Resource":[
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/system*"
]
}
]
}
```
## 刪除 UDT 的許可
若要從單一區域金鑰空間刪除 UDT，委託人需要指定金鑰空間之 `Drop`動作的許可。
下列 IAM 政策為範例。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "cassandra:Drop",
"Resource": [
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
]
}
]
}
```
若要從多區域金鑰空間刪除 UDT，委託人需要 `Drop`動作的許可，以及指定金鑰空間的 `DropMultiRegionResource`動作的許可。
下列 IAM 政策為範例。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [ "cassandra:Drop", "cassandra:DropMultiRegionResource" ],
"Resource": [
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
]
}
]
}
```
# 在 Amazon Keyspaces 中建立使用者定義類型 (UDT)
若要在單一區域金鑰空間中建立 UDT，您可以在 CQL、 `create-type`命令與 AWS CLI或 主控台中使用 `CREATE TYPE`陳述式。
UDT 名稱不得超過 48 個字元、開頭必須是英文字母字元，且只能包含英數字元和底線。Amazon Keyspaces 會自動將大寫字元轉換成小寫字元。
或者，您可以使用雙引號宣告 UDT 名稱。在 UDT 名稱前後加上雙引號來宣告名稱時，Amazon Keyspaces 會保留大寫並允許特殊字元。
您也可以在建立 UDT 時使用雙引號作為名稱的一部分，但必須使用額外的雙引號字元來逸出每個雙引號字元。
下表顯示允許的 UDT 名稱範例。第一欄顯示如何在建立類型時輸入名稱，第二欄顯示 Amazon Keyspace 如何在內部格式化名稱。Amazon Keyspaces 預期 `GetType` 這類操作使用格式化的名稱。
| 輸入的名稱 | 格式化名稱 | 注意 |
| --- | --- | --- |
| MY\$1UDT | my\$1udt | 若沒有雙引號，Amazon Keyspaces 就會將所有大寫字元轉換成小寫字元。 |
| "MY\$1UDT" | MY\$1UDT | 若有雙引號，Amazon Keyspaces 就會遵循大寫字元，並從格式化名稱中移除雙引號。 |
| "1234" | 1234 | 若有雙引號，名稱開頭就可以是數字，而且 Amazon Keyspaces 會從格式化名稱中移除雙引號。 |
| "Special\$1Ch@r@cters<>\$1\$1" | Special\$1Ch@r@cters<>\$1\$1 | 若有雙引號，名稱就可以包含特殊字元，而且 Amazon Keyspaces 會從格式化名稱中移除雙引號。 |
| "nested""""""quotes" | nested"""quotes | Amazon Keyspaces 會從格式化名稱中移除最外層的雙引號及逸出雙引號。 |
------
#### [ Console ]
**使用 Amazon Keyspaces 主控台建立使用者定義類型 (UDT)**
1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/keyspaces/home](https://console.aws.amazon.com/keyspaces/home) 開啟 Amazon Keyspaces 主控台。
1. 在導覽窗格中，選擇**金鑰空間**，然後從清單中選擇金鑰空間。
1. 選擇 **UDTs**標籤。
1. 選擇**建立 UDT**
1. 在 **UDT 詳細資訊**下，輸入 UDT 的名稱。在 **UDT 欄位**下，您可以定義 UDT 的結構描述。
1. 若要完成，請選擇**建立 UDT**。
------
#### [ Cassandra Query Language (CQL) ]
**使用 CQL 建立使用者定義類型 (UDT)**
在此範例中，我們建立了 中使用的新版本書籍獎勵表[在 Amazon Keyspaces 中建立資料表](getting-started.tables.md)。在此表格中，我們會存放作者為指定書籍收到的所有獎勵。我們建立兩個巢狀 UDTs，其中包含有關獲得 獎勵之書籍的資訊。
1. 建立名稱為 的金鑰空間`catalog`。
```
CREATE KEYSPACE catalog WITH REPLICATION = {'class': 'SingleRegionStrategy'};
```
1. 建立第一個類型。此類型存放 *BISAC* 代碼，用於定義書籍類型。BISAC 代碼由英數字元代碼組成，最多四個主題區域。
```
CREATE TYPE catalog.bisac (
bisac_code text,
subject1 text,
subject2 text,
subject3 text,
subject4 text
);
```
1. 為使用第一個 UDT 的書籍獎勵建立第二個類型。巢狀 UDT 必須凍結。
```
CREATE TYPE catalog.book (
award_title text,
book_title text,
publication_date date,
page_count int,
ISBN text,
genre FROZEN
);
```
1. 使用作者名稱的資料欄建立資料表，並使用書籍獎勵的清單類型。請注意，清單中使用的 UDT 必須凍結。
```
CREATE TABLE catalog.authors (
author_name text PRIMARY KEY,
awards list >
);
```
1. 在此步驟中，我們會將一列資料插入新資料表。
```
CONSISTENCY LOCAL_QUORUM;
```
```
INSERT INTO catalog.authors (author_name, awards) VALUES (
'John Stiles' ,
[{
award_title: 'Wolf',
book_title: 'Yesterday',
publication_date: '2020-10-10',
page_count: 345,
ISBN: '026204630X',
genre: { bisac_code:'FIC014090', subject1: 'FICTION', subject2: 'Historical', subject3: '20th Century', subject4: 'Post-World War II'}
},
{award_title: 'Richard Roe',
book_title: 'Who ate the cake?',
publication_date: '2019-05-13',
page_count: 193,
ISBN: '9780262046305',
genre: { bisac_code:'FIC022130', subject1: 'FICTION', subject2: 'Mystery & Detective', subject3: 'Cozy', subject4: 'Culinary'}
}]
);
```
1. 在最後一個步驟中，我們從資料表讀取資料。
```
SELECT * FROM catalog.authors;
```
命令的輸出應如下所示。
```
author_name | awards
-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
John Stiles | [{award_title: 'Wolf', book_title: 'Yesterday', publication_date: 2020-10-10, page_count: 345, isbn: '026204630X', genre: {bisac_code: 'FIC014090', subject1: 'FICTION', subject2: 'Historical', subject3: '20th Century', subject4: 'Post-World War II'}}, {award_title: 'Richard Roe', book_title: 'Who ate the cake?', publication_date: 2019-05-13, page_count: 193, isbn: '9780262046305', genre: {bisac_code: 'FIC022130', subject1: 'FICTION', subject2: 'Mystery & Detective', subject3: 'Cozy', subject4: 'Culinary'}}]
(1 rows)
```
如需 CQL 語法的詳細資訊，請參閱 [CREATE TYPE](cql.ddl.type.md#cql.ddl.type.create)。
------
#### [ CLI ]
**使用 建立使用者定義類型 (UDT) AWS CLI**
1. 若要建立類型，您可以使用下列語法。
```
aws keyspaces create-type
--keyspace-name 'my_keyspace'
--type-name 'my_udt'
--field-definitions
'[
{"name" : "field1", "type" : "int"},
{"name" : "field2", "type" : "text"}
]'
```
1. 該命令的輸出看起來與此範例類似。請注意， 會`typeName`傳回 UDT 的格式化名稱。
```
{
"keyspaceArn": "arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/",
"typeName": "my_udt"
}
```
------
# 檢視 Amazon Keyspaces 中的使用者定義類型 (UDTs)
若要檢視或列出單一區域金鑰空間中的所有 UDTs，您可以使用 CQL `system_schema_mcs.types`中的陳述式查詢系統金鑰空間中的資料表，或搭配 AWS CLI或 主控台使用 `get-type`和 `list-type`命令。
對於任一選項，IAM 主體都需要系統金鑰空間的讀取許可。如需詳細資訊，請參閱[設定許可以在 Amazon Keyspaces 中使用使用者定義類型 (UDTs)](configure-udt-permissions.md)。
------
#### [ Console ]
**使用 Amazon Keyspaces 主控台檢視使用者定義類型 (UDT)**
1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/keyspaces/home](https://console.aws.amazon.com/keyspaces/home) 開啟 Amazon Keyspaces 主控台。
1. 在導覽窗格中，選擇**金鑰空間**，然後從清單中選擇金鑰空間。
1. 選擇 **UDTs**索引標籤，以檢閱金鑰空間中所有 UDTs的清單。
1. 若要詳細檢閱一個 UDT，請從清單中選擇 **UDT**。
1. 在**結構描述**索引標籤上，您可以檢閱結構描述。在**用於 **索引標籤上，您可以查看此 UDT 是否用於資料表或其他 UDTs。請注意，您只能刪除資料表或其他 UDTs 未使用的 UDTs。
------
#### [ Cassandra Query Language (CQL) ]
**使用 CQL 檢視單一區域金鑰空間的使用者定義類型 (UDTs)**
1. 若要查看指定金鑰空間中可用的類型，您可以使用下列陳述式。
```
SELECT type_name
FROM system_schema_mcs.types
WHERE keyspace_name = 'my_keyspace';
```
1. 若要檢視特定類型的詳細資訊，您可以使用下列陳述式。
```
SELECT
keyspace_name,
type_name,
field_names,
field_types,
max_nesting_depth,
last_modified_timestamp,
status,
direct_referring_tables,
direct_parent_types
FROM system_schema_mcs.types
WHERE keyspace_name = 'my_keyspace' AND type_name = 'my_udt';
```
1. 您可以使用 列出帳戶中存在的所有 UDTs`DESC TYPE`。
```
DESC TYPES;
Keyspace my_keyspace
---------------------------
my_udt1 my_udt2
Keyspace my_keyspace2
---------------------------
my_udt1
```
1. 您可以使用 列出目前所選金鑰空間中的所有 UDTs`DESC TYPE`。
```
USE my_keyspace;
my_keyspace DESC TYPES;
my_udt1 my_udt2
```
1. 若要列出多區域金鑰空間中的所有 UDTs，您可以在`system_multiregion_info`金鑰空間`types`中查詢系統資料表。下列查詢是此範例。
```
SELECT keyspace_name, type_name, region, status FROM system_multiregion_info.types WHERE keyspace_name = 'mykeyspace' AND table_name = 'mytable';
```
此命令的輸出看起來與此類似。
```
keyspace_name | table_name | region | status
mykeyspace | mytable | us-east-1 | ACTIVE
mykeyspace | mytable | ap-southeast-1 | ACTIVE
mykeyspace | mytable | eu-west-1 | ACTIVE
```
------
#### [ CLI ]
**使用 檢視使用者定義類型 (UDTs) AWS CLI**
1. 若要列出金鑰空間中可用的類型，您可以使用 `list-types`命令。
```
aws keyspaces list-types
--keyspace-name 'my_keyspace'
```
該命令的輸出看起來與此範例類似。
```
{
"types": [
"my_udt",
"parent_udt"
]
}
```
1. 若要檢視指定類型的詳細資訊，您可以使用 `get-type`命令。
```
aws keyspaces get-type
--type-name 'my_udt'
--keyspace-name 'my_keyspace'
```
此命令的輸出看起來與此範例類似。
```
{
"keyspaceName": "my_keyspace",
"typeName": "my_udt",
"fieldDefinitions": [
{
"name": "a",
"type": "int"
},
{
"name": "b",
"type": "text"
}
],
"lastModifiedTimestamp": 1721328225776,
"maxNestingDepth": 3
"status": "ACTIVE",
"directReferringTables": [],
"directParentTypes": [
"parent_udt"
],
"keyspaceArn": "arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/"
}
```
------
# 在 Amazon Keyspaces 中刪除使用者定義類型 (UDT)
若要刪除金鑰空間中的 UDT，您可以在 CQL、 `delete-type`命令與 AWS CLI或 主控台中使用 `DROP TYPE`陳述式。
------
#### [ Console ]
**使用 Amazon Keyspaces 主控台刪除使用者定義類型 (UDT)**
1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/keyspaces/home](https://console.aws.amazon.com/keyspaces/home) 開啟 Amazon Keyspaces 主控台。
1. 在導覽窗格中，選擇**金鑰空間**，然後從清單中選擇金鑰空間。
1. 選擇 **UDTs**標籤。
1. 選擇您要刪除的 UDT。在 **中使用的** 上，您可以確認資料表或其他 UDT 目前未使用您要刪除的類型。
1. 選擇**摘要**上方的**刪除**。
1. `Delete` 在顯示的對話方塊中輸入 ，然後選擇**刪除 UDT**。
------
#### [ Cassandra Query Language (CQL) ]
**使用 CQL 刪除使用者定義類型 (UDT)**
+ 若要刪除類型，您可以使用下列陳述式。
```
DROP TYPE my_keyspace.my_udt;
```
如需 CQL 語法的詳細資訊，請參閱 [DROP TYPE](cql.ddl.type.md#cql.ddl.type.drop)。
------
#### [ CLI ]
**使用 刪除使用者定義類型 (UDT) AWS CLI**
1. 若要刪除類型，您可以使用下列命令。
```
aws keyspaces delete-type
--keyspace-name 'my_keyspace'
--type-name 'my_udt'
```
1. 命令的輸出看起來與此範例類似。
```
{
"keyspaceArn": "arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/",
"typeName": "my_udt"
}
```
------