本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon Keyspaces 疑難排解 （適用於 Apache Cassandra)
本指南涵蓋使用 Amazon Keyspaces （適用於 Apache Cassandra) 時各種案例的疑難排解步驟。它包含解決一般錯誤、連線問題、容量管理問題和資料定義語言 (DDL) 錯誤的資訊。
+ **一般錯誤**
+ 疑難排解最上層例外狀況`NoHostAvailableException`，例如 `NoNodeAvailableException`、 和 `AllNodesFailedException`。
+ 隔離基礎錯誤與 Java 驅動程式例外狀況。
+ 實作重試政策和正確設定連線。
+ **連線問題**
+ 解決使用 `cqlsh`或 Apache Cassandra 用戶端驅動程式連線至 Amazon Keyspaces 端點時的錯誤。
+ 故障診斷 VPC 端點連線、Cassandra-stress 連線和 IAM 組態錯誤。
+ 在資料匯入期間處理連線中斷。
+ **容量管理錯誤**
+ 識別和解決與資料表、分割區和連線相關的容量不足錯誤。
+ 監控 Amazon CloudWatch Logs 中的相關 Amazon Keyspaces 指標。
+ 最佳化連線和輸送量以提升效能。
+ **資料定義語言 (DDL) 錯誤**
+ 建立、存取或還原金鑰空間和資料表時發生錯誤的故障診斷。
+ 處理與自訂存留時間 (TTL) 設定、資料欄限制和範圍刪除相關的失敗。
+ 大量刪除工作負載的考量事項。
如需 IAM 存取特定的疑難排解指引，請參閱 [對 Amazon Keyspaces 身分和存取進行故障診斷](security_iam_troubleshoot.md)。如需安全最佳實務的詳細資訊，請參閱 [Amazon Keyspaces 的安全最佳實務](best-practices-security.md)。
**Topics**
+ [一般錯誤](troubleshooting.general.md)
+ [連線錯誤](troubleshooting.connecting.md)
+ [容量管理錯誤](troubleshooting.serverless.md)
+ [資料定義語言錯誤](troubleshooting.cql.md)
# 對 Amazon Keyspaces 中的一般錯誤進行故障診斷
取得一般錯誤？ 以下是一些常見問題，以及如何解決這些問題。
## 一般錯誤
您會收到下列其中一個可能因許多不同原因而發生的頂層例外狀況。
+ `NoNodeAvailableException`
+ `NoHostAvailableException`
+ `AllNodesFailedException`
這些例外狀況是由用戶端驅動程式產生，而且可能會在您建立控制連線或執行read/write/prepare/執行/批次請求時發生。
當您建立控制連線時發生錯誤時，表示應用程式中指定的所有聯絡點都無法連線。當執行read/write/prepare/執行查詢時發生錯誤時，表示該請求的所有重試都已用盡。當您使用預設重試政策時，會在不同的節點上嘗試每次重試。
### 如何隔離基礎錯誤與最上層 Java 驅動程式例外狀況
這些一般錯誤可能是由連線問題或執行read/write/prepare/執行操作時造成。必須在分散式系統中預期暫時性失敗，並且應該透過重試請求來處理。遇到連線錯誤時，Java 驅動程式不會自動重試，因此建議在應用程式中建立驅動程式連線時實作重試政策。如需連線最佳實務的詳細概觀，請參閱 [最佳化無伺服器環境的用戶端驅動程式連線](connections.md)。
根據預設，Java 驅動程式會將所有請求`idempotence`設為 false，這表示 Java 驅動程式不會自動重試失敗的read/write/prepare請求。若要`idempotence`將 設定為 `true` 並告知驅動程式重試失敗的請求，您可以透過幾種不同的方式執行此操作。以下範例說明如何以程式設計方式為 Java 應用程式中的單一請求設定冪等性。
```
Statement s = new SimpleStatement("SELECT * FROM my_table WHERE id = 1");
s.setIdempotent(true);
```
或者，您可以透過程式設計方式設定整個 Java 應用程式的預設冪等性，如下列範例所示。
```
// Make all statements idempotent by default:
cluster.getConfiguration().getQueryOptions().setDefaultIdempotence(true);
//Set the default idempotency to true in your Cassandra configuration
basic.request.default-idempotence = true
```
另一個建議是在應用程式層級建立重試政策。在此情況下，應用程式需要擷取 `NoNodeAvailableException` 並重試請求。我們建議從 10 毫秒開始，以指數退避進行 10 次重試，並對所有重試進行最多 100 毫秒的總時間為 1 秒。
另一個選項是在建立 [Github](https://github.com/aws-samples/amazon-keyspaces-java-driver-helpers/blob/main/src/main/java/com/aws/ssa/keyspaces/retry/AmazonKeyspacesExponentialRetryPolicy.java) 上可用的 Java 驅動程式連線時套用 Amazon Keyspaces 指數重試政策。
確認您在使用預設重試政策時已建立與多個節點的連線。您可以在 Amazon Keyspaces 中使用下列查詢來執行此操作。
```
SELECT * FROM system.peers;
```
如果此查詢的回應是空的，這表示您正在使用 Amazon Keyspaces 的單一節點。如果您使用的是預設重試政策，則不會重試，因為預設重試一律發生在不同的節點上。若要進一步了解如何透過 VPC 端點建立連線，請參閱 [如何在 Amazon Keyspaces 中透過 VPC 端點設定連線](connections.md#connections.VPCendpoints)。
如需step-by-step教學課程，說明如何使用 Datastax 4.x Cassandra 驅動程式建立與 Amazon Keyspaces 的連線，請參閱 [使用適用於 Apache Cassandra 的 4.x DataStax Java 驅動程式和 SigV4 身分驗證外掛程式連線至 Amazon Keyspaces 的Step-by-step教學課程](using_java_driver.md#java_tutorial.SigV4)。
# 對 Amazon Keyspaces 中的連線錯誤進行故障診斷
連線時發生問題？ 以下是一些常見問題，以及如何解決這些問題。
## 連線至 Amazon Keyspaces 端點時發生錯誤
失敗的連線和連線錯誤可能會導致不同的錯誤訊息。下一節涵蓋最常見的案例。
**Topics**
+ [我無法使用 cqlsh 連線到 Amazon Keyspaces](#troubleshooting.connection.cqlsh)
+ [我無法使用 Cassandra 用戶端驅動程式連線至 Amazon Keyspaces](#troubleshooting.connection.driver)
### 我無法使用 cqlsh 連線到 Amazon Keyspaces
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces 端點，但連線與 的連線失敗`Connection error`。**
如果您嘗試連線至 Amazon Keyspaces 資料表，但尚未正確設定 cqlsh，則連線會失敗。下節提供在您嘗試使用 cqlsh 建立連線時，導致連線錯誤的最常見組態問題範例。
**注意**
如果您嘗試從 VPC 連線至 Amazon Keyspaces，則需要額外的許可。若要使用 VPC 端點成功設定連線，請遵循中的步驟[教學課程：使用介面 VPC 端點連線至 Amazon Keyspaces](vpc-endpoints-tutorial.md)。
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但發生連線`timed out`錯誤。**
如果您未提供正確的連接埠，則可能會發生這種情況，這會導致下列錯誤。
```
# cqlsh cassandra.us-east-1.amazonaws.com 9140 -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.199': error(None, "Tried connecting to [('3.234.248.199', 9140)]. Last error: timed out")})
```
若要解決此問題，請確認您使用連接埠 9142 進行連線。
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但發生錯誤`Name or service not known`。**
如果您使用的端點拼寫錯誤或不存在，則可能會發生這種情況。在下列範例中，端點的名稱拼錯。
```
# cqlsh cassandra.us-east-1.amazon.com 9142 -u "USERNAME" -p "PASSWORD" --ssl
Traceback (most recent call last):
File "/usr/bin/cqlsh.py", line 2458, in >module>
main(*read_options(sys.argv[1:], os.environ))
File "/usr/bin/cqlsh.py", line 2436, in main
encoding=options.encoding)
File "/usr/bin/cqlsh.py", line 484, in __init__
load_balancing_policy=WhiteListRoundRobinPolicy([self.hostname]),
File "/usr/share/cassandra/lib/cassandra-driver-internal-only-3.11.0-bb96859b.zip/cassandra-driver-3.11.0-bb96859b/cassandra/policies.py", line 417, in __init__
socket.gaierror: [Errno -2] Name or service not known
```
若要在使用公有端點進行連線時解決此問題，請從 選取可用的端點[Amazon Keyspaces 的服務端點](programmatic.endpoints.md)，並確認端點的名稱沒有任何錯誤。如果您使用 VPC 端點進行連線，請確認 cqlsh 組態中的 VPC 端點資訊正確無誤。
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但收到`OperationTimedOut`錯誤。**
Amazon Keyspaces 需要為連線啟用 SSL，以確保強大的安全性。如果您收到下列錯誤，則 SSL 參數可能會遺失。
```
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD"
Connection error: ('Unable to connect to any servers', {'3.234.248.192': OperationTimedOut('errors=Timed out creating connection (5 seconds), last_host=None',)})
#
```
若要解決此問題，請將下列旗標新增至 cqlsh 連線命令。
```
--ssl
```
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，並收到`SSL transport factory requires a valid certfile to be specified`錯誤。**
在此情況下，缺少 SSL/TLS 憑證的路徑，這會導致下列錯誤。
```
# cat .cassandra/cqlshrc
[connection]
port = 9142
factory = cqlshlib.ssl.ssl_transport_factory
#
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Validation is enabled; SSL transport factory requires a valid certfile to be specified. Please provide path to the certfile in [ssl] section as 'certfile' option in /root/.cassandra/cqlshrc (or use [certfiles] section) or set SSL_CERTFILE environment variable.
#
```
若要解決此問題，請將路徑新增至電腦上的 certfile。如需詳細資訊，請參閱[如何手動設定 TLS 的`cqlsh`連線](programmatic.cqlsh.md#encrypt_using_tls)。
```
certfile = path_to_file/keyspaces-bundle.pem
```
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但收到`No such file or directory`錯誤。**
如果電腦上憑證檔案的路徑錯誤，這可能會導致以下錯誤。
```
# cat .cassandra/cqlshrc
[connection]
port = 9142
factory = cqlshlib.ssl.ssl_transport_factory
[ssl]
validate = true
certfile = /root/wrong_path/keyspaces-bundle.pem
#
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.192': IOError(2, 'No such file or directory')})
#
```
若要解決此問題，請確認電腦上 certfile 的路徑正確無誤。如需詳細資訊，請參閱[如何手動設定 TLS 的`cqlsh`連線](programmatic.cqlsh.md#encrypt_using_tls)。
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但收到`[X509] PEM lib`錯誤。**
如果 SSL/TLS 憑證`pem`檔案無效，則可能會發生這種情況，這會導致下列錯誤。
```
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.241': error(185090057, u"Tried connecting to [('3.234.248.241', 9142)]. Last error: [X509] PEM lib (_ssl.c:3063)")})
#
```
若要解決此問題，請確定您已下載必要的數位憑證。如需詳細資訊，請參閱[如何手動設定 TLS 的`cqlsh`連線](programmatic.cqlsh.md#encrypt_using_tls)。
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但收到 `unknown` SSL 錯誤。**
如果 SSL/TLS 憑證`pem`檔案是空的，則可能會發生這種情況，這會導致下列錯誤。
```
# cqlsh cassandra.us-east-1.amazonaws.com -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.220': error(0, u"Tried connecting to [('3.234.248.220', 9142)]. Last error: unknown error (_ssl.c:3063)")})
#
```
若要解決此問題，請確定您已下載必要的數位憑證。您可以使用下列主題 中的步驟來確認這一點[如何手動設定 TLS 的`cqlsh`連線](programmatic.cqlsh.md#encrypt_using_tls)。
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但收到`SSL: CERTIFICATE_VERIFY_FAILED`錯誤。**
如果無法驗證 SSL/TLS 憑證檔案，則可能會發生這種情況，這會導致下列錯誤。
```
Connection error: ('Unable to connect to any servers', {'3.234.248.223': error(1, u"Tried connecting to [('3.234.248.223', 9142)]. Last error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:727)")})
```
若要解決此問題，請確定您已下載必要的數位憑證。您可以使用下列主題 中的步驟來確認這一點[如何手動設定 TLS 的`cqlsh`連線](programmatic.cqlsh.md#encrypt_using_tls)。
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但收到`Last error: timed out`錯誤。**
如果您未在 Amazon EC2 安全群組中為 Amazon Keyspaces 設定傳出規則，這可能會導致以下錯誤。
```
# cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.206': error(None, "Tried connecting to [('3.234.248.206', 9142)]. Last error: timed out")})
#
```
若要確認此問題是由 Amazon EC2 執行個體的組態造成，而非 `cqlsh`，您可以嘗試使用 連線到您的金鑰空間 AWS CLI，例如使用下列命令。
```
aws keyspaces list-tables --keyspace-name 'my_keyspace'
```
如果此命令也逾時，表示 Amazon EC2 執行個體未正確設定。
若要確認您有足夠的許可來存取 Amazon Keyspaces，您可以使用 AWS CloudShell 來與 連線`cqlsh`。如果連線已建立，您需要設定 Amazon EC2 執行個體。
若要解決此問題，請確認您的 Amazon EC2 執行個體具有允許流量至 Amazon Keyspaces 的傳出規則。如果不是這種情況，您需要為 EC2 執行個體建立新的安全群組，並新增允許傳出流量到 Amazon Keyspaces 資源的規則。若要更新傳出規則以允許流量到 Amazon Keyspaces，請從**類型**下拉式選單中選擇 **CQLSH/CASSANDRA**。
使用傳出流量規則建立新的安全群組之後，您需要將其新增至執行個體。選取執行個體，然後選擇**動作**、**安全性**，然後選擇**變更安全群組**。使用傳出規則新增安全群組，但請確定預設群組也保持可用。
如需如何檢視和編輯 EC2 傳出規則的詳細資訊，請參閱《[Amazon EC2 使用者指南》中的將規則新增至安全群組](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-security-groups.html#adding-security-group-rule)。
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但收到`Unauthorized`錯誤。**
如果您在 IAM 使用者政策中缺少 Amazon Keyspaces 許可，這可能會導致以下錯誤。
```
# cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "testuser-at-12345678910" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.241': AuthenticationFailed('Failed to authenticate to 3.234.248.241: Error from server: code=2100 [Unauthorized] message="User arn:aws:iam::12345678910:user/testuser has no permissions."',)})
#
```
若要解決此問題，請確定 IAM 使用者`testuser-at-12345678910`具有存取 Amazon Keyspaces 的許可。如需授予 Amazon Keyspaces 存取權的 IAM 政策範例，請參閱 [Amazon Keyspaces 身分型政策範例](security_iam_id-based-policy-examples.md)。
如需 IAM 存取特定的疑難排解指引，請參閱 [對 Amazon Keyspaces 身分和存取進行故障診斷](security_iam_troubleshoot.md)。
**您嘗試使用 cqlsh 連線至 Amazon Keyspaces，但收到`Bad credentials`錯誤。**
如果使用者名稱或密碼錯誤，則可能會發生這種情況，這會導致下列錯誤。
```
# cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "USERNAME" -p "PASSWORD" --ssl
Connection error: ('Unable to connect to any servers', {'3.234.248.248': AuthenticationFailed('Failed to authenticate to 3.234.248.248: Error from server: code=0100 [Bad credentials] message="Provided username USERNAME and/or password are incorrect"',)})
#
```
若要解決此問題，請確認程式碼中的 *USERNAME* 和 *PASSWORD* 與您產生[服務特定登入](programmatic.credentials.ssc.md)資料時取得的使用者名稱和密碼相符。
**重要**
如果您在嘗試與 cqlsh 連線時持續看到錯誤，請使用 `--debug`選項重新執行命令，並在聯絡 時包含詳細輸出 支援。
### 我無法使用 Cassandra 用戶端驅動程式連線至 Amazon Keyspaces
下列各節顯示與 Cassandra 用戶端驅動程式連線時最常見的錯誤。
**您嘗試使用 DataStax Java 驅動程式連線至 Amazon Keyspaces 資料表，但收到`NodeUnavailableException`錯誤。**
如果嘗試請求的連線中斷，則會導致下列錯誤。
```
[com.datastax.oss.driver.api.core.NodeUnavailableException: No connection was available to Node(endPoint=vpce-22ff22f2f22222fff-aa1bb234.cassandra.us-west-2.vpce.amazonaws.com/11.1.1111.222:9142, hostId=1a23456b-c77d-8888-9d99-146cb22d6ef6, hashCode=123ca4567)]
```
若要解決此問題，請尋找活動訊號值，如果訊號值較高，請將其降至 30 秒。
```
advanced.heartbeat.interval = 30 seconds
```
然後尋找相關聯的逾時，並確保值設定為至少 5 秒。
```
advanced.connection.init-query-timeout = 5 seconds
```
**您嘗試使用驅動程式和 SigV4 外掛程式連線至 Amazon Keyspaces 資料表，但收到`AttributeError`錯誤。**
如果登入資料未正確設定，則會導致下列錯誤。
```
cassandra.cluster.NoHostAvailable: (‘Unable to connect to any servers’,
{‘44.234.22.154:9142’: AttributeError(“‘NoneType’ object has no attribute ‘access_key’“)})
```
若要解決此問題，請確認您在使用 SigV4 外掛程式時，傳遞與您的 IAM 使用者或角色相關聯的登入資料。SigV4 外掛程式需要下列登入資料。
+ `AWS_ACCESS_KEY_ID` – 指定與 IAM 使用者或角色相關聯的 AWS 存取金鑰。
+ `AWS_SECRET_ACCESS_KEY`– 指定與存取金鑰相關聯的私密金鑰。這基本上是存取金鑰的「密碼」。
若要進一步了解存取金鑰和 SigV4 外掛程式，請參閱 [建立和設定 Amazon Keyspaces 的 AWS 登入資料](access.credentials.md)。
**您嘗試使用驅動程式連線至 Amazon Keyspaces 資料表，但收到`PartialCredentialsError`錯誤。**
如果遺失 `AWS_SECRET_ACCESS_KEY` ，可能會導致下列錯誤。
```
cassandra.cluster.NoHostAvailable: (‘Unable to connect to any servers’, {‘44.234.22.153:9142’:
PartialCredentialsError(‘Partial credentials found in config-file, missing: aws_secret_access_key’)})
```
若要解決此問題，請確認您使用 SigV4 外掛程式`AWS_SECRET_ACCESS_KEY`時同時傳遞 `AWS_ACCESS_KEY_ID`和 。若要進一步了解存取金鑰和 SigV4 外掛程式，請參閱 [建立和設定 Amazon Keyspaces 的 AWS 登入資料](access.credentials.md)。
**您嘗試使用驅動程式連線至 Amazon Keyspaces 資料表，但收到`Invalid signature`錯誤。**
如果簽章所需的任何元件錯誤或未正確定義工作階段，則可能會發生這種情況。
+ `AWS_ACCESS_KEY_ID`
+ `AWS_SECRET_ACCESS_KEY`
+ `AWS_DEFAULT_REGION`
下列錯誤是無效的存取金鑰範例。
```
cassandra.cluster.NoHostAvailable: (‘Unable to connect to any servers’, {‘11.234.11.234:9142’:
AuthenticationFailed(‘Failed to authenticate to 11.234.11.234:9142: Error from server: code=0100
[Bad credentials] message=“Authentication failure: Invalid signature”’)})
```
若要解決此問題，請確認存取金鑰和 AWS 區域 已正確設定供 SigV4 外掛程式存取 Amazon Keyspaces。若要進一步了解存取金鑰和 SigV4 外掛程式，請參閱 [建立和設定 Amazon Keyspaces 的 AWS 登入資料](access.credentials.md)。
#### 我的 VPC 端點連線無法正常運作
**您嘗試使用 VPC 端點連線至 Amazon Keyspaces，但收到字符映射錯誤或輸送量低。 **
如果 VPC 端點連線未正確設定，則可能會發生這種情況。
若要解決這些問題，請確認下列組態詳細資訊。若要遵循step-by-step教學，了解如何透過 Amazon Keyspaces 的介面 VPC 端點設定連線，請參閱 [教學課程：使用介面 VPC 端點連線至 Amazon Keyspaces](vpc-endpoints-tutorial.md)。
1. 確認用於連線至 Amazon Keyspaces 的 IAM 實體具有使用者資料表的讀取/寫入存取權，以及對系統資料表的讀取存取權，如下列範例所示。
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"cassandra:Select",
"cassandra:Modify"
],
"Resource":[
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/mykeyspace/table/mytable",
"arn:aws:cassandra:us-east-1:111122223333:/keyspace/system*"
]
}
]
}
```
1. 確認用於連線至 Amazon Keyspaces 的 IAM 實體具有存取 Amazon EC2 執行個體上 VPC 端點資訊所需的讀取許可，如下列範例所示。
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"ListVPCEndpoints",
"Effect":"Allow",
"Action":[
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeVpcEndpoints"
],
"Resource":"*"
}
]
}
```
**注意**
受管政策`AmazonKeyspacesReadOnlyAccess_v2`並`AmazonKeyspacesFullAccess`包含必要許可，讓 Amazon Keyspaces 存取 Amazon EC2 執行個體，以讀取可用介面 VPC 端點的相關資訊。
如需 VPC 端點的詳細資訊，請參閱 [使用 Amazon Keyspaces 的介面 VPC 端點](vpc-endpoints.md#using-interface-vpc-endpoints)
1. 確認 Java 驅動程式的 SSL 組態將主機名稱驗證設定為 false，如本範例所示。
```
hostname-validation = false
```
如需驅動程式組態的詳細資訊，請參閱 [步驟 2：設定驅動程式](using_java_driver.md#java_tutorial.driverconfiguration)。
1. 若要確認 VPC 端點已正確設定，您可以從 VPC *內*執行下列陳述式。
**注意**
您無法使用本機開發人員環境或 Amazon Keyspaces CQL 編輯器來確認此組態，因為它們使用公有端點。
```
SELECT peer FROM system.peers;
```
輸出看起來應該類似此範例，並在從 IPv4 網路連線時傳回 2 到 6 個具有私有 IPv4 地址的節點，視您的 VPC 設定和 AWS 區域而定。
```
peer
---------------
192.0.2.0.15
192.0.2.0.24
192.0.2.0.13
192.0.2.0.7
192.0.2.0.8
(5 rows)
```
#### 我無法使用 連線 `cassandra-stress`
**您嘗試使用 `cassandra-stress`命令連線至 Amazon Keyspaces，但收到`SSL context`錯誤。 **
如果您嘗試連線至 Amazon Keyspaces，但您未正確設定 trustStore，就會發生這種情況。Amazon Keyspaces 需要使用 Transport Layer Security (TLS) 來協助保護與用戶端的連線。
在此情況下，您會看到下列錯誤。
```
Error creating the initializing the SSL Context
```
若要解決此問題，請依照指示設定 trustStore，如本主題 所示[開始之前](using_java_driver.md#using_java_driver.BeforeYouBegin)。
設定 trustStore 後，您應該能夠使用下列命令進行連線。
```
./cassandra-stress user profile=./profile.yaml n=100 "ops(insert=1,select=1)" cl=LOCAL_QUORUM -node "cassandra.eu-north-1.amazonaws.com" -port native=9142 -transport ssl-alg="PKIX" truststore="./cassandra_truststore.jks" truststore-password="trustStore_pw" -mode native cql3 user="user_name" password="password"
```
#### 我無法使用 IAM 身分連線
**您嘗試使用 IAM 身分連線至 Amazon Keyspaces 資料表，但收到`Unauthorized`錯誤。 **
如果您嘗試使用 IAM 身分 （例如 IAM 使用者） 連線到 Amazon Keyspaces 資料表，但未實作政策並先提供使用者所需的許可，就會發生這種情況。
在此情況下，您會看到下列錯誤。
```
Connection error: ('Unable to connect to any servers', {'3.234.248.202': AuthenticationFailed('Failed to authenticate to 3.234.248.202:
Error from server: code=2100 [Unauthorized] message="User arn:aws:iam::1234567890123:user/testuser has no permissions."',)})
```
若要解決此問題，請驗證 IAM 使用者的許可。若要與標準驅動程式連線，使用者必須至少`SELECT`存取系統資料表，因為大多數驅動程式會在建立連線時讀取系統金鑰空間/資料表。
如需授予 Amazon Keyspaces 系統和使用者資料表存取權的 IAM 政策範例，請參閱 [存取 Amazon Keyspaces 資料表](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-one-table)。
若要檢閱 IAM 特定的疑難排解區段，請參閱 [對 Amazon Keyspaces 身分和存取進行故障診斷](security_iam_troubleshoot.md)。
#### 我嘗試使用 cqlsh 匯入資料，且與 Amazon Keyspaces 資料表的連線遺失
**您嘗試使用 cqlsh 將資料上傳至 Amazon Keyspaces，但收到連線錯誤。**
cqlsh 用戶端從伺服器收到任何類型的連續三次錯誤後，與 Amazon Keyspaces 的連線會失敗。cqlsh 用戶端失敗，並顯示下列訊息。
```
Failed to import 1 rows: NoHostAvailable - , will retry later, attempt 3 of 100
```
若要解決此錯誤，您需要確定要匯入的資料符合 Amazon Keyspaces 中的資料表結構描述。檢閱匯入檔案是否有剖析錯誤。您可以使用 INSERT 陳述式來隔離錯誤，嘗試使用單一資料列。
用戶端會自動嘗試重新建立連線。
# 對 Amazon Keyspaces 中的容量管理錯誤進行故障診斷
無法使用無伺服器容量？ 以下是一些常見問題，以及如何解決這些問題。
## 無伺服器容量錯誤
本節概述如何識別與無伺服器容量管理相關的錯誤，以及如何解決這些錯誤。例如，當您的應用程式超過佈建的輸送量容量時，您可能會發現容量事件不足。
由於 Apache Cassandra 是叢集型軟體，專為在節點機群上執行而設計，因此沒有與無伺服器功能相關的例外狀況訊息，例如輸送量容量。大多數驅動程式只了解 Apache Cassandra 中可用的錯誤代碼，因此 Amazon Keyspaces 會使用相同的一組錯誤代碼來維持相容性。
若要將 Cassandra 錯誤對應至基礎容量事件，您可以使用 Amazon CloudWatch 來監控相關的 Amazon Keyspaces 指標。導致用戶端錯誤的容量不足事件，可根據導致事件的資源分類為這三個群組：
+ **資料表** – 如果您選擇資料表的**佈建**容量模式，且應用程式超過佈建的輸送量，則可能會發現容量不足錯誤。如需詳細資訊，請參閱[在 Amazon Keyspaces 中設定讀取/寫入容量模式](ReadWriteCapacityMode.md)。
+ **分割區** – 如果針對指定分割區的流量超過 3，000 RCUs 或 1，000 個 WCUs，您可能會遇到容量不足的事件。最佳實務是建議在分割區之間均勻分配流量。如需詳細資訊，請參閱[資料建模最佳實務：設計資料模型的建議](data-modeling.md)。
+ **連線** – 如果您超過每個連線每秒最大操作數的配額，可能會遇到輸送量不足的情況。若要提高輸送量，您可以在設定與驅動程式的連線時增加預設連線數。
若要了解如何設定 Amazon Keyspaces 的連線，請參閱 [如何在 Amazon Keyspaces 中設定連線](connections.md#connections.howtoconfigure)。如需透過 VPC 端點最佳化連線的詳細資訊，請參閱 [如何在 Amazon Keyspaces 中透過 VPC 端點設定連線](connections.md#connections.VPCendpoints)。
若要判斷哪個資源造成傳回用戶端錯誤的容量不足事件，您可以在 Amazon Keyspaces 主控台中檢查儀表板。根據預設，主控台會在資料表的容量索引標籤的**容量和相關指標**區段中，提供最常見**容量**和流量相關 CloudWatch 指標的彙總檢視。
若要使用 Amazon CloudWatch 建立您自己的儀表板，請檢查下列 Amazon Keyspaces 指標。
+ `PerConnectionRequestRateExceeded` – 對 Amazon Keyspaces 的請求超過每個連線請求率的配額。每個客户端到 Amazon Keyspaces 的連線最多可支援每秒 3000 個 CQL 請求。透過建立多個連線，可以每秒執行 3000 多個請求。
+ `ReadThrottleEvents` – 請求超過資料表讀取容量的 Amazon Keyspaces。
+ `StoragePartitionThroughputCapacityExceeded` – 請求超過分割區輸送量容量的 Amazon Keyspaces 儲存分割區。Amazon Keyspaces 儲存分割區每秒最多可支援 1000 WCU/WRU 和 3000 RCU/RRU。為了減少這些例外情況，建議您查看資料模型，以便在更多分區之間分配讀取/寫入流量。
+ `WriteThrottleEvents` – 請求超過資料表寫入容量的 Amazon Keyspaces。
若要進一步了解 CloudWatch，請參閱 [使用 Amazon CloudWatch 監控 Amazon Keyspaces](monitoring-cloudwatch.md)。如需 Amazon Keyspaces 所有可用 CloudWatch 指標的清單，請參閱 [Amazon Keyspaces 指標和維度](metrics-dimensions.md)。
**注意**
若要開始使用顯示 Amazon Keyspaces 所有常用指標的自訂儀表板，您可以使用[AWS 範例](https://github.com/aws-samples/amazon-keyspaces-cloudwatch-cloudformation-templates)儲存庫中 GitHub 上可用的預先建置 CloudWatch 範本。
**Topics**
+ [用戶端錯誤](#troubleshooting.serverless.clientside)
+ [資料匯入期間寫入逾時錯誤](#troubleshooting.serverless.writetimeout)
+ [金鑰空間或資料表儲存體大小](#troubleshooting.serverless.storagesize)
### 我從用戶端驅動程式收到容量`NoHostAvailable`不足的錯誤
**您正在查看資料表的 `Read_Timeout`或 `Write_Timeout`例外狀況。**
重複嘗試寫入或讀取容量不足的 Amazon Keyspaces 資料表，可能會導致驅動程式特有的用戶端錯誤。
使用 CloudWatch 監控您的佈建和實際輸送量指標，以及資料表的容量不足事件。例如，沒有足夠輸送量容量的讀取請求會失敗，但有`Read_Timeout`例外狀況，並會發佈到 `ReadThrottleEvents` 指標。輸送量容量不足的寫入請求會失敗，但有`Write_Timeout`例外狀況，並會發佈到 `WriteThrottleEvents` 指標。如需這些指標的詳細資訊，請參閱 [Amazon Keyspaces 指標和維度](metrics-dimensions.md)。
若要解決這些問題，請考慮下列其中一個選項。
+ 增加資料表的*佈建輸送量*，這是應用程式可使用的最大輸送量。如需詳細資訊，請參閱[讀取容量單位和寫入容量單位](ReadWriteCapacityMode.Provisioned.md#ReadWriteCapacityMode.Provisioned.Units)。
+ 讓服務透過自動擴展代表您管理輸送量容量。如需詳細資訊，請參閱[使用 Amazon Keyspaces 自動擴展自動管理輸送量容量](autoscaling.md)。
+ 選擇資料表的**隨需**容量模式。如需詳細資訊，請參閱[設定隨需容量模式](ReadWriteCapacityMode.OnDemand.md)。
如果您需要增加帳戶的預設容量配額，請參閱 [Amazon Keyspaces 配額 （適用於 Apache Cassandra)](quotas.md)。
**您看到與超過分割區容量相關的錯誤。**
當您看到錯誤時`StoragePartitionThroughputCapacityExceeded`，會暫時超過分割區容量。這可能會由自適應容量或隨需容量自動處理。我們建議您檢閱資料模型，將讀取/寫入流量分散到更多分割區，以減少這些錯誤。Amazon Keyspaces 儲存分割區每秒最多可支援 1000 WCU/WRU 和 3000 RCU/RRU。若要進一步了解如何改善資料模型，以將讀取/寫入流量分散到更多分割區，請參閱 [資料建模最佳實務：設計資料模型的建議](data-modeling.md)。
`Write_Timeout` 例外狀況也可能是由並行寫入操作的速率提高所造成，包括相同邏輯分割區中的靜態和非靜態資料。如果預期流量會執行多個並行寫入操作，其中包含相同邏輯分割區內的靜態和非靜態資料，建議您分別寫入靜態和非靜態資料。分別寫入資料也有助於最佳化輸送量成本。
**您看到與超出連線請求率相關的錯誤。**
由於下列其中一個原因`PerConnectionRequestRateExceeded`，您看到 。
+ 您可能沒有為每個工作階段設定足夠的連線。
+ 您取得的連線可能少於可用的對等，因為您未正確設定 VPC 端點許可。如需 VPC 端點政策的詳細資訊，請參閱 [使用 Amazon Keyspaces 的介面 VPC 端點](vpc-endpoints.md#using-interface-vpc-endpoints)。
+ 如果您使用的是 4.x 驅動程式，請檢查您是否已啟用主機名稱驗證。根據預設，驅動程式會啟用 TLS 主機名稱驗證。此組態會導致 Amazon Keyspaces 顯示為驅動程式的單一節點叢集。建議您關閉主機名稱驗證。
我們建議您遵循這些最佳實務，以確保您的連線和輸送量已最佳化：
+ **設定 CQL 查詢輸送量調校。**
Amazon Keyspaces 每秒支援每個 TCP 連線最多 3，000 個 CQL 查詢，但驅動程式可以建立的連線數量沒有限制。
大多數開放原始碼 Cassandra 驅動程式會建立連至 Cassandra 的連線集區，並透過該連線集區進行負載平衡查詢。Amazon Keyspaces 向驅動程式公開 9 個對等 IP 地址。大多數驅動程式的預設行為是建立與每個對等 IP 地址的單一連線。因此，使用預設設定的驅動程式 CQL 查詢輸送量上限為每秒 27，000 個 CQL 查詢。
若要增加此數量，建議您增加驅動程式在其連線集區中維護的每個 IP 地址的連線數量。例如，將每個 IP 地址的最大連線數設定為 2 會將驅動程式的最大輸送量加倍至每秒 54，000 個 CQL 查詢。
+ **最佳化您的單一節點連線。**
根據預設，大多數開放原始碼 Cassandra 驅動程式會在建立工作階段時，建立與`system.peers`資料表中公告之每個 IP 地址的一或多個連線。不過，某些組態可能會導致驅動程式連線到單一 Amazon Keyspaces IP 地址。如果驅動程式嘗試對等節點進行 SSL 主機名稱驗證 （例如 DataStax Java 驅動程式），或透過 VPC 端點連線時，可能會發生這種情況。
若要取得與多個 IP 地址連線的驅動程式相同的可用性和效能，建議您執行下列動作：
+ 根據所需的用戶端輸送量，將每個 IP 的連線數增加到 9 或更高。
+ 建立自訂重試政策，以確保重試在相同的節點上執行。如需詳細資訊，請參閱
[如何在 Amazon Keyspaces 中設定連線的重試政策](connections.md#connections.retry-policies).
+ 如果您使用 VPC 端點，請授予用於連線至 Amazon Keyspaces 的 IAM 實體存取許可，以查詢 VPC 以取得端點和網路介面資訊。這可改善負載平衡並增加讀取/寫入輸送量。如需詳細資訊，請參閱[使用界面 VPC 端點資訊填入`system.peers`資料表項目](vpc-endpoints.md#system_peers)。
### 我在資料匯入期間收到寫入逾時錯誤
**使用 `cqlsh``COPY`命令上傳資料時，您會收到逾時錯誤。**
```
Failed to import 1 rows: WriteTimeout - Error from server: code=1100 [Coordinator node timed out waiting for replica nodes' responses]
message="Operation timed out - received only 0 responses." info={'received_responses': 0, 'required_responses': 2, 'write_type': 'SIMPLE', 'consistency':
'LOCAL_QUORUM'}, will retry later, attempt 1 of 100
```
Amazon Keyspaces 使用 `ReadTimeout`和 `WriteTimeout`例外狀況來指示寫入請求何時因輸送量容量不足而失敗。為了協助診斷容量不足的例外狀況，Amazon Keyspaces 會在 Amazon CloudWatch 中發佈下列指標。
+ `WriteThrottleEvents`
+ `ReadThrottledEvents`
+ `StoragePartitionThroughputCapacityExceeded`
若要解決資料載入期間容量不足的錯誤，請降低每個工作者的寫入速率或總擷取速率，然後重試上傳資料列。如需詳細資訊，請參閱[步驟 4：設定`cqlsh COPY FROM`設定](bulk-upload-config.md)。如需更強大的資料上傳選項，請考慮使用 DSBulk，可從 [GitHub 儲存庫](https://github.com/datastax/dsbulk)取得。如需逐步說明，請參閱 [教學課程：使用 DSBulk 將資料載入 Amazon Keyspaces](dsbulk-upload.md)。
### 我看不到金鑰空間或資料表的實際儲存大小
**您無法查看金鑰空間或資料表的實際儲存大小。**
若要進一步了解資料表的儲存體大小，請參閱 [在資料表層級評估您的成本](CostOptimization_TableLevelCostAnalysis.md)。您也可以開始計算資料表中的資料列大小，來估計儲存體大小。如需計算資料列大小的詳細指示，請參閱 [估計 Amazon Keyspaces 中的資料列大小](calculating-row-size.md)。
# 對 Amazon Keyspaces 中的資料定義語言錯誤進行故障診斷
建立資源時遇到問題？ 以下是一些常見問題，以及如何解決這些問題。
## 資料定義語言錯誤
Amazon Keyspaces 會以非同步方式執行資料定義語言 (DDL) 操作，例如建立和刪除金鑰空間和資料表。如果應用程式在準備好之前嘗試使用 資源，則操作會失敗。
您可以在 中監控新金鑰空間和資料表的建立狀態 AWS 管理主控台，這表示金鑰空間或資料表何時處於待定或作用中狀態。您也可以透過查詢系統結構描述資料表，以程式設計方式監控新金鑰空間或資料表的建立狀態。金鑰空間或資料表準備就緒時，會顯示在系統結構描述中。
**注意**
若要使用 最佳化金鑰空間的建立 CloudFormation，您可以使用此公用程式將 CQL 指令碼轉換為 CloudFormation 範本。此工具可從 [GitHub 儲存庫](https://github.com/aws/amazon-keyspaces-cql-to-cfn-converter)取得。
**Topics**
+ [金鑰空間建立錯誤](#troubleshooting.cql.keyspace)
+ [資料表建立錯誤](#troubleshooting.cql.table)
+ [我嘗試使用 Amazon Keyspaces point-in-time復原 (PITR) 還原資料表，但還原失敗](#troubleshooting.cql.pitr)
+ [我嘗試使用 INSERT/UPDATE 來編輯自訂存留時間 (TTL) 設定，但操作失敗](#troubleshooting.cql.ttl)
+ [超過資料欄](#troubleshooting.cql.upload)
+ [範圍刪除錯誤](#troubleshooting.cql.rangedelete)
### 我建立了新的金鑰空間，但我無法檢視或存取它
**您從應用程式收到嘗試存取新金鑰空間的錯誤。**
如果您嘗試存取仍在非同步建立的新建立 Amazon Keyspaces 金鑰空間，您會收到錯誤。下列錯誤為範例。
```
InvalidRequest: Error from server: code=2200 [Invalid query] message="unconfigured keyspace mykeyspace"
```
檢查新金鑰空間何時可供使用的建議設計模式是輪詢 Amazon Keyspaces 系統結構描述表 (system\$1schema\$1mcs.\$1)。
如需詳細資訊，請參閱[檢查 Amazon Keyspaces 中的金鑰空間建立狀態](keyspaces-create.md)。
### 我建立了新的資料表，但我無法檢視或存取它
**您從應用程式收到嘗試存取新資料表的錯誤。**
如果您嘗試存取仍在非同步建立的新建立 Amazon Keyspaces 資料表，您會收到錯誤。例如，嘗試查詢尚無法使用的資料表會失敗並顯示`unconfigured table`錯誤。
```
InvalidRequest: Error from server: code=2200 [Invalid query] message="unconfigured table mykeyspace.mytable"
```
嘗試使用 檢視資料表時， 會`sync_table()`失敗`KeyError`。
```
KeyError: 'mytable'
```
檢查新資料表何時可供使用的建議設計模式是輪詢 Amazon Keyspaces 系統結構描述資料表 (system\$1schema\$1mcs.\$1)。
這是所建立資料表的範例輸出。
```
user-at-123@cqlsh:system_schema_mcs> select table_name,status from system_schema_mcs.tables where keyspace_name='example_keyspace' and table_name='example_table';
table_name | status
------------+----------
example_table | CREATING
(1 rows)
```
這是作用中資料表的範例輸出。
```
user-at-123@cqlsh:system_schema_mcs> select table_name,status from system_schema_mcs.tables where keyspace_name='example_keyspace' and table_name='example_table';
table_name | status
------------+----------
example_table | ACTIVE
(1 rows)
```
如需詳細資訊，請參閱[在 Amazon Keyspaces 中檢查資料表建立狀態](tables-create.md)。
### 我嘗試使用 Amazon Keyspaces point-in-time復原 (PITR) 還原資料表，但還原失敗
如果您嘗試使用point-in-time復原 (PITR) 還原 Amazon Keyspaces 資料表，而且您看到還原程序開始但未成功完成，您可能尚未設定此特定資料表還原程序所需的所有必要許可。
除了使用者許可之外，Amazon Keyspaces 可能需要許可，才能代表您委託人在還原程序期間執行動作。如果資料表使用客戶受管金鑰加密，或者您使用限制傳入流量的 IAM 政策，就會發生這種情況。
例如，如果您在 IAM 政策中使用條件索引鍵來限制來源流量至特定端點或 IP 範圍，則還原操作會失敗。若要允許 Amazon Keyspaces 代表您委託人執行資料表還原操作，您必須在 IAM 政策中新增`aws:ViaAWSService`全域條件金鑰。
如需還原資料表之許可的詳細資訊，請參閱 [設定 Amazon Keyspaces PITR 的還原資料表 IAM 許可](howitworks_restore_permissions.md)。
### 我嘗試使用 INSERT/UPDATE 來編輯自訂存留時間 (TTL) 設定，但操作失敗
如果您嘗試插入或更新自訂 TTL 值，操作可能會失敗，並出現下列錯誤。
```
TTL is not yet supported.
```
若要使用 或 `INSERT``UPDATE`操作指定資料列或資料欄的自訂 TTL 值，您必須先為資料表啟用 TTL。您可以使用`ttl`自訂屬性為資料表啟用 TTL。
如需啟用資料表自訂 TTL 設定的詳細資訊，請參閱 [使用自訂存留時間 (TTL) 更新資料表](TTL-how-to-enable-custom-alter.md)。
### 我嘗試將資料上傳至 Amazon Keyspaces 資料表，並收到超過資料欄數量的錯誤
**您正在上傳資料，並已超過可同時更新的欄數。**
當您的資料表結構描述超過 350 KB 的大小上限時，就會發生此錯誤。如需詳細資訊，請參閱[Amazon Keyspaces 配額 （適用於 Apache Cassandra)](quotas.md)。
### 我嘗試刪除 Amazon Keyspaces 資料表中的資料，但該範圍的刪除失敗
**您嘗試依分割區索引鍵刪除資料，並收到範圍刪除錯誤。**
當您嘗試在一個刪除操作中刪除超過 1，000 個資料列時，就會發生此錯誤。
```
Range delete requests are limited by the amount of items that can be deleted in a single range.
```
如需詳細資訊，請參閱[刪除範圍](functional-differences.md#functional-differences.range-delete)。
若要在單一分割區中刪除超過 1，000 個資料列，請考慮下列選項。
+ 依分割區刪除 – 如果大部分分割區少於 1，000 個資料列，您可以嘗試依分割區刪除資料。如果分割區包含超過 1，000 個資料列，請改為嘗試由叢集資料欄刪除 。
+ 透過叢集資料欄刪除 – 如果您的模型包含多個叢集資料欄，您可以使用資料欄階層來刪除多個資料列。叢集資料欄是一種巢狀結構，您可以透過對頂層資料欄操作來刪除許多資料列。
+ 依個別資料列刪除 – 您可以逐一查看資料列，並依其完整的主索引鍵 （分割區資料欄和叢集資料欄） 刪除每一列。
+ 最佳實務是考慮跨分割區分割資料列 – 在 Amazon Keyspaces 中，建議您將輸送量分散到資料表分割區。這會將資料和存取平均分配到實體資源，以提供最佳輸送量。如需詳細資訊，請參閱[資料建模最佳實務：設計資料模型的建議](data-modeling.md)。
當您規劃大量工作負載的刪除操作時，也請考慮下列建議。
+ 使用 Amazon Keyspaces，分割區可以包含幾乎沒有限制的資料列數目。這可讓您擴展分割區「比傳統的 100 MB Cassandra 指引更寬」。時間序列或分類帳隨著時間經過 1 GB 的資料成長並不罕見。
+ 使用 Amazon Keyspaces，當您必須為繁重的工作負載執行刪除操作時，無需考慮任何壓縮策略或墓地。您可以視需要刪除任意數量的資料，而不會影響讀取效能。