Amazon QLDB 分類帳的基本操作 - Amazon Quantum 賬本數據庫（AmazonQLDB）
建立分類帳描述分類帳更新分類帳更新分類帳權限模式刪除分類帳列出分類帳

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

Amazon QLDB 分類帳的基本操作

重要

支援結束通知：現有客戶將能夠使用 Amazon，QLDB直到 2025 年 7 月 31 日終止支援為止。有關更多詳細信息，請參閱將 Amazon QLDB 分類帳遷移到 Amazon Aurora 郵政. SQL

您可以使用QLDBAPI或 AWS Command Line Interface (AWS CLI) 在 Amazon QLDB 中建立、更新和刪除分類帳。您也可以列出科目中的所有分類帳，或取得特定分類帳的相關資訊。

下列主題提供簡短程式碼範例，顯示使用 AWS SDK for Java 和的分類帳作業的一般步驟 AWS CLI。

如需在完整範例應用程式中示範這些作業的程式碼範例，請參閱下列開始使用驅動程式教學課程和 GitHub 儲存庫：

建立分類帳

使用此作CreateLedger業在您的帳戶中建立分類帳 AWS 帳戶。您必須提供以下信息：

  • 分類帳名稱 — 您要在帳戶中建立的分類帳名稱。名稱在目 AWS 區域前的所有分類帳中必須是唯一的。

    分類帳名稱的命名限制已在中定義Amazon 的配額和限制 QLDB。

  • 權限模式 — 要分配給分類帳的權限模式。請選擇下列其中一個選項：

    • 允許全部 — 一種舊有權限模式，可針對分類帳啟用API層級精細度的存取控制。

      此模式允許具有此分類帳SendCommandAPI權限的使用者在指定分類帳中的任何表上執行所有 PartiQL 命令 (因此ALLOW_ALL)。此模式會忽略您為總帳建立的任何資料表層級或命令層級IAM權限原則。

    • 標準 — (建議) 一種權限模式，可針對分類帳、表格和 PartiQL 命令以更精細的粒度啟用存取控制。我們強烈建議您使用此權限模式，以最大限度地提高分類帳資料的安全性。

      依預設，此模式會拒絕在此分類帳中的任何資料表上執行任何 PartiQL 命令的所有請求。若要允許 PartiQL 命令，除了分類帳的IAM權限之外，您還必須針對特定資料表資源和 PartiQL 動作建立SendCommandAPI權限原則。如需相關資訊，請參閱開始使用 Amazon 的標準許可模式 QLDB。

  • 刪除保護 — (選擇性) 防止任何使用者刪除分類帳的旗標。如果未在分類帳建立期間指定，則預設會啟用此功能 (true)。

    如果已啟用刪除保護，則必須先停用該功能才能刪除分類帳。您可以使用將旗標設定為的UpdateLedger作業來停用它false。

  • AWS KMS key— (選擇性) in AWS Key Management Service (AWS KMS) 用於靜態資料加密的金鑰。選擇下列其中一種類型 AWS KMS keys：

    • AWS 擁有的KMS金鑰 — 使用代表您擁有和管理 AWS 的KMS金鑰。

      如果您未在分類帳建立期間定義此參數，則分類帳會依預設使用此型態的索引鍵。您也可以使用字串AWS_OWNED_KMS_KEY來指定此金鑰類型。此選項不需要額外的設定。

    • 客戶管理KMS金鑰 — 在您建立、擁有和管理的帳戶中使用對稱加密KMS金鑰。QLDB不支援非對稱金鑰。

      此選項會要求您建立KMS金鑰或使用帳戶中現有的金鑰。如需有關建立客戶管理金鑰的指示，請參閱AWS Key Management Service 開發人員指南中的建立對稱加密KMS金鑰。

      您可以使用 ID、別名或 Amazon 資源名稱 (ARN) 來指定客戶受管KMS金鑰。若要深入了解，請參閱AWS Key Management Service 開發人員指南中的金鑰識別碼 (KeyId)。

      注意

      不支援跨區域金鑰。指定的KMS密鑰必須與您的分類帳 AWS 區域 相同。

    如需詳細資訊，請參閱 Amazon 中的靜態加密 QLDB。

  • 標籤 — (選擇性) 透過附加標籤做為鍵值配對，將中繼資料新增至分類帳。您可以將標籤新增至分類帳，以協助組織和識別標籤。如需詳細資訊，請參閱 標記 Amazon QLDB 資源。

