Amazon QLDB 分類帳的基本操作

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

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

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

• Java: 教程 | GitHub 儲存庫

• Node.js: 教學課程 | GitHub 儲存庫

• 蟒蛇：教程 | GitHub 存儲庫

建立分類帳

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

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

  分類帳名稱的命名限制是在亞馬遜 QLDB 中的配額和限制。

• 許可模式 — 要指派給分類帳的許可模式。請選擇下列其中一個選項：

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

    此模式允許具有指定分類帳 SendCommand API 許可的使用者 (因此為 ALLOW_ALL)，在此分類帳中的任何資料表上執行所有 PartiQL 命令。此模式會忽略您為分類帳建立之任何資料表層級或命令層級 IAM 許可政策。

  • STAND@@ ARD — (建議) 一種許可模式，可使用更細的層級啟用對分類帳、資料表和 PartiQL 命令的存取控制。強烈建議您使用此許可模式來最大化分類帳資料的安全性。

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

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

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

• AWS KMS key— (選擇性) inAWS 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 Resource Name (ARN)，指定客戶受管 KMS 金鑰。若要深入了解，請參閱AWS Key Management Service開發人員指南中的金鑰識別碼 (KeyId)。

    注意

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

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

• Tags (選用) 藉由連接標籤作為鍵值對，將中繼資料新增至分類帳。您可以將標籤新增至分類帳，協助整理和識別。如需詳細資訊，請參閱 標記 Amazon QLDB 資源。

分類帳尚未準備就緒，直到 QLDB 建立分類帳並將其狀態設為ACTIVE。

建立分類帳 (Java)

若要使用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)。

• KMS 金鑰 —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);

創建分類帳（AWS CLI）

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

範例

aws qldb create-ledger --name vehicle-registration --permissions-mode STANDARD

注意

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

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

• KMS 金鑰 —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樣版來建立分類帳。若要取得更多資訊，請參閱《AWS CloudFormation使用指南》中的AWS::QLDB::Ledger資源。

描述分類帳

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

• 分類帳名稱 — 您要描述分類帳的名稱。

• ARN — 分類帳的 Amazon Resource Name (ARN)，格式為下列格式。

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

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

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

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

  • CREATING

  • ACTIVE

  • DELETING

  • DELETED

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

  • ALLOW_ALL— 一種舊版許可模式，可使用 API 層級精細程度啟用對分類帳的存取控制。

  • STANDARD— 一種許可模式，可使用更細的層級啟用對分類帳、資料表和 PartiQL 命令的存取控制。

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

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

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

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

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

      QLDB 中的關鍵變更是非同步的。在處理金鑰變更時，可以完全存取分類帳，而不會造成任何效能影響。更新金鑰所需的時間量因分類帳大小而異。

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

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

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

    如果 KMS 金鑰可存取，則未定義此選項。

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

注意

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

描述一個分類帳（Java）

若要使用描述分類帳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());

描述分類帳（AWS CLI）

描述您剛才建立vehicle-registration分類帳。

範例

aws qldb describe-ledger --name vehicle-registration

更新分類帳

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

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

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

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

  注意

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

  您可以在 QLDB 主控台上檢視分類帳的建立時間。

  使用下列其中一個選項：

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

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

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

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

    注意

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

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

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

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

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

更新分類帳 (Java)

若要更新分類帳，請使用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);

更新分類帳 (AWS CLI)

如果您的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 層級精細程度啟用對分類帳的存取控制。

  此模式允許具有指定分類帳 SendCommand API 許可的使用者 (因此為 ALLOW_ALL)，在此分類帳中的任何資料表上執行所有 PartiQL 命令。此模式會忽略您為分類帳建立之任何資料表層級或命令層級 IAM 許可政策。

• STAND@@ ARD — (建議) 一種許可模式，可使用更細的層級啟用對分類帳、資料表和 PartiQL 命令的存取控制。強烈建議您使用此許可模式來最大化分類帳資料的安全性。

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

重要

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

更新分類帳權限模式 (Java)

若要更新分類帳權限模式，請使用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);

更新分類帳權限模式 (AWS CLI)

將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 中就不再存在分類帳。

刪除分類帳 (Java)

若要刪除分類帳，請使用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);

刪除分類帳 (AWS CLI)

刪除分vehicle-registration類帳。

範例

aws qldb delete-ledger --name vehicle-registration

清單分類帳

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

列出分類帳 (Java)

若要使用下列步驟列出您帳戶中的分類帳，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 CLI)

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

範例

aws qldb list-ledgers