在創建分類帳並將其狀態設置QLDB為之前，該分類帳尚未準備好使用ACTIVE。

若要使用 AWS SDK for Java

  1. 建立 AmazonQLDB 類別的執行個體。

  2. 建立 CreateLedgerRequest 類別的執行個體，以提供請求資訊。

    您必須提供分類帳名稱和權限模式。

  3. 以參數形式提供請求物件，以便執行 createLedger 方法。

createLedger請求會傳回包含分類帳相關資訊的CreateLedgerResult物件。如需在建立分類帳後使用DescribeLedger作業檢查分類帳狀態的範例，請參閱下一節。

下列範例會示範前述步驟。

範例 — 使用預設組態設定
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
CreateLedgerRequest request = new CreateLedgerRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD);
CreateLedgerResult result = client.createLedger(request);
注意

如果未指定分類帳，則會使用下列預設設定：

  • 刪除保護 — 已啟用 (true)。

  • KMSkey- AWS 擁有的KMS密鑰。

範例 — 禁用刪除保護，使用客戶管理的KMS密鑰，並附加標籤
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();

Map<String, String> tags = new HashMap<>();
tags.put("IsTest", "true");
tags.put("Domain", "Test");

CreateLedgerRequest request = new CreateLedgerRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD)
        .withDeletionProtection(false)
        .withKmsKey("arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
        .withTags(tags);
CreateLedgerResult result = client.createLedger(request);

使用預設組態設定建vehicle-registration立名為的新分類帳。

範例 
aws qldb create-ledger --name vehicle-registration --permissions-mode STANDARD
注意

如果未指定分類帳，則會使用下列預設設定：

  • 刪除保護 — 已啟用 (true)。

  • KMSkey- AWS 擁有的KMS密鑰。

或者，建立名為停vehicle-registration用刪除保護、使用指定客戶管理KMS金鑰並具有指定標籤的新分類帳。

範例 
aws qldb create-ledger \
    --name vehicle-registration \
    --no-deletion-protection \
    --permissions-mode STANDARD \
    --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --tags IsTest=true,Domain=Test

您也可以使用AWS CloudFormation樣版來建立分類帳。如需更多資訊，請參閱《AWS CloudFormation 使用指南》中的 AWSQLDB：:: 分類帳資源。

描述分類帳

使用此作DescribeLedger業可檢視分類帳的詳細資訊。您必須提供分類帳名稱。DescribeLedger 中輸出的格式與 CreateLedger 相同。其包含下列資訊：

  • 分類帳名稱 — 您要說明的分類帳名稱。

  • ARN— 分類帳的 Amazon 資源名稱 (ARN)，格式如下。

    arn:aws:qldb:aws-region:account-id:ledger/ledger-name

  • 刪除保護 — 指出刪除保護功能是否已啟用的旗標。

  • 建立日期與時間 — 建立分類帳時的日期與時間 (以紀元時間格式表示)。

  • 狀態 — 分類帳的目前狀態。這可以是下列其中一個值：

    • CREATING

    • ACTIVE

    • DELETING

    • DELETED

  • 權限模式 — 指派給分類帳的權限模式。這可以是下列其中一個值：

    • ALLOW_ALL— 舊版權限模式，可針對分類帳啟用API層級精細度的存取控制。

    • STANDARD— 一種權限模式，可對分類帳、資料表和 PartiQL 命令進行更精細的存取控制。

  • 加密說明 — 分類帳中靜態資料加密的相關資訊。這包括以下項目：

    • AWS KMS key ARN— 分ARN類帳用於靜態加密的客戶管理KMS金鑰。如果未定義，則分類帳會使用 AWS 擁有的KMS金鑰進行加密。

    • 加密狀態 — 分類帳的靜態加密目前的狀態。這可以是下列其中一個值：

      • ENABLED— 使用指定的金鑰完全啟用加密。

      • UPDATING— 正在處理指定的金鑰變更。

        中的主要變更QLDB是非同步的。在處理金鑰變更時，可完全存取分類帳，而不會造成任何效能影響。更新金鑰所需的時間長度視分類帳大小而有所不同。

      • KMS_KEY_INACCESSIBLE— 無法存取指定的客戶管理KMS金鑰，且分類帳會受損。金鑰已停用或刪除，或是金鑰的授權遭到撤銷。當分類帳受損時，它無法訪問，並且不接受任何讀取或寫入請求。

        在您還原金鑰的授權之後，或重新啟用已停用的金鑰之後，受損的分類帳會自動返回作用中狀態。但是，刪除客戶管理的KMS金鑰是不可逆轉的。刪除金鑰後，您將無法再存取受該金鑰保護的分類帳，而且資料永久無法復原。

    • 無法存取 AWS KMS key — 在發生錯誤時，KMS金鑰首次無法存取時，以紀元時間格式顯示的日期和時間。

      如果KMS密鑰是可訪問的，則這是未定義的。

    如需詳細資訊，請參閱 Amazon 中的靜態加密 QLDB。

注意

建立QLDB分類帳後，當分類帳的狀態從變更為時，便可供使CREATING用ACTIVE。

若要使用描述分類帳 AWS SDK for Java

  1. 建立 AmazonQLDB 類別的執行個體。或者，您可以使用為CreateLedger請求實例化的AmazonQLDB客戶端的相同實例。

  2. 建立DescribeLedgerRequest類別的執行環境，並提供您要說明的分類帳名稱。

  3. 以參數形式提供請求物件，以便執行 describeLedger 方法。

  4. describeLedger請求會傳回包含分類帳目前相關資訊的DescribeLedgerResult物件。

下列程式碼範例示範前述步驟。您可以隨時調用客戶端的describeLedger方法以獲取分類帳信息。

範例 
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
DescribeLedgerRequest request = new DescribeLedgerRequest().withName(ledgerName);
DescribeLedgerResult result = client.describeLedger(request);
System.out.printf("%s: ARN: %s \t State: %s \t CreationDateTime: %s \t DeletionProtection: %s
                   \t PermissionsMode: %s \t EncryptionDescription: %s",
        result.getName(),
        result.getArn(),
        result.getState(),
        result.getCreationDateTime(),
        result.getDeletionProtection(),
        result.getPermissionsMode(),
        result.getEncryptionDescription());

說明您剛建立的vehicle-registration分類帳。

範例 
aws qldb describe-ledger --name vehicle-registration

更新分類帳

UpdateLedger作業目前可讓您變更現有分類帳的下列組態設定：

  • 刪除保護 — 可防止任何使用者刪除分類帳的旗標。如果啟用此功能，您必須先將旗標設定為來停用此功能，false然後才能刪除分類帳。

    如果未定義此參數，則不會變更分類帳的刪除保護設定。

  • AWS KMS key— 中的密鑰 AWS Key Management Service （AWS KMS）用於靜態數據的加密。如果未定義此參數，則不會對分類帳的KMS索引鍵進行任何變更。

    注意

    Amazon 於 2021 年 7 月 22 日QLDB推出了 AWS KMS keys 對管理的客戶的支持。依預設，在啟動之前建立的任何分類帳都會 AWS 擁有的金鑰 受到保護，但目前不符合使用客戶管理金鑰進行靜態加密的資格。

    您可以在QLDB控制台上查看分類帳的創建時間。

    使用下列其中一個選項：

    • AWS 擁有的KMS金鑰 — 使用代表您擁有和管理 AWS 的KMS金鑰。若要使用此類型的金鑰，請指定此AWS_OWNED_KMS_KEY參數的字串。此選項不需要額外的設定。

    • 客戶管理KMS金鑰 — 在您建立、擁有和管理的帳戶中使用對稱加密KMS金鑰。QLDB不支援非對稱金鑰。

      此選項會要求您建立KMS金鑰或使用帳戶中現有的金鑰。如需有關建立客戶管理金鑰的指示，請參閱AWS Key Management Service 開發人員指南中的建立對稱加密KMS金鑰。

      您可以使用 ID、別名或 Amazon 資源名稱 (ARN) 來指定客戶受管KMS金鑰。若要深入了解，請參閱AWS Key Management Service 開發人員指南中的金鑰識別碼 (KeyId)。

      注意

      不支援跨區域金鑰。指定的KMS密鑰必須與您的分類帳 AWS 區域 相同。

    中的主要變更QLDB是非同步的。在處理金鑰變更時，可完全存取分類帳，而不會造成任何效能影響。

    您可以視需要經常切換金鑰，但更新金鑰所花費的時間長度視分類帳大小而有所不同。您可以使用此DescribeLedger操作來檢查靜態加密狀態。

    如需詳細資訊，請參閱 Amazon 中的靜態加密 QLDB。

UpdateLedger 中輸出的格式與 CreateLedger 相同。

若要更新分類帳，請使用 AWS SDK for Java

  1. 建立 AmazonQLDB 類別的執行個體。

  2. 建立 UpdateLedgerRequest 類別的執行個體，以提供請求資訊。

    您必須提供分類帳名稱以及用於刪除保護的新布林值，或為KMS金鑰提供新的字串值。

  3. 以參數形式提供請求物件，以便執行 updateLedger 方法。

下列程式碼範例會示範前述步驟。updateLedger請求會傳回已更新分類帳相關資訊的UpdateLedgerResult物件。

範例 — 禁用刪除保護
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withDeletionProtection(false);
UpdateLedgerResult result = client.updateLedger(request);
範例 — 使用客戶管理的KMS密鑰
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withKmsKey("arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
UpdateLedgerResult result = client.updateLedger(request);
範例 — 使用 AWS 擁有的KMS密鑰
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withKmsKey("AWS_OWNED_KMS_KEY")
UpdateLedgerResult result = client.updateLedger(request);

如果您的vehicle-registration分類帳已啟用刪除保護，則必須先將其停用，然後才能刪除它。

範例 
aws qldb update-ledger --name vehicle-registration --no-deletion-protection

您也可以變更分類帳的靜態加密設定，以使用客戶管理的KMS金鑰。

範例 
aws qldb update-ledger --name vehicle-registration --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

或者，您可以將靜態加密設定變更為使用 AWS 擁有的KMS金鑰。

範例 
aws qldb update-ledger --name vehicle-registration --kms-key AWS_OWNED_KMS_KEY

更新分類帳權限模式

此UpdateLedgerPermissionsMode作業可讓您變更現有分類帳的權限模式。請選擇下列其中一個選項：

  • 允許全部 — 一種舊有權限模式，可針對分類帳啟用API層級精細度的存取控制。

    此模式允許具有此分類帳SendCommandAPI權限的使用者在指定分類帳中的任何表上執行所有 PartiQL 命令 (因此ALLOW_ALL)。此模式會忽略您為總帳建立的任何資料表層級或命令層級IAM權限原則。

  • 標準 — (建議) 一種權限模式，可針對分類帳、表格和 PartiQL 命令以更精細的粒度啟用存取控制。我們強烈建議您使用此權限模式，以最大限度地提高分類帳資料的安全性。

    依預設，此模式會拒絕在此分類帳中的任何資料表上執行任何 PartiQL 命令的所有請求。若要允許 PartiQL 命令，除了分類帳的IAM權限之外，您還必須針對特定資料表資源和 PartiQL 動作建立SendCommandAPI權限原則。如需相關資訊，請參閱開始使用 Amazon 的標準許可模式 QLDB。

重要

切換至STANDARD權限模式之前，您必須先建立所有必要的IAM原則和資料表標記，以避免對使用者造成干擾。要了解更多信息，請繼續移轉至標準權限模式。

若要使用更新分類帳權限模式 AWS SDK for Java

  1. 建立 AmazonQLDB 類別的執行個體。

  2. 建立 UpdateLedgerPermissionsModeRequest 類別的執行個體，以提供請求資訊。

    您必須提供分類帳名稱以及權限模式的新字串值。

  3. 以參數形式提供請求物件，以便執行 updateLedgerPermissionsMode 方法。

下列程式碼範例會示範前述步驟。updateLedgerPermissionsMode請求會傳回已更新分類帳相關資訊的UpdateLedgerPermissionsModeResult物件。

範例 — 分配標準權限模式
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerPermissionsModeRequest request = new UpdateLedgerPermissionsModeRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD);
UpdateLedgerPermissionsModeResult result = client.updateLedgerPermissionsMode(request);

將STANDARD權限模式指定給vehicle-registration分類帳。

範例 
aws qldb update-ledger-permissions-mode --name vehicle-registration --permissions-mode STANDARD

移轉至標準權限模式

若要移轉至STANDARD權限模式，我們建議您分析您的QLDB存取模式並新增IAM政策，以授與使用者存取其資源的適當權限。

在切換至STANDARD權限模式之前，您必須先建立所有必要的IAM原則和表格標籤。否則，切換權限模式可能會中斷使用者，直到您建立正確的IAM策略或將權限模式還原為ALLOW_ALL止。如需有關建立這些原則的資訊，請參閱開始使用 Amazon 的標準許可模式 QLDB。

您也可以使用 AWS 受管策略來授與所有QLDB資源的完整存取權。AmazonQLDBFullAccess和受AmazonQLDBConsoleFullAccess管理的原則包括所有QLDB動作，包括所有 PartiQL 動作。將其中一個原則附加至主參與者等同於該主參與者的ALLOW_ALL權限模式。如需詳細資訊，請參閱 AWS Amazon 的受管政策 QLDB。

刪除分類帳

使用此DeleteLedger作業刪除分類帳及其所有內容。刪除分類帳是無法回復的作業。

如果已啟用分類帳的刪除保護，您必須先停用它，然後才能刪除分類帳。

當您發出DeleteLedger請求時，分類帳的狀態會從變更ACTIVE為DELETING。刪除分類帳可能需要一段時間，具體取決於分類帳使用的存儲量。DeleteLedger作業結束時，中不再存在QLDB分類帳。

若要刪除分類帳，請使用 AWS SDK for Java

  1. 建立 AmazonQLDB 類別的執行個體。

  2. 建立DeleteLedgerRequest類別的執行環境，並提供您要刪除的分類帳名稱。

  3. 以參數形式提供請求物件，以便執行 deleteLedger 方法。

下列程式碼範例示範前述步驟。

範例 
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
DeleteLedgerRequest request = new DeleteLedgerRequest().withName(ledgerName);
DeleteLedgerResult result = client.deleteLedger(request);

刪除分vehicle-registration類帳。

範例 
aws qldb delete-ledger --name vehicle-registration

列出分類帳

ListLedgers作業會傳回目前 AWS 帳戶 與區域之所有QLDB分類帳的彙總資訊。

若要使用下列步驟列出您帳戶中的分類帳， AWS SDK for Java

  1. 建立 AmazonQLDB 類別的執行個體。

  2. 建立 ListLedgersRequest 類別的執行個體。

    如果您在先前ListLedgers呼叫的回應NextToken中收到的值，您必須在此要求中提供該值，才能取得下一頁結果。

  3. 以參數形式提供請求物件，以便執行 listLedgers 方法。

  4. 該listLedgers請求返回一個ListLedgersResult對象。這個對象有一個對LedgerSummary象的列表和一個分頁令牌，指示是否有更多的結果可用：

    • 如果NextToken為空，則表示結果的最後一頁已處理，並且沒有更多結果。

    • 如果不NextToken是空的，則會有更多可用的結果。若要擷取結果的下一頁，請在後續ListLedgers呼叫NextToken中使用的值。

下列程式碼範例示範前述步驟。

範例 
AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
List<LedgerSummary> ledgerSummaries = new ArrayList<>();
String nextToken = null;
do {
    ListLedgersRequest request = new ListLedgersRequest().withNextToken(nextToken);
    ListLedgersResult result = client.listLedgers(request);
    ledgerSummaries.addAll(result.getLedgers());
    nextToken = result.getNextToken();
} while (nextToken != null);

列出目前 AWS 帳戶 與區域中的所有分類帳。

範例 
aws qldb list-ledgers