本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用範例應用程式教學課程開始使用 Amazon QLDB
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在本教學課程中，您會使用 Amazon QLDB 驅動程式搭配 AWS SDK 來建立 QLDB 分類帳，並填入範例資料。驅動程式可讓您的應用程式使用交易資料 API 與 QLDB 互動。 AWS 開發套件支援與 QLDB 資源管理 API 的互動。
您在此案例中建立的範例分類帳是機動車輛 (DMV) 資料庫部門，可追蹤車輛註冊的完整歷史資訊。下列主題說明如何新增車輛註冊、修改和檢視這些註冊變更的歷史記錄。本指南也說明如何以密碼編譯方式驗證註冊文件，並透過清除資源和刪除範例分類帳來結束。
此範例應用程式教學課程適用於下列程式設計語言。
**Topics**
+ [Java 教學課程](getting-started.java.tutorial.md)
+ [Node.js 教學課程](getting-started.nodejs.tutorial.md)
+ [Python 教學課程](getting-started.python.tutorial.md)
# Amazon QLDB Java 教學課程
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此教學課程範例應用程式的實作中，您可以使用 Amazon QLDB 驅動程式搭配 適用於 Java 的 AWS SDK 來建立 QLDB 分類帳，並填入範例資料。
當您完成本教學課程時，您可以參考管理 API [適用於 Java 的 AWS SDK 操作的 API 參考](https://docs.aws.amazon.com/sdk-for-java/latest/reference/)。對於交易資料操作，您可以參考適用於 [Java 的 QLDB 驅動程式 API 參考](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/index.html)。
**注意**
在適用的情況下，某些教學課程步驟對於每個支援的主要版本的 QLDB Java 驅動程式都有不同的命令或程式碼範例。
**Topics**
+ [
# 安裝 Amazon QLDB Java 範例應用程式
](sample-app.java.md)
+ [
# 步驟 1：建立新的分類帳
](getting-started.java.step-1.md)
+ [
# 步驟 2：測試與分類帳的連線
](getting-started.java.step-2.md)
+ [
# 步驟 3：建立資料表、索引和範例資料
](getting-started.java.step-3.md)
+ [
# 步驟 4：查詢分類帳中的資料表
](getting-started.java.step-4.md)
+ [
# 步驟 5：修改分類帳中的文件
](getting-started.java.step-5.md)
+ [
# 步驟 6：檢視文件的修訂歷史記錄
](getting-started.java.step-6.md)
+ [
# 步驟 7：驗證分類帳中的文件
](getting-started.java.step-7.md)
+ [
# 步驟 8：在分類帳中匯出和驗證日誌資料
](getting-started.java.step-8.md)
+ [
# 步驟 9 （選用）：清除資源
](getting-started.java.step-9.md)
# 安裝 Amazon QLDB Java 範例應用程式
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
本節說明如何為step-by-step Java 教學課程安裝和執行提供的 Amazon QLDB 範例應用程式。此範例應用程式的使用案例是機動車輛 (DMV) 資料庫部門，可追蹤車輛註冊的完整歷史資訊。
Java 的 DMV 範例應用程式是 GitHub 儲存庫 [aws-samples/amazon-qldb-dmv-sample-java](https://github.com/aws-samples/amazon-qldb-dmv-sample-java) 中的開放原始碼。
## 先決條件
開始之前，請務必完成適用於 Java 的 QLDB 驅動程式[先決條件](getting-started.java.md#getting-started.java.prereqs)。這包含下列項目：
1. 註冊 AWS。
1. 建立具有適當 QLDB 許可的使用者。若要完成本教學課程中的所有步驟，您需要透過 QLDB API 完整存取您的分類帳資源。
1. 如果您使用的不是 IDE AWS Cloud9，請安裝 Java 並授予程式設計存取權以進行開發。
## 安裝
下列步驟說明如何使用本機開發環境下載和設定範例應用程式。或者，您可以使用 AWS Cloud9 做為您的 IDE 來自動化範例應用程式的設定，以及佈建開發資源的 CloudFormation 範本。
### 本機開發環境
這些指示說明如何使用您自己的資源和開發環境下載和安裝 QLDB Java 範例應用程式。
**下載並執行範例應用程式**
1. 輸入下列命令，從 GitHub 複製範例應用程式。
------
#### [ 2.x ]
```
git clone https://github.com/aws-samples/amazon-qldb-dmv-sample-java.git
```
------
#### [ 1.x ]
```
git clone -b v1.2.0 https://github.com/aws-samples/amazon-qldb-dmv-sample-java.git
```
------
此套件包含 Gradle 組態和來自 的完整程式碼[Java 教學課程](getting-started.java.tutorial.md)。
1. 載入並執行提供的應用程式。
+ 如果您使用的是 Eclipse：
1. 啟動 Eclipse，然後在 **Eclipse** 功能表上，選擇**檔案**、**匯入**，然後選擇**現有 Gradle 專案**。
1. 在專案根目錄中，瀏覽並選取包含 `build.gradle` 檔案的應用程式目錄。然後，選擇**完成**以使用預設的 Gradle 設定進行匯入。
1. 您可以嘗試執行`ListLedgers`程式做為範例。開啟 `ListLedgers.java` 檔案的內容 （按一下滑鼠右鍵） 選單，然後選擇**執行為 Java 應用程式**。
+ 如果您使用的是 IntelliJ：
1. 啟動 IntelliJ，然後在 **IntelliJ** 功能表上，選擇**檔案**，然後選擇**開啟**。
1. 在專案根目錄中，瀏覽並選取包含 `build.gradle` 檔案的應用程式目錄。然後，選擇**確定**。保留預設設定，然後再次選擇**確定**。
1. 您可以嘗試執行`ListLedgers`程式做為範例。開啟 `ListLedgers.java` 檔案的內容 （按一下滑鼠右鍵） 選單，然後選擇**執行 'ListLedgers'**。
1. 前往 [步驟 1：建立新的分類帳](getting-started.java.step-1.md) 以開始教學課程並建立分類帳。
### AWS Cloud9
這些指示說明如何使用 [AWS Cloud9](https://aws.amazon.com/cloud9)做為您的 IDE，自動設定適用於 Java 的 Amazon QLDB 車輛註冊範例應用程式。在本指南中，您可以使用 [CloudFormation](https://aws.amazon.com/cloudformation) 範本來佈建您的開發資源。
如需詳細資訊 AWS Cloud9，請參閱 [AWS Cloud9 使用者指南](https://docs.aws.amazon.com/cloud9/latest/user-guide/)。若要進一步了解 CloudFormation，請參閱 [AWS CloudFormation 使用者指南](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/)。
**Topics**
+ [
#### 第 1 部分：佈建您的 資源
](#sample-app.java.cfn-ac9.step-1)
+ [
#### 第 2 部分：設定您的 IDE
](#sample-app.java.cfn-ac9.step-2)
+ [
#### 第 3 部分：執行 QLDB DMV 範例應用程式
](#sample-app.java.cfn-ac9.step-3)
#### 第 1 部分：佈建您的 資源
在此第一個步驟中，您可以使用 CloudFormation 佈建使用 Amazon QLDB 範例應用程式設定開發環境所需的資源。
**開啟 CloudFormation 主控台並載入 QLDB 範例應用程式範本**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) 開啟 CloudFormation 主控台。
切換到支援 QLDB 的區域。如需完整清單，請參閱 中的 [Amazon QLDB 端點和配額](https://docs.aws.amazon.com/general/latest/gr/qldb.html)*AWS 一般參考*。下列螢幕擷取畫面 AWS 管理主控台 顯示美國東部 （維吉尼亞北部） 為選取的 AWS 區域。
![\[AWS 管理主控台 顯示美國東部 （維吉尼亞北部） 為選取的 AWS 區域。\]](http://docs.aws.amazon.com/zh_tw/qldb/latest/developerguide/images/cfn-ac9/aws-region-us-east-1.png)
1. 在 CloudFormation 主控台上，選擇**建立堆疊**，然後選擇**使用新資源 （標準）**。
1. 在**指定範本**下的**建立堆疊**頁面上，選擇 **Amazon S3 URL**。
1. 輸入下列 URL，然後選擇**下一步**。
```
https://amazon-qldb-assets.s3.amazonaws.com/templates/QLDB-DMV-SampleApp.yml
```
1. 輸入**堆疊名稱** （例如 **qldb-sample-app**)，然後選擇**下一步**。
1. 您可以視需要新增任何標籤，並保留預設選項。然後選擇**下一步**。
1. 檢閱您的堆疊設定，然後選擇**建立堆疊**。 CloudFormation 指令碼可能需要幾分鐘的時間才能完成。
此指令碼會為您的 AWS Cloud9 環境佈建相關聯的 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體，您可用來在本教學課程中執行 QLDB 範例應用程式。它也會將 [aws-samples/amazon-qldb-dmv-sample-java](https://github.com/aws-samples/amazon-qldb-dmv-sample-java/) 儲存庫從 GitHub 複製到您的 AWS Cloud9 開發環境。
#### 第 2 部分：設定您的 IDE
在此步驟中，您已完成雲端開發環境的設定。您可以下載並執行提供的 shell AWS Cloud9 指令碼，以使用範例應用程式的相依性來設定 IDE。
**設定您的 AWS Cloud9 環境**
1. 在 https：//[https://console.aws.amazon.com/cloud9/](https://console.aws.amazon.com/cloud9/) 開啟 AWS Cloud9 主控台。
1. **在您的環境**下，找到名為 **QLDB DMV Sample Application** 之環境的卡片，然後選擇**開啟 IDE**。當基礎 EC2 執行個體啟動時，您的環境可能需要一分鐘才能載入。
您的 AWS Cloud9 環境已預先設定執行教學課程所需的系統相依性。在主控台**的環境**導覽窗格中，確認您看到名為 的資料夾`QLDB DMV Sample Application`。下列 AWS Cloud9 主控台螢幕擷取畫面顯示 QLDB DMV 範例應用程式環境資料夾窗格。
![\[AWS Cloud9 主控台顯示 QLDB DMV 範例應用程式環境資料夾窗格。\]](http://docs.aws.amazon.com/zh_tw/qldb/latest/developerguide/images/cfn-ac9/cloud9-folders.png)
如果您沒有看到導覽窗格，請切換主控台左側**的環境**索引標籤。如果您在窗格中看不到任何資料夾，請使用設定圖示 () 啟用**顯示環境根**目錄![\[Settings icon\]](http://docs.aws.amazon.com/zh_tw/qldb/latest/developerguide/images/settings.png)。
1. 在主控台的底部窗格中，您應該會看到開啟的`bash`終端機視窗。如果您沒有看到，請從主控台頂端的**視窗**功能表中選擇**新終端機**。
1. 接著，下載並執行安裝指令碼以安裝 OpenJDK 8，並在適用時查看 Git 儲存庫中適當的分支。在您在上一個步驟中建立的 AWS Cloud9 終端機中，依序執行下列兩個命令：
------
#### [ 2.x ]
```
aws s3 cp s3://amazon-qldb-assets/setup-scripts/dmv-setup-v2.sh .
```
```
sh dmv-setup-v2.sh
```
------
#### [ 1.x ]
```
aws s3 cp s3://amazon-qldb-assets/setup-scripts/dmv-setup.sh .
```
```
sh dmv-setup.sh
```
------
完成後，您應該會在終端機中看到下列訊息：
```
** DMV Sample App setup completed , enjoy!! **
```
1. 花一點時間瀏覽 中的應用程式程式碼範例 AWS Cloud9，特別是在以下目錄路徑中：`src/main/java/software/amazon/qldb/tutorial`。
#### 第 3 部分：執行 QLDB DMV 範例應用程式
在此步驟中，您將了解如何使用 執行 Amazon QLDB DMV 範例應用程式任務 AWS Cloud9。若要執行範例程式碼，請返回您的 AWS Cloud9 終端機，或如第 *2 部分：設定您的 IDE* 中所執行建立新的終端機視窗。
**執行範例應用程式**
1. 在終端機中執行下列命令，以切換到專案根目錄：
```
cd ~/environment/amazon-qldb-dmv-sample-java
```
請確定您在下列目錄路徑中執行範例。
```
/home/ec2-user/environment/amazon-qldb-dmv-sample-java/
```
1. 下列命令顯示執行每個任務的 Gradle 語法。
```
./gradlew run -Dtutorial=Task
```
例如，執行下列命令來列出您 AWS 帳戶 和目前區域中的所有分類帳。
```
./gradlew run -Dtutorial=ListLedgers
```
1. 前往 [步驟 1：建立新的分類帳](getting-started.java.step-1.md) 以開始教學課程並建立分類帳。
1. （選用） 完成教學課程後，如果您不再需要資源 CloudFormation ，請清除資源。
1. 在 https：//[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) 開啟 CloudFormation 主控台，並刪除您在*第一部分：佈建資源*中建立的堆疊。
1. 也請刪除 CloudFormation 範本為您建立的 AWS Cloud9 堆疊。
# 步驟 1：建立新的分類帳
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步驟中，您會建立新的 Amazon QLDB 分類帳，名稱為 `vehicle-registration`。
**建立新的分類帳**
1. 檢閱下列檔案 (`Constants.java`)，其中包含本教學課程中所有其他程式所使用的常數值。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.dataformat.ion.IonObjectMapper;
import com.fasterxml.jackson.dataformat.ion.ionvalue.IonValueMapper;
/**
* Constant values used throughout this tutorial.
*/
public final class Constants {
public static final int RETRY_LIMIT = 4;
public static final String LEDGER_NAME = "vehicle-registration";
public static final String STREAM_NAME = "vehicle-registration-stream";
public static final String VEHICLE_REGISTRATION_TABLE_NAME = "VehicleRegistration";
public static final String VEHICLE_TABLE_NAME = "Vehicle";
public static final String PERSON_TABLE_NAME = "Person";
public static final String DRIVERS_LICENSE_TABLE_NAME = "DriversLicense";
public static final String VIN_INDEX_NAME = "VIN";
public static final String PERSON_GOV_ID_INDEX_NAME = "GovId";
public static final String VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME = "LicensePlateNumber";
public static final String DRIVER_LICENSE_NUMBER_INDEX_NAME = "LicenseNumber";
public static final String DRIVER_LICENSE_PERSONID_INDEX_NAME = "PersonId";
public static final String JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX = "qldb-tutorial-journal-export";
public static final String USER_TABLES = "information_schema.user_tables";
public static final String LEDGER_NAME_WITH_TAGS = "tags";
public static final IonSystem SYSTEM = IonSystemBuilder.standard().build();
public static final IonObjectMapper MAPPER = new IonValueMapper(SYSTEM);
private Constants() { }
static {
MAPPER.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
}
}
```
------
#### [ 1.x ]
**重要**
對於 Amazon Ion 套件，您必須在`com.amazon.ion`應用程式中使用 命名空間。 適用於 Java 的 AWS SDK 取決於命名空間 下的另一個 Ion 套件`software.amazon.ion`，但這是與 QLDB 驅動程式不相容的舊版套件。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.dataformat.ion.IonObjectMapper;
import com.fasterxml.jackson.dataformat.ion.ionvalue.IonValueMapper;
/**
* Constant values used throughout this tutorial.
*/
public final class Constants {
public static final int RETRY_LIMIT = 4;
public static final String LEDGER_NAME = "vehicle-registration";
public static final String STREAM_NAME = "vehicle-registration-stream";
public static final String VEHICLE_REGISTRATION_TABLE_NAME = "VehicleRegistration";
public static final String VEHICLE_TABLE_NAME = "Vehicle";
public static final String PERSON_TABLE_NAME = "Person";
public static final String DRIVERS_LICENSE_TABLE_NAME = "DriversLicense";
public static final String VIN_INDEX_NAME = "VIN";
public static final String PERSON_GOV_ID_INDEX_NAME = "GovId";
public static final String VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME = "LicensePlateNumber";
public static final String DRIVER_LICENSE_NUMBER_INDEX_NAME = "LicenseNumber";
public static final String DRIVER_LICENSE_PERSONID_INDEX_NAME = "PersonId";
public static final String JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX = "qldb-tutorial-journal-export";
public static final String USER_TABLES = "information_schema.user_tables";
public static final String LEDGER_NAME_WITH_TAGS = "tags";
public static final IonSystem SYSTEM = IonSystemBuilder.standard().build();
public static final IonObjectMapper MAPPER = new IonValueMapper(SYSTEM);
private Constants() { }
static {
MAPPER.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
}
}
```
------
**注意**
此`Constants`類別包含開放原始碼 Jackson `IonValueMapper`類別的執行個體。您可以在執行讀取和寫入交易時使用此映射器來處理 [Amazon Ion](ion.md) 資料。
`CreateLedger.java` 檔案也依賴於下列程式 (`DescribeLedger.java`)，其中描述了您分類帳的目前狀態。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.DescribeLedgerRequest;
import com.amazonaws.services.qldb.model.DescribeLedgerResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Describe a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class DescribeLedger {
public static AmazonQLDB client = CreateLedger.getClient();
public static final Logger log = LoggerFactory.getLogger(DescribeLedger.class);
private DescribeLedger() { }
public static void main(final String... args) {
try {
describe(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to describe a ledger!", e);
}
}
/**
* Describe a ledger.
*
* @param name
* Name of the ledger to describe.
* @return {@link DescribeLedgerResult} from QLDB.
*/
public static DescribeLedgerResult describe(final String name) {
log.info("Let's describe ledger with name: {}...", name);
DescribeLedgerRequest request = new DescribeLedgerRequest().withName(name);
DescribeLedgerResult result = client.describeLedger(request);
log.info("Success. Ledger description: {}", result);
return result;
}
}
```
1. 編譯並執行 `CreateLedger.java`程式，以建立名為 的分類帳`vehicle-registration`。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.client.builder.AwsClientBuilder;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.AmazonQLDBClientBuilder;
import com.amazonaws.services.qldb.model.CreateLedgerRequest;
import com.amazonaws.services.qldb.model.CreateLedgerResult;
import com.amazonaws.services.qldb.model.DescribeLedgerResult;
import com.amazonaws.services.qldb.model.LedgerState;
import com.amazonaws.services.qldb.model.PermissionsMode;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Create a ledger and wait for it to be active.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateLedger {
public static final Logger log = LoggerFactory.getLogger(CreateLedger.class);
public static final Long LEDGER_CREATION_POLL_PERIOD_MS = 10_000L;
public static String endpoint = null;
public static String region = null;
public static AmazonQLDB client = getClient();
private CreateLedger() {
}
/**
* Build a low-level QLDB client.
*
* @return {@link AmazonQLDB} control plane client.
*/
public static AmazonQLDB getClient() {
AmazonQLDBClientBuilder builder = AmazonQLDBClientBuilder.standard();
if (null != endpoint && null != region) {
builder.setEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(endpoint, region));
}
return builder.build();
}
public static void main(final String... args) throws Exception {
try {
client = getClient();
create(Constants.LEDGER_NAME);
waitForActive(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to create the ledger!", e);
throw e;
}
}
/**
* Create a new ledger with the specified ledger name.
*
* @param ledgerName Name of the ledger to be created.
* @return {@link CreateLedgerResult} from QLDB.
*/
public static CreateLedgerResult create(final String ledgerName) {
log.info("Let's create the ledger with name: {}...", ledgerName);
CreateLedgerRequest request = new CreateLedgerRequest()
.withName(ledgerName)
.withPermissionsMode(PermissionsMode.ALLOW_ALL);
CreateLedgerResult result = client.createLedger(request);
log.info("Success. Ledger state: {}.", result.getState());
return result;
}
/**
* Wait for a newly created ledger to become active.
*
* @param ledgerName Name of the ledger to wait on.
* @return {@link DescribeLedgerResult} from QLDB.
* @throws InterruptedException if thread is being interrupted.
*/
public static DescribeLedgerResult waitForActive(final String ledgerName) throws InterruptedException {
log.info("Waiting for ledger to become active...");
while (true) {
DescribeLedgerResult result = DescribeLedger.describe(ledgerName);
if (result.getState().equals(LedgerState.ACTIVE.name())) {
log.info("Success. Ledger is active and ready to use.");
return result;
}
log.info("The ledger is still creating. Please wait...");
Thread.sleep(LEDGER_CREATION_POLL_PERIOD_MS);
}
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.AmazonQLDBClientBuilder;
import com.amazonaws.services.qldb.model.CreateLedgerRequest;
import com.amazonaws.services.qldb.model.CreateLedgerResult;
import com.amazonaws.services.qldb.model.DescribeLedgerResult;
import com.amazonaws.services.qldb.model.LedgerState;
import com.amazonaws.services.qldb.model.PermissionsMode;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Create a ledger and wait for it to be active.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateLedger {
public static final Logger log = LoggerFactory.getLogger(CreateLedger.class);
public static final Long LEDGER_CREATION_POLL_PERIOD_MS = 10_000L;
public static AmazonQLDB client = getClient();
private CreateLedger() { }
/**
* Build a low-level QLDB client.
*
* @return {@link AmazonQLDB} control plane client.
*/
public static AmazonQLDB getClient() {
return AmazonQLDBClientBuilder.standard().build();
}
public static void main(final String... args) throws Exception {
try {
create(Constants.LEDGER_NAME);
waitForActive(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to create the ledger!", e);
throw e;
}
}
/**
* Create a new ledger with the specified ledger name.
*
* @param ledgerName
* Name of the ledger to be created.
* @return {@link CreateLedgerResult} from QLDB.
*/
public static CreateLedgerResult create(final String ledgerName) {
log.info("Let's create the ledger with name: {}...", ledgerName);
CreateLedgerRequest request = new CreateLedgerRequest()
.withName(ledgerName)
.withPermissionsMode(PermissionsMode.ALLOW_ALL);
CreateLedgerResult result = client.createLedger(request);
log.info("Success. Ledger state: {}.", result.getState());
return result;
}
/**
* Wait for a newly created ledger to become active.
*
* @param ledgerName
* Name of the ledger to wait on.
* @return {@link DescribeLedgerResult} from QLDB.
* @throws InterruptedException if thread is being interrupted.
*/
public static DescribeLedgerResult waitForActive(final String ledgerName) throws InterruptedException {
log.info("Waiting for ledger to become active...");
while (true) {
DescribeLedgerResult result = DescribeLedger.describe(ledgerName);
if (result.getState().equals(LedgerState.ACTIVE.name())) {
log.info("Success. Ledger is active and ready to use.");
return result;
}
log.info("The ledger is still creating. Please wait...");
Thread.sleep(LEDGER_CREATION_POLL_PERIOD_MS);
}
}
}
```
------
**注意**
在`createLedger`通話中，您必須指定分類帳名稱和許可模式。我們建議您使用 `STANDARD` 許可模式，將分類帳資料的安全性最大化。
當您建立分類帳時，預設會啟用*刪除保護*。這是 QLDB 中的一項功能，可防止任何使用者刪除分類帳。您可以選擇使用 QLDB API 或 AWS Command Line Interface () 在建立分類帳時停用刪除保護AWS CLI。
您也可以選擇性地指定要連接到分類帳的標籤。
若要驗證與新分類帳的連線，請繼續 [步驟 2：測試與分類帳的連線](getting-started.java.step-2.md)。
# 步驟 2：測試與分類帳的連線
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步驟中，您會驗證您可以使用交易資料 API `vehicle-registration` 端點連線到 Amazon QLDB 中的分類帳。
**測試與分類帳的連線**
1. 檢閱下列程式 `vehicle-registration` (`ConnectToLedger.java`)，這會建立與分類帳的資料工作階段連線。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.net.URI;
import java.net.URISyntaxException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import software.amazon.awssdk.services.qldbsession.QldbSessionClient;
import software.amazon.awssdk.services.qldbsession.QldbSessionClientBuilder;
import software.amazon.qldb.QldbDriver;
import software.amazon.qldb.RetryPolicy;
/**
* Connect to a session for a given ledger using default settings.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class ConnectToLedger {
public static final Logger log = LoggerFactory.getLogger(ConnectToLedger.class);
public static AwsCredentialsProvider credentialsProvider;
public static String endpoint = null;
public static String ledgerName = Constants.LEDGER_NAME;
public static String region = null;
public static QldbDriver driver;
private ConnectToLedger() {
}
/**
* Create a pooled driver for creating sessions.
*
* @param retryAttempts How many times the transaction will be retried in
* case of a retryable issue happens like Optimistic Concurrency Control exception,
* server side failures or network issues.
* @return The pooled driver for creating sessions.
*/
public static QldbDriver createQldbDriver(int retryAttempts) {
QldbSessionClientBuilder builder = getAmazonQldbSessionClientBuilder();
return QldbDriver.builder()
.ledger(ledgerName)
.transactionRetryPolicy(RetryPolicy
.builder()
.maxRetries(retryAttempts)
.build())
.sessionClientBuilder(builder)
.build();
}
/**
* Create a pooled driver for creating sessions.
*
* @return The pooled driver for creating sessions.
*/
public static QldbDriver createQldbDriver() {
QldbSessionClientBuilder builder = getAmazonQldbSessionClientBuilder();
return QldbDriver.builder()
.ledger(ledgerName)
.transactionRetryPolicy(RetryPolicy.builder()
.maxRetries(Constants.RETRY_LIMIT).build())
.sessionClientBuilder(builder)
.build();
}
/**
* Creates a QldbSession builder that is passed to the QldbDriver to connect to the Ledger.
*
* @return An instance of the AmazonQLDBSessionClientBuilder
*/
public static QldbSessionClientBuilder getAmazonQldbSessionClientBuilder() {
QldbSessionClientBuilder builder = QldbSessionClient.builder();
if (null != endpoint && null != region) {
try {
builder.endpointOverride(new URI(endpoint));
} catch (URISyntaxException e) {
throw new IllegalArgumentException(e);
}
}
if (null != credentialsProvider) {
builder.credentialsProvider(credentialsProvider);
}
return builder;
}
/**
* Create a pooled driver for creating sessions.
*
* @return The pooled driver for creating sessions.
*/
public static QldbDriver getDriver() {
if (driver == null) {
driver = createQldbDriver();
}
return driver;
}
public static void main(final String... args) {
Iterable tables = ConnectToLedger.getDriver().getTableNames();
log.info("Existing tables in the ledger:");
for (String table : tables) {
log.info("- {} ", table);
}
}
}
```
**注意**
若要在分類帳上執行資料操作，您必須建立 `QldbDriver`類別的執行個體，才能連線到特定分類帳。這是與您在上一個步驟中用來建立分類帳的`AmazonQLDB`用戶端不同的用戶端物件。先前的用戶端僅用於執行 中列出的管理 API 操作[Amazon QLDB API 參考](api-reference.md)。
首先，建立 `QldbDriver` 物件。建立此驅動程式時，您必須指定分類帳名稱。
然後，您可以使用此驅動程式的 `execute`方法執行 PartiQL 陳述式。
或者，您可以指定交易例外狀況的重試嘗試次數上限。此`execute`方法會自動重試樂觀並行控制 (OCC) 衝突和其他常見的暫時性例外狀況，直到達到此可設定的限制為止。預設值為 `4`。
如果交易在達到限制之後仍然失敗，則驅動程式會擲回例外狀況。如需進一步了解，請參閱 [了解 Amazon QLDB 中驅動程式的重試政策](driver-retry-policy.md)。
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.client.builder.AwsClientBuilder;
import com.amazonaws.services.qldbsession.AmazonQLDBSessionClientBuilder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.PooledQldbDriver;
import software.amazon.qldb.QldbDriver;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.exceptions.QldbClientException;
/**
* Connect to a session for a given ledger using default settings.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class ConnectToLedger {
public static final Logger log = LoggerFactory.getLogger(ConnectToLedger.class);
public static AWSCredentialsProvider credentialsProvider;
public static String endpoint = null;
public static String ledgerName = Constants.LEDGER_NAME;
public static String region = null;
private static PooledQldbDriver driver;
private ConnectToLedger() {
}
/**
* Create a pooled driver for creating sessions.
*
* @return The pooled driver for creating sessions.
*/
public static PooledQldbDriver createQldbDriver() {
AmazonQLDBSessionClientBuilder builder = AmazonQLDBSessionClientBuilder.standard();
if (null != endpoint && null != region) {
builder.setEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(endpoint, region));
}
if (null != credentialsProvider) {
builder.setCredentials(credentialsProvider);
}
return PooledQldbDriver.builder()
.withLedger(ledgerName)
.withRetryLimit(Constants.RETRY_LIMIT)
.withSessionClientBuilder(builder)
.build();
}
/**
* Create a pooled driver for creating sessions.
*
* @return The pooled driver for creating sessions.
*/
public static PooledQldbDriver getDriver() {
if (driver == null) {
driver = createQldbDriver();
}
return driver;
}
/**
* Connect to a ledger through a {@link QldbDriver}.
*
* @return {@link QldbSession}.
*/
public static QldbSession createQldbSession() {
return getDriver().getSession();
}
public static void main(final String... args) {
try (QldbSession qldbSession = createQldbSession()) {
log.info("Listing table names ");
for (String tableName : qldbSession.getTableNames()) {
log.info(tableName);
}
} catch (QldbClientException e) {
log.error("Unable to create session.", e);
}
}
}
```
**注意**
若要在分類帳上執行資料操作，您必須建立 `PooledQldbDriver`或 `QldbDriver`類別的執行個體，才能連線到特定分類帳。這是與您在上一個步驟中用來建立分類帳的`AmazonQLDB`用戶端不同的用戶端物件。先前的用戶端僅用於執行 中列出的管理 API 操作[Amazon QLDB API 參考](api-reference.md)。
建議您使用 ，`PooledQldbDriver`除非您需要使用 實作自訂工作階段集區`QldbDriver`。的預設集區大小`PooledQldbDriver`是工作階段用戶端允許的[開啟 HTTP 連線數目上限](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/ClientConfiguration.html#getMaxConnections--)。
首先，建立`PooledQldbDriver`物件。建立此驅動程式時，您必須指定分類帳名稱。
然後，您可以使用此驅動程式的 `execute`方法執行 PartiQL 陳述式。或者，您可以從此集區驅動程式物件手動建立工作階段，並使用工作階段的 `execute`方法。工作階段代表與分類帳的單一連線。
或者，您可以指定交易例外狀況的重試嘗試次數上限。此`execute`方法會自動重試樂觀並行控制 (OCC) 衝突和其他常見的暫時性例外狀況，直到達到此可設定的限制為止。預設值為 `4`。
如果交易在達到限制之後仍然失敗，則驅動程式會擲回例外狀況。如需進一步了解，請參閱 [了解 Amazon QLDB 中驅動程式的重試政策](driver-retry-policy.md)。
------
1. 編譯並執行 `ConnectToLedger.java`程式，以測試您的資料工作階段與`vehicle-registration`分類帳的連線。
**覆寫 AWS 區域**
範例應用程式會連線至預設中的 QLDB AWS 區域，您可以依照先決條件步驟 中所述進行設定[設定您的預設 AWS 登入資料和區域](getting-started.java.md#getting-started.java.credentials)。您也可以修改 QLDB 工作階段用戶端建置器屬性來變更區域。
------
#### [ 2.x ]
下列程式碼範例會執行個體化新的`QldbSessionClientBuilder`物件。
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.qldbsession.QldbSessionClientBuilder;
// This client builder will default to US East (Ohio)
QldbSessionClientBuilder builder = QldbSessionClient.builder()
.region(Region.US_EAST_2);
```
您可以使用 `region`方法，在任何可用區域中針對 QLDB 執行程式碼。如需完整清單，請參閱 中的 [Amazon QLDB 端點和配額](https://docs.aws.amazon.com/general/latest/gr/qldb.html)*AWS 一般參考*。
------
#### [ 1.x ]
下列程式碼範例會執行個體化新`AmazonQLDBSessionClientBuilder`物件。
```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.qldbsession.AmazonQLDBSessionClientBuilder;
// This client builder will default to US East (Ohio)
AmazonQLDBSessionClientBuilder builder = AmazonQLDBSessionClientBuilder.standard()
.withRegion(Regions.US_EAST_2);
```
您可以使用 `withRegion`方法，在任何可用區域中針對 QLDB 執行程式碼。如需完整清單，請參閱 中的 [Amazon QLDB 端點和配額](https://docs.aws.amazon.com/general/latest/gr/qldb.html)*AWS 一般參考*。
------
若要在`vehicle-registration`分類帳中建立資料表，請繼續執行 [步驟 3：建立資料表、索引和範例資料](getting-started.java.step-3.md)。
# 步驟 3：建立資料表、索引和範例資料
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
當您的 Amazon QLDB 分類帳處於作用中狀態並接受連線時，您可以開始為車輛、其擁有者及其註冊資訊的資料建立資料表。建立資料表和索引之後，您可以使用資料載入它們。
在此步驟中，您會在`vehicle-registration`分類帳中建立四個資料表：
+ `VehicleRegistration`
+ `Vehicle`
+ `Person`
+ `DriversLicense`
您也可以建立下列索引。
****
| 資料表名稱 | 欄位 |
| --- | --- |
| VehicleRegistration | VIN |
| VehicleRegistration | LicensePlateNumber |
| Vehicle | VIN |
| Person | GovId |
| DriversLicense | LicenseNumber |
| DriversLicense | PersonId |
插入範例資料時，首先將文件插入`Person`資料表。然後，您可以使用`id`每個`Person`文件中由系統指派的 ，在適當的 `VehicleRegistration`和 `DriversLicense` 文件中填入對應的欄位。
**提示**
最佳實務是使用文件的系統指派`id`為外部金鑰。雖然您可以定義旨在作為唯一識別符的欄位 （例如，車輛的 VIN)，但文件的真正唯一識別符是其 `id`。此欄位包含在文件的中繼資料中，您可以在*遞交檢視* （資料表的系統定義檢視） 中查詢。
如需 QLDB 中檢視的詳細資訊，請參閱[核心概念](ledger-structure.md)。若要進一步了解中繼資料，請參閱 [查詢文件中繼資料](working.metadata.md)。
**設定範例資料**
1. 檢閱下列`.java`檔案。這些模型類別代表您存放在`vehicle-registration`資料表中的文件。它們可在 Amazon Ion 格式之間序列化。
**注意**
[Amazon QLDB 文件](ql-reference.docs.md) 以 Ion 格式儲存，這是 JSON 的超集合。因此，您可以使用 FasterXML Jackson 程式庫來建立 JSON 中的資料模型。
1. `DriversLicense.java`
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import software.amazon.qldb.tutorial.model.streams.RevisionData;
import java.time.LocalDate;
/**
* Represents a driver's license, serializable to (and from) Ion.
*/
public final class DriversLicense implements RevisionData {
private final String personId;
private final String licenseNumber;
private final String licenseType;
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
private final LocalDate validFromDate;
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
private final LocalDate validToDate;
@JsonCreator
public DriversLicense(@JsonProperty("PersonId") final String personId,
@JsonProperty("LicenseNumber") final String licenseNumber,
@JsonProperty("LicenseType") final String licenseType,
@JsonProperty("ValidFromDate") final LocalDate validFromDate,
@JsonProperty("ValidToDate") final LocalDate validToDate) {
this.personId = personId;
this.licenseNumber = licenseNumber;
this.licenseType = licenseType;
this.validFromDate = validFromDate;
this.validToDate = validToDate;
}
@JsonProperty("PersonId")
public String getPersonId() {
return personId;
}
@JsonProperty("LicenseNumber")
public String getLicenseNumber() {
return licenseNumber;
}
@JsonProperty("LicenseType")
public String getLicenseType() {
return licenseType;
}
@JsonProperty("ValidFromDate")
public LocalDate getValidFromDate() {
return validFromDate;
}
@JsonProperty("ValidToDate")
public LocalDate getValidToDate() {
return validToDate;
}
@Override
public String toString() {
return "DriversLicense{" +
"personId='" + personId + '\'' +
", licenseNumber='" + licenseNumber + '\'' +
", licenseType='" + licenseType + '\'' +
", validFromDate=" + validFromDate +
", validToDate=" + validToDate +
'}';
}
}
```
1. `Person.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import java.time.LocalDate;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.model.streams.RevisionData;
/**
* Represents a person, serializable to (and from) Ion.
*/
public final class Person implements RevisionData {
private final String firstName;
private final String lastName;
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
private final LocalDate dob;
private final String govId;
private final String govIdType;
private final String address;
@JsonCreator
public Person(@JsonProperty("FirstName") final String firstName,
@JsonProperty("LastName") final String lastName,
@JsonProperty("DOB") final LocalDate dob,
@JsonProperty("GovId") final String govId,
@JsonProperty("GovIdType") final String govIdType,
@JsonProperty("Address") final String address) {
this.firstName = firstName;
this.lastName = lastName;
this.dob = dob;
this.govId = govId;
this.govIdType = govIdType;
this.address = address;
}
@JsonProperty("Address")
public String getAddress() {
return address;
}
@JsonProperty("DOB")
public LocalDate getDob() {
return dob;
}
@JsonProperty("FirstName")
public String getFirstName() {
return firstName;
}
@JsonProperty("LastName")
public String getLastName() {
return lastName;
}
@JsonProperty("GovId")
public String getGovId() {
return govId;
}
@JsonProperty("GovIdType")
public String getGovIdType() {
return govIdType;
}
/**
* This returns the unique document ID given a specific government ID.
*
* @param txn
* A transaction executor object.
* @param govId
* The government ID of a driver.
* @return the unique document ID.
*/
public static String getDocumentIdByGovId(final TransactionExecutor txn, final String govId) {
return SampleData.getDocumentId(txn, Constants.PERSON_TABLE_NAME, "GovId", govId);
}
@Override
public String toString() {
return "Person{" +
"firstName='" + firstName + '\'' +
", lastName='" + lastName + '\'' +
", dob=" + dob +
", govId='" + govId + '\'' +
", govIdType='" + govIdType + '\'' +
", address='" + address + '\'' +
'}';
}
}
```
1. `VehicleRegistration.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.model.streams.RevisionData;
import java.math.BigDecimal;
import java.time.LocalDate;
/**
* Represents a vehicle registration, serializable to (and from) Ion.
*/
public final class VehicleRegistration implements RevisionData {
private final String vin;
private final String licensePlateNumber;
private final String state;
private final String city;
private final BigDecimal pendingPenaltyTicketAmount;
private final LocalDate validFromDate;
private final LocalDate validToDate;
private final Owners owners;
@JsonCreator
public VehicleRegistration(@JsonProperty("VIN") final String vin,
@JsonProperty("LicensePlateNumber") final String licensePlateNumber,
@JsonProperty("State") final String state,
@JsonProperty("City") final String city,
@JsonProperty("PendingPenaltyTicketAmount") final BigDecimal pendingPenaltyTicketAmount,
@JsonProperty("ValidFromDate") final LocalDate validFromDate,
@JsonProperty("ValidToDate") final LocalDate validToDate,
@JsonProperty("Owners") final Owners owners) {
this.vin = vin;
this.licensePlateNumber = licensePlateNumber;
this.state = state;
this.city = city;
this.pendingPenaltyTicketAmount = pendingPenaltyTicketAmount;
this.validFromDate = validFromDate;
this.validToDate = validToDate;
this.owners = owners;
}
@JsonProperty("City")
public String getCity() {
return city;
}
@JsonProperty("LicensePlateNumber")
public String getLicensePlateNumber() {
return licensePlateNumber;
}
@JsonProperty("Owners")
public Owners getOwners() {
return owners;
}
@JsonProperty("PendingPenaltyTicketAmount")
public BigDecimal getPendingPenaltyTicketAmount() {
return pendingPenaltyTicketAmount;
}
@JsonProperty("State")
public String getState() {
return state;
}
@JsonProperty("ValidFromDate")
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
public LocalDate getValidFromDate() {
return validFromDate;
}
@JsonProperty("ValidToDate")
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
public LocalDate getValidToDate() {
return validToDate;
}
@JsonProperty("VIN")
public String getVin() {
return vin;
}
/**
* Returns the unique document ID of a vehicle given a specific VIN.
*
* @param txn
* A transaction executor object.
* @param vin
* The VIN of a vehicle.
* @return the unique document ID of the specified vehicle.
*/
public static String getDocumentIdByVin(final TransactionExecutor txn, final String vin) {
return SampleData.getDocumentId(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME, "VIN", vin);
}
@Override
public String toString() {
return "VehicleRegistration{" +
"vin='" + vin + '\'' +
", licensePlateNumber='" + licensePlateNumber + '\'' +
", state='" + state + '\'' +
", city='" + city + '\'' +
", pendingPenaltyTicketAmount=" + pendingPenaltyTicketAmount +
", validFromDate=" + validFromDate +
", validToDate=" + validToDate +
", owners=" + owners +
'}';
}
}
```
1. `Vehicle.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import software.amazon.qldb.tutorial.model.streams.RevisionData;
/**
* Represents a vehicle, serializable to (and from) Ion.
*/
public final class Vehicle implements RevisionData {
private final String vin;
private final String type;
private final int year;
private final String make;
private final String model;
private final String color;
@JsonCreator
public Vehicle(@JsonProperty("VIN") final String vin,
@JsonProperty("Type") final String type,
@JsonProperty("Year") final int year,
@JsonProperty("Make") final String make,
@JsonProperty("Model") final String model,
@JsonProperty("Color") final String color) {
this.vin = vin;
this.type = type;
this.year = year;
this.make = make;
this.model = model;
this.color = color;
}
@JsonProperty("Color")
public String getColor() {
return color;
}
@JsonProperty("Make")
public String getMake() {
return make;
}
@JsonProperty("Model")
public String getModel() {
return model;
}
@JsonProperty("Type")
public String getType() {
return type;
}
@JsonProperty("VIN")
public String getVin() {
return vin;
}
@JsonProperty("Year")
public int getYear() {
return year;
}
@Override
public String toString() {
return "Vehicle{" +
"vin='" + vin + '\'' +
", type='" + type + '\'' +
", year=" + year +
", make='" + make + '\'' +
", model='" + model + '\'' +
", color='" + color + '\'' +
'}';
}
}
```
1. `Owner.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Represents a vehicle owner, serializable to (and from) Ion.
*/
public final class Owner {
private final String personId;
public Owner(@JsonProperty("PersonId") final String personId) {
this.personId = personId;
}
@JsonProperty("PersonId")
public String getPersonId() {
return personId;
}
@Override
public String toString() {
return "Owner{" +
"personId='" + personId + '\'' +
'}';
}
}
```
1. `Owners.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* Represents a set of owners for a given vehicle, serializable to (and from) Ion.
*/
public final class Owners {
private final Owner primaryOwner;
private final List secondaryOwners;
public Owners(@JsonProperty("PrimaryOwner") final Owner primaryOwner,
@JsonProperty("SecondaryOwners") final List secondaryOwners) {
this.primaryOwner = primaryOwner;
this.secondaryOwners = secondaryOwners;
}
@JsonProperty("PrimaryOwner")
public Owner getPrimaryOwner() {
return primaryOwner;
}
@JsonProperty("SecondaryOwners")
public List getSecondaryOwners() {
return secondaryOwners;
}
@Override
public String toString() {
return "Owners{" +
"primaryOwner=" + primaryOwner +
", secondaryOwners=" + secondaryOwners +
'}';
}
}
```
1. `DmlResultDocument.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Contains information about an individual document inserted or modified
* as a result of DML.
*/
public class DmlResultDocument {
private String documentId;
@JsonCreator
public DmlResultDocument(@JsonProperty("documentId") final String documentId) {
this.documentId = documentId;
}
public String getDocumentId() {
return documentId;
}
@Override
public String toString() {
return "DmlResultDocument{"
+ "documentId='" + documentId + '\''
+ '}';
}
}
```
1. `RevisionData.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model.streams;
/**
* Allows modeling the content of all revisions as a generic revision data. Used
* in the {@link Revision} and extended by domain models in {@link
* software.amazon.qldb.tutorial.model} to make it easier to write the {@link
* Revision.RevisionDataDeserializer} that must deserialize the {@link
* Revision#data} from different domain models.
*/
public interface RevisionData { }
```
1. `RevisionMetadata.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonInt;
import com.amazon.ion.IonString;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonTimestamp;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.dataformat.ion.IonTimestampSerializers;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.Date;
import java.util.Objects;
/**
* Represents the metadata field of a QLDB Document
*/
public class RevisionMetadata {
private static final Logger log = LoggerFactory.getLogger(RevisionMetadata.class);
private final String id;
private final long version;
@JsonSerialize(using = IonTimestampSerializers.IonTimestampJavaDateSerializer.class)
private final Date txTime;
private final String txId;
@JsonCreator
public RevisionMetadata(@JsonProperty("id") final String id,
@JsonProperty("version") final long version,
@JsonProperty("txTime") final Date txTime,
@JsonProperty("txId") final String txId) {
this.id = id;
this.version = version;
this.txTime = txTime;
this.txId = txId;
}
/**
* Gets the unique ID of a QLDB document.
*
* @return the document ID.
*/
public String getId() {
return id;
}
/**
* Gets the version number of the document in the document's modification history.
* @return the version number.
*/
public long getVersion() {
return version;
}
/**
* Gets the time during which the document was modified.
*
* @return the transaction time.
*/
public Date getTxTime() {
return txTime;
}
/**
* Gets the transaction ID associated with this document.
*
* @return the transaction ID.
*/
public String getTxId() {
return txId;
}
public static RevisionMetadata fromIon(final IonStruct ionStruct) {
if (ionStruct == null) {
throw new IllegalArgumentException("Metadata cannot be null");
}
try {
IonString id = (IonString) ionStruct.get("id");
IonInt version = (IonInt) ionStruct.get("version");
IonTimestamp txTime = (IonTimestamp) ionStruct.get("txTime");
IonString txId = (IonString) ionStruct.get("txId");
if (id == null || version == null || txTime == null || txId == null) {
throw new IllegalArgumentException("Document is missing required fields");
}
return new RevisionMetadata(id.stringValue(), version.longValue(), new Date(txTime.getMillis()), txId.stringValue());
} catch (ClassCastException e) {
log.error("Failed to parse ion document");
throw new IllegalArgumentException("Document members are not of the correct type", e);
}
}
/**
* Converts a {@link RevisionMetadata} object to a string.
*
* @return the string representation of the {@link QldbRevision} object.
*/
@Override
public String toString() {
return "Metadata{"
+ "id='" + id + '\''
+ ", version=" + version
+ ", txTime=" + txTime
+ ", txId='" + txId
+ '\''
+ '}';
}
/**
* Check whether two {@link RevisionMetadata} objects are equivalent.
*
* @return {@code true} if the two objects are equal, {@code false} otherwise.
*/
@Override
public boolean equals(Object o) {
if (this == o) { return true; }
if (o == null || getClass() != o.getClass()) { return false; }
RevisionMetadata metadata = (RevisionMetadata) o;
return version == metadata.version
&& id.equals(metadata.id)
&& txTime.equals(metadata.txTime)
&& txId.equals(metadata.txId);
}
/**
* Generate a hash code for the {@link RevisionMetadata} object.
*
* @return the hash code.
*/
@Override
public int hashCode() {
// CHECKSTYLE:OFF - Disabling as we are generating a hashCode of multiple properties.
return Objects.hash(id, version, txTime, txId);
// CHECKSTYLE:ON
}
}
```
1. `QldbRevision.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonBlob;
import com.amazon.ion.IonStruct;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.Verifier;
import java.io.IOException;
import java.util.Arrays;
import java.util.Objects;
/**
* Represents a QldbRevision including both user data and metadata.
*/
public final class QldbRevision {
private static final Logger log = LoggerFactory.getLogger(QldbRevision.class);
private final BlockAddress blockAddress;
private final RevisionMetadata metadata;
private final byte[] hash;
private final byte[] dataHash;
private final IonStruct data;
@JsonCreator
public QldbRevision(@JsonProperty("blockAddress") final BlockAddress blockAddress,
@JsonProperty("metadata") final RevisionMetadata metadata,
@JsonProperty("hash") final byte[] hash,
@JsonProperty("dataHash") final byte[] dataHash,
@JsonProperty("data") final IonStruct data) {
this.blockAddress = blockAddress;
this.metadata = metadata;
this.hash = hash;
this.dataHash = dataHash;
this.data = data;
}
/**
* Gets the unique ID of a QLDB document.
*
* @return the {@link BlockAddress} object.
*/
public BlockAddress getBlockAddress() {
return blockAddress;
}
/**
* Gets the metadata of the revision.
*
* @return the {@link RevisionMetadata} object.
*/
public RevisionMetadata getMetadata() {
return metadata;
}
/**
* Gets the SHA-256 hash value of the revision.
* This is equivalent to the hash of the revision metadata and data.
*
* @return the byte array representing the hash.
*/
public byte[] getHash() {
return hash;
}
/**
* Gets the SHA-256 hash value of the data portion of the revision.
* This is only present if the revision is redacted.
*
* @return the byte array representing the hash.
*/
public byte[] getDataHash() {
return dataHash;
}
/**
* Gets the revision data.
*
* @return the revision data.
*/
public IonStruct getData() {
return data;
}
/**
* Returns true if the revision has been redacted.
* @return a boolean value representing the redaction status
* of this revision.
*/
public Boolean isRedacted() {
return dataHash != null;
}
/**
* Constructs a new {@link QldbRevision} from an {@link IonStruct}.
*
* The specified {@link IonStruct} must include the following fields
*
* - blockAddress -- a {@link BlockAddress},
* - metadata -- a {@link RevisionMetadata},
* - hash -- the revision's hash calculated by QLDB,
* - dataHash -- the user data's hash calculated by QLDB (only present if revision is redacted),
* - data -- an {@link IonStruct} containing user data in the document.
*
* If any of these fields are missing or are malformed, then throws {@link IllegalArgumentException}.
*
* If the document hash calculated from the members of the specified {@link IonStruct} does not match
* the hash member of the {@link IonStruct} then throws {@link IllegalArgumentException}.
*
* @param ionStruct
* The {@link IonStruct} that contains a {@link QldbRevision} object.
* @return the converted {@link QldbRevision} object.
* @throws IOException if failed to parse parameter {@link IonStruct}.
*/
public static QldbRevision fromIon(final IonStruct ionStruct) throws IOException {
try {
BlockAddress blockAddress = Constants.MAPPER.readValue(ionStruct.get("blockAddress"), BlockAddress.class);
IonBlob revisionHash = (IonBlob) ionStruct.get("hash");
IonStruct metadataStruct = (IonStruct) ionStruct.get("metadata");
IonStruct data = ionStruct.get("data") == null || ionStruct.get("data").isNullValue() ?
null : (IonStruct) ionStruct.get("data");
IonBlob dataHash = ionStruct.get("dataHash") == null || ionStruct.get("dataHash").isNullValue() ?
null : (IonBlob) ionStruct.get("dataHash");
if (revisionHash == null || metadataStruct == null) {
throw new IllegalArgumentException("Document is missing required fields");
}
byte[] dataHashBytes = dataHash != null ? dataHash.getBytes() : QldbIonUtils.hashIonValue(data);
verifyRevisionHash(metadataStruct, dataHashBytes, revisionHash.getBytes());
RevisionMetadata metadata = RevisionMetadata.fromIon(metadataStruct);
return new QldbRevision(
blockAddress,
metadata,
revisionHash.getBytes(),
dataHash != null ? dataHash.getBytes() : null,
data
);
} catch (ClassCastException e) {
log.error("Failed to parse ion document");
throw new IllegalArgumentException("Document members are not of the correct type", e);
}
}
/**
* Converts a {@link QldbRevision} object to string.
*
* @return the string representation of the {@link QldbRevision} object.
*/
@Override
public String toString() {
return "QldbRevision{" +
"blockAddress=" + blockAddress +
", metadata=" + metadata +
", hash=" + Arrays.toString(hash) +
", dataHash=" + Arrays.toString(dataHash) +
", data=" + data +
'}';
}
/**
* Check whether two {@link QldbRevision} objects are equivalent.
*
* @return {@code true} if the two objects are equal, {@code false} otherwise.
*/
@Override
public boolean equals(final Object o) {
if (this == o) {
return true;
}
if (!(o instanceof QldbRevision)) {
return false;
}
final QldbRevision that = (QldbRevision) o;
return Objects.equals(getBlockAddress(), that.getBlockAddress())
&& Objects.equals(getMetadata(), that.getMetadata())
&& Arrays.equals(getHash(), that.getHash())
&& Arrays.equals(getDataHash(), that.getDataHash())
&& Objects.equals(getData(), that.getData());
}
/**
* Create a hash code for the {@link QldbRevision} object.
*
* @return the hash code.
*/
@Override
public int hashCode() {
// CHECKSTYLE:OFF - Disabling as we are generating a hashCode of multiple properties.
int result = Objects.hash(blockAddress, metadata, data);
// CHECKSTYLE:ON
result = 31 * result + Arrays.hashCode(hash);
return result;
}
/**
* Throws an IllegalArgumentException if the hash of the revision data and metadata
* does not match the hash provided by QLDB with the revision.
*/
public void verifyRevisionHash() {
// Certain internal-only system revisions only contain a hash which cannot be
// further computed. However, these system hashes still participate to validate
// the journal block. User revisions will always contain values for all fields
// and can therefore have their hash computed.
if (blockAddress == null && metadata == null && data == null && dataHash == null) {
return;
}
try {
IonStruct metadataIon = (IonStruct) Constants.MAPPER.writeValueAsIonValue(metadata);
byte[] dataHashBytes = isRedacted() ? dataHash : QldbIonUtils.hashIonValue(data);
verifyRevisionHash(metadataIon, dataHashBytes, hash);
} catch (IOException e) {
throw new IllegalArgumentException("Could not encode revision metadata to ion.", e);
}
}
private static void verifyRevisionHash(IonStruct metadata, byte[] dataHash, byte[] expectedHash) {
byte[] metadataHash = QldbIonUtils.hashIonValue(metadata);
byte[] candidateHash = Verifier.dot(metadataHash, dataHash);
if (!Arrays.equals(candidateHash, expectedHash)) {
throw new IllegalArgumentException("Hash entry of QLDB revision and computed hash "
+ "of QLDB revision do not match");
}
}
}
```
1. `IonLocalDateDeserializer.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.amazon.ion.Timestamp;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.databind.DeserializationContext;
import com.fasterxml.jackson.databind.JsonDeserializer;
import java.io.IOException;
import java.time.LocalDate;
/**
* Deserializes [java.time.LocalDate] from Ion.
*/
public class IonLocalDateDeserializer extends JsonDeserializer {
@Override
public LocalDate deserialize(JsonParser jp, DeserializationContext ctxt) throws IOException {
return timestampToLocalDate((Timestamp) jp.getEmbeddedObject());
}
private LocalDate timestampToLocalDate(Timestamp timestamp) {
return LocalDate.of(timestamp.getYear(), timestamp.getMonth(), timestamp.getDay());
}
}
```
1. `IonLocalDateSerializer.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.amazon.ion.Timestamp;
import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.SerializerProvider;
import com.fasterxml.jackson.databind.ser.std.StdScalarSerializer;
import com.fasterxml.jackson.dataformat.ion.IonGenerator;
import java.io.IOException;
import java.time.LocalDate;
/**
* Serializes [java.time.LocalDate] to Ion.
*/
public class IonLocalDateSerializer extends StdScalarSerializer {
public IonLocalDateSerializer() {
super(LocalDate.class);
}
@Override
public void serialize(LocalDate date, JsonGenerator jsonGenerator, SerializerProvider serializerProvider) throws IOException {
Timestamp timestamp = Timestamp.forDay(date.getYear(), date.getMonthValue(), date.getDayOfMonth());
((IonGenerator) jsonGenerator).writeValue(timestamp);
}
}
```
1. 檢閱下列檔案 (`SampleData.java`)，其代表您插入`vehicle-registration`資料表的範例資料。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.amazon.ion.IonString;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import java.io.IOException;
import java.math.BigDecimal;
import java.text.ParseException;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.ConnectToLedger;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.qldb.DmlResultDocument;
import software.amazon.qldb.tutorial.qldb.QldbRevision;
/**
* Sample domain objects for use throughout this tutorial.
*/
public final class SampleData {
public static final DateTimeFormatter DATE_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd");
public static final List REGISTRATIONS = Collections.unmodifiableList(Arrays.asList(
new VehicleRegistration("1N4AL11D75C109151", "LEWISR261LL", "WA", "Seattle",
BigDecimal.valueOf(90.25), convertToLocalDate("2017-08-21"), convertToLocalDate("2020-05-11"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("KM8SRDHF6EU074761", "CA762X", "WA", "Kent",
BigDecimal.valueOf(130.75), convertToLocalDate("2017-09-14"), convertToLocalDate("2020-06-25"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("3HGGK5G53FM761765", "CD820Z", "WA", "Everett",
BigDecimal.valueOf(442.30), convertToLocalDate("2011-03-17"), convertToLocalDate("2021-03-24"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("1HVBBAANXWH544237", "LS477D", "WA", "Tacoma",
BigDecimal.valueOf(42.20), convertToLocalDate("2011-10-26"), convertToLocalDate("2023-09-25"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("1C4RJFAG0FC625797", "TH393F", "WA", "Olympia",
BigDecimal.valueOf(30.45), convertToLocalDate("2013-09-02"), convertToLocalDate("2024-03-19"),
new Owners(new Owner(null), Collections.emptyList()))
));
public static final List VEHICLES = Collections.unmodifiableList(Arrays.asList(
new Vehicle("1N4AL11D75C109151", "Sedan", 2011, "Audi", "A5", "Silver"),
new Vehicle("KM8SRDHF6EU074761", "Sedan", 2015, "Tesla", "Model S", "Blue"),
new Vehicle("3HGGK5G53FM761765", "Motorcycle", 2011, "Ducati", "Monster 1200", "Yellow"),
new Vehicle("1HVBBAANXWH544237", "Semi", 2009, "Ford", "F 150", "Black"),
new Vehicle("1C4RJFAG0FC625797", "Sedan", 2019, "Mercedes", "CLK 350", "White")
));
public static final List PEOPLE = Collections.unmodifiableList(Arrays.asList(
new Person("Raul", "Lewis", convertToLocalDate("1963-08-19"),
"LEWISR261LL", "Driver License", "1719 University Street, Seattle, WA, 98109"),
new Person("Brent", "Logan", convertToLocalDate("1967-07-03"),
"LOGANB486CG", "Driver License", "43 Stockert Hollow Road, Everett, WA, 98203"),
new Person("Alexis", "Pena", convertToLocalDate("1974-02-10"),
"744 849 301", "SSN", "4058 Melrose Street, Spokane Valley, WA, 99206"),
new Person("Melvin", "Parker", convertToLocalDate("1976-05-22"),
"P626-168-229-765", "Passport", "4362 Ryder Avenue, Seattle, WA, 98101"),
new Person("Salvatore", "Spencer", convertToLocalDate("1997-11-15"),
"S152-780-97-415-0", "Passport", "4450 Honeysuckle Lane, Seattle, WA, 98101")
));
public static final List LICENSES = Collections.unmodifiableList(Arrays.asList(
new DriversLicense(null, "LEWISR261LL", "Learner",
convertToLocalDate("2016-12-20"), convertToLocalDate("2020-11-15")),
new DriversLicense(null, "LOGANB486CG", "Probationary",
convertToLocalDate("2016-04-06"), convertToLocalDate("2020-11-15")),
new DriversLicense(null, "744 849 301", "Full",
convertToLocalDate("2017-12-06"), convertToLocalDate("2022-10-15")),
new DriversLicense(null, "P626-168-229-765", "Learner",
convertToLocalDate("2017-08-16"), convertToLocalDate("2021-11-15")),
new DriversLicense(null, "S152-780-97-415-0", "Probationary",
convertToLocalDate("2015-08-15"), convertToLocalDate("2021-08-21"))
));
private SampleData() { }
/**
* Converts a date string with the format 'yyyy-MM-dd' into a {@link java.util.Date} object.
*
* @param date
* The date string to convert.
* @return {@link java.time.LocalDate} or null if there is a {@link ParseException}
*/
public static synchronized LocalDate convertToLocalDate(String date) {
return LocalDate.parse(date, DATE_TIME_FORMAT);
}
/**
* Convert the result set into a list of IonValues.
*
* @param result
* The result set to convert.
* @return a list of IonValues.
*/
public static List toIonValues(Result result) {
final List valueList = new ArrayList<>();
result.iterator().forEachRemaining(valueList::add);
return valueList;
}
/**
* Get the document ID of a particular document.
*
* @param txn
* A transaction executor object.
* @param tableName
* Name of the table containing the document.
* @param identifier
* The identifier used to narrow down the search.
* @param value
* Value of the identifier.
* @return the list of document IDs in the result set.
*/
public static String getDocumentId(final TransactionExecutor txn, final String tableName,
final String identifier, final String value) {
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(value));
final String query = String.format("SELECT metadata.id FROM _ql_committed_%s AS p WHERE p.data.%s = ?",
tableName, identifier);
Result result = txn.execute(query, parameters);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to retrieve document ID using " + value);
}
return getStringValueOfStructField((IonStruct) result.iterator().next(), "id");
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Get the document by ID.
*
* @param tableName
* Name of the table to insert documents into.
* @param documentId
* The unique ID of a document in the Person table.
* @return a {@link QldbRevision} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static QldbRevision getDocumentById(String tableName, String documentId) {
try {
final IonValue ionValue = Constants.MAPPER.writeValueAsIonValue(documentId);
Result result = ConnectToLedger.getDriver().execute(txn -> {
return txn.execute("SELECT c.* FROM _ql_committed_" + tableName + " AS c BY docId "
+ "WHERE docId = ?", ionValue);
});
if (result.isEmpty()) {
throw new IllegalStateException("Unable to retrieve document by id " + documentId + " in table " + tableName);
}
return Constants.MAPPER.readValue(result.iterator().next(), QldbRevision.class);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Return a list of modified document IDs as strings from a DML {@link Result}.
*
* @param result
* The result set from a DML operation.
* @return the list of document IDs modified by the operation.
*/
public static List getDocumentIdsFromDmlResult(final Result result) {
final List strings = new ArrayList<>();
result.iterator().forEachRemaining(row -> strings.add(getDocumentIdFromDmlResultDocument(row)));
return strings;
}
/**
* Convert the given DML result row's document ID to string.
*
* @param dmlResultDocument
* The {@link IonValue} representing the results of a DML operation.
* @return a string of document ID.
*/
public static String getDocumentIdFromDmlResultDocument(final IonValue dmlResultDocument) {
try {
DmlResultDocument result = Constants.MAPPER.readValue(dmlResultDocument, DmlResultDocument.class);
return result.getDocumentId();
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Get the String value of a given {@link IonStruct} field name.
* @param struct the {@link IonStruct} from which to get the value.
* @param fieldName the name of the field from which to get the value.
* @return the String value of the field within the given {@link IonStruct}.
*/
public static String getStringValueOfStructField(final IonStruct struct, final String fieldName) {
return ((IonString) struct.get(fieldName)).stringValue();
}
/**
* Return a copy of the given driver's license with updated person Id.
*
* @param oldLicense
* The old driver's license to update.
* @param personId
* The PersonId of the driver.
* @return the updated {@link DriversLicense}.
*/
public static DriversLicense updatePersonIdDriversLicense(final DriversLicense oldLicense, final String personId) {
return new DriversLicense(personId, oldLicense.getLicenseNumber(), oldLicense.getLicenseType(),
oldLicense.getValidFromDate(), oldLicense.getValidToDate());
}
/**
* Return a copy of the given vehicle registration with updated person Id.
*
* @param oldRegistration
* The old vehicle registration to update.
* @param personId
* The PersonId of the driver.
* @return the updated {@link VehicleRegistration}.
*/
public static VehicleRegistration updateOwnerVehicleRegistration(final VehicleRegistration oldRegistration,
final String personId) {
return new VehicleRegistration(oldRegistration.getVin(), oldRegistration.getLicensePlateNumber(),
oldRegistration.getState(), oldRegistration.getCity(), oldRegistration.getPendingPenaltyTicketAmount(),
oldRegistration.getValidFromDate(), oldRegistration.getValidToDate(),
new Owners(new Owner(personId), Collections.emptyList()));
}
}
```
------
#### [ 1.x ]
**重要**
對於 Amazon Ion 套件，您必須在`com.amazon.ion`應用程式中使用 命名空間。 適用於 Java 的 AWS SDK 取決於命名空間 下的另一個 Ion 套件`software.amazon.ion`，但這是與 QLDB 驅動程式不相容的舊版套件。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.amazon.ion.IonString;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.qldb.DmlResultDocument;
import software.amazon.qldb.tutorial.qldb.QldbRevision;
import java.io.IOException;
import java.math.BigDecimal;
import java.text.ParseException;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
/**
* Sample domain objects for use throughout this tutorial.
*/
public final class SampleData {
public static final DateTimeFormatter DATE_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd");
public static final List REGISTRATIONS = Collections.unmodifiableList(Arrays.asList(
new VehicleRegistration("1N4AL11D75C109151", "LEWISR261LL", "WA", "Seattle",
BigDecimal.valueOf(90.25), convertToLocalDate("2017-08-21"), convertToLocalDate("2020-05-11"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("KM8SRDHF6EU074761", "CA762X", "WA", "Kent",
BigDecimal.valueOf(130.75), convertToLocalDate("2017-09-14"), convertToLocalDate("2020-06-25"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("3HGGK5G53FM761765", "CD820Z", "WA", "Everett",
BigDecimal.valueOf(442.30), convertToLocalDate("2011-03-17"), convertToLocalDate("2021-03-24"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("1HVBBAANXWH544237", "LS477D", "WA", "Tacoma",
BigDecimal.valueOf(42.20), convertToLocalDate("2011-10-26"), convertToLocalDate("2023-09-25"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("1C4RJFAG0FC625797", "TH393F", "WA", "Olympia",
BigDecimal.valueOf(30.45), convertToLocalDate("2013-09-02"), convertToLocalDate("2024-03-19"),
new Owners(new Owner(null), Collections.emptyList()))
));
public static final List VEHICLES = Collections.unmodifiableList(Arrays.asList(
new Vehicle("1N4AL11D75C109151", "Sedan", 2011, "Audi", "A5", "Silver"),
new Vehicle("KM8SRDHF6EU074761", "Sedan", 2015, "Tesla", "Model S", "Blue"),
new Vehicle("3HGGK5G53FM761765", "Motorcycle", 2011, "Ducati", "Monster 1200", "Yellow"),
new Vehicle("1HVBBAANXWH544237", "Semi", 2009, "Ford", "F 150", "Black"),
new Vehicle("1C4RJFAG0FC625797", "Sedan", 2019, "Mercedes", "CLK 350", "White")
));
public static final List PEOPLE = Collections.unmodifiableList(Arrays.asList(
new Person("Raul", "Lewis", convertToLocalDate("1963-08-19"),
"LEWISR261LL", "Driver License", "1719 University Street, Seattle, WA, 98109"),
new Person("Brent", "Logan", convertToLocalDate("1967-07-03"),
"LOGANB486CG", "Driver License", "43 Stockert Hollow Road, Everett, WA, 98203"),
new Person("Alexis", "Pena", convertToLocalDate("1974-02-10"),
"744 849 301", "SSN", "4058 Melrose Street, Spokane Valley, WA, 99206"),
new Person("Melvin", "Parker", convertToLocalDate("1976-05-22"),
"P626-168-229-765", "Passport", "4362 Ryder Avenue, Seattle, WA, 98101"),
new Person("Salvatore", "Spencer", convertToLocalDate("1997-11-15"),
"S152-780-97-415-0", "Passport", "4450 Honeysuckle Lane, Seattle, WA, 98101")
));
public static final List LICENSES = Collections.unmodifiableList(Arrays.asList(
new DriversLicense(null, "LEWISR261LL", "Learner",
convertToLocalDate("2016-12-20"), convertToLocalDate("2020-11-15")),
new DriversLicense(null, "LOGANB486CG", "Probationary",
convertToLocalDate("2016-04-06"), convertToLocalDate("2020-11-15")),
new DriversLicense(null, "744 849 301", "Full",
convertToLocalDate("2017-12-06"), convertToLocalDate("2022-10-15")),
new DriversLicense(null, "P626-168-229-765", "Learner",
convertToLocalDate("2017-08-16"), convertToLocalDate("2021-11-15")),
new DriversLicense(null, "S152-780-97-415-0", "Probationary",
convertToLocalDate("2015-08-15"), convertToLocalDate("2021-08-21"))
));
private SampleData() { }
/**
* Converts a date string with the format 'yyyy-MM-dd' into a {@link java.util.Date} object.
*
* @param date
* The date string to convert.
* @return {@link LocalDate} or null if there is a {@link ParseException}
*/
public static synchronized LocalDate convertToLocalDate(String date) {
return LocalDate.parse(date, DATE_TIME_FORMAT);
}
/**
* Convert the result set into a list of IonValues.
*
* @param result
* The result set to convert.
* @return a list of IonValues.
*/
public static List toIonValues(Result result) {
final List valueList = new ArrayList<>();
result.iterator().forEachRemaining(valueList::add);
return valueList;
}
/**
* Get the document ID of a particular document.
*
* @param txn
* A transaction executor object.
* @param tableName
* Name of the table containing the document.
* @param identifier
* The identifier used to narrow down the search.
* @param value
* Value of the identifier.
* @return the list of document IDs in the result set.
*/
public static String getDocumentId(final TransactionExecutor txn, final String tableName,
final String identifier, final String value) {
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(value));
final String query = String.format("SELECT metadata.id FROM _ql_committed_%s AS p WHERE p.data.%s = ?",
tableName, identifier);
Result result = txn.execute(query, parameters);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to retrieve document ID using " + value);
}
return getStringValueOfStructField((IonStruct) result.iterator().next(), "id");
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Get the document by ID.
*
* @param qldbSession
* A QLDB session.
* @param tableName
* Name of the table to insert documents into.
* @param documentId
* The unique ID of a document in the Person table.
* @return a {@link QldbRevision} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static QldbRevision getDocumentById(QldbSession qldbSession, String tableName, String documentId) {
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(documentId));
final String query = String.format("SELECT c.* FROM _ql_committed_%s AS c BY docId WHERE docId = ?", tableName);
Result result = qldbSession.execute(query, parameters);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to retrieve document by id " + documentId + " in table " + tableName);
}
return Constants.MAPPER.readValue(result.iterator().next(), QldbRevision.class);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Return a list of modified document IDs as strings from a DML {@link Result}.
*
* @param result
* The result set from a DML operation.
* @return the list of document IDs modified by the operation.
*/
public static List getDocumentIdsFromDmlResult(final Result result) {
final List strings = new ArrayList<>();
result.iterator().forEachRemaining(row -> strings.add(getDocumentIdFromDmlResultDocument(row)));
return strings;
}
/**
* Convert the given DML result row's document ID to string.
*
* @param dmlResultDocument
* The {@link IonValue} representing the results of a DML operation.
* @return a string of document ID.
*/
public static String getDocumentIdFromDmlResultDocument(final IonValue dmlResultDocument) {
try {
DmlResultDocument result = Constants.MAPPER.readValue(dmlResultDocument, DmlResultDocument.class);
return result.getDocumentId();
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Get the String value of a given {@link IonStruct} field name.
* @param struct the {@link IonStruct} from which to get the value.
* @param fieldName the name of the field from which to get the value.
* @return the String value of the field within the given {@link IonStruct}.
*/
public static String getStringValueOfStructField(final IonStruct struct, final String fieldName) {
return ((IonString) struct.get(fieldName)).stringValue();
}
/**
* Return a copy of the given driver's license with updated person Id.
*
* @param oldLicense
* The old driver's license to update.
* @param personId
* The PersonId of the driver.
* @return the updated {@link DriversLicense}.
*/
public static DriversLicense updatePersonIdDriversLicense(final DriversLicense oldLicense, final String personId) {
return new DriversLicense(personId, oldLicense.getLicenseNumber(), oldLicense.getLicenseType(),
oldLicense.getValidFromDate(), oldLicense.getValidToDate());
}
/**
* Return a copy of the given vehicle registration with updated person Id.
*
* @param oldRegistration
* The old vehicle registration to update.
* @param personId
* The PersonId of the driver.
* @return the updated {@link VehicleRegistration}.
*/
public static VehicleRegistration updateOwnerVehicleRegistration(final VehicleRegistration oldRegistration,
final String personId) {
return new VehicleRegistration(oldRegistration.getVin(), oldRegistration.getLicensePlateNumber(),
oldRegistration.getState(), oldRegistration.getCity(), oldRegistration.getPendingPenaltyTicketAmount(),
oldRegistration.getValidFromDate(), oldRegistration.getValidToDate(),
new Owners(new Owner(personId), Collections.emptyList()));
}
}
```
------
**注意**
此類別使用 Ion 程式庫來提供協助程式方法，將您的資料轉換為 Ion 格式或從中轉換。
`getDocumentId` 方法會在具有字首 的資料表上執行查詢`_ql_committed_`。這是預留字首，表示您想要查詢資料表的*遞交檢視*。在此檢視中，您的資料會在 `data` 欄位中巢狀化，而中繼資料會在 `metadata` 欄位中巢狀化。
1. 編譯並執行下列程式 (`CreateTable.java`)，以建立先前提及的資料表。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Create tables in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateTable {
public static final Logger log = LoggerFactory.getLogger(CreateTable.class);
private CreateTable() { }
/**
* Registrations, vehicles, owners, and licenses tables being created in a single transaction.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to be created.
* @return the number of tables created.
*/
public static int createTable(final TransactionExecutor txn, final String tableName) {
log.info("Creating the '{}' table...", tableName);
final String createTable = String.format("CREATE TABLE %s", tableName);
final Result result = txn.execute(createTable);
log.info("{} table created successfully.", tableName);
return SampleData.toIonValues(result).size();
}
public static void main(final String... args) {
ConnectToLedger.getDriver().execute(txn -> {
createTable(txn, Constants.DRIVERS_LICENSE_TABLE_NAME);
createTable(txn, Constants.PERSON_TABLE_NAME);
createTable(txn, Constants.VEHICLE_TABLE_NAME);
createTable(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME);
});
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Create tables in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateTable {
public static final Logger log = LoggerFactory.getLogger(CreateTable.class);
private CreateTable() { }
/**
* Registrations, vehicles, owners, and licenses tables being created in a single transaction.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to be created.
* @return the number of tables created.
*/
public static int createTable(final TransactionExecutor txn, final String tableName) {
log.info("Creating the '{}' table...", tableName);
final String createTable = String.format("CREATE TABLE %s", tableName);
final Result result = txn.execute(createTable);
log.info("{} table created successfully.", tableName);
return SampleData.toIonValues(result).size();
}
public static void main(final String... args) {
ConnectToLedger.getDriver().execute(txn -> {
createTable(txn, Constants.DRIVERS_LICENSE_TABLE_NAME);
createTable(txn, Constants.PERSON_TABLE_NAME);
createTable(txn, Constants.VEHICLE_TABLE_NAME);
createTable(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME);
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
}
}
```
------
**注意**
此程式示範如何將 lambda `TransactionExecutor` 傳遞至 `execute`方法。在此範例中，您使用 lambda 表達式在單一交易中執行多個 `CREATE TABLE` PartiQL 陳述式。
`execute` 方法會隱含地啟動交易、執行 lambda 中的所有陳述式，然後自動遞交交易。
1. 編譯並執行下列程式 (`CreateIndex.java`)，以在資料表上建立索引，如前所述。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Create indexes on tables in a particular ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateIndex {
public static final Logger log = LoggerFactory.getLogger(CreateIndex.class);
private CreateIndex() { }
/**
* In this example, create indexes for registrations and vehicles tables.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to be created.
* @param indexAttribute
* The index attribute to use.
* @return the number of tables created.
*/
public static int createIndex(final TransactionExecutor txn, final String tableName, final String indexAttribute) {
log.info("Creating an index on {}...", indexAttribute);
final String createIndex = String.format("CREATE INDEX ON %s (%s)", tableName, indexAttribute);
final Result r = txn.execute(createIndex);
return SampleData.toIonValues(r).size();
}
public static void main(final String... args) {
ConnectToLedger.getDriver().execute(txn -> {
createIndex(txn, Constants.PERSON_TABLE_NAME, Constants.PERSON_GOV_ID_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_TABLE_NAME, Constants.VIN_INDEX_NAME);
createIndex(txn, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.DRIVER_LICENSE_NUMBER_INDEX_NAME);
createIndex(txn, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.DRIVER_LICENSE_PERSONID_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME, Constants.VIN_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Constants.VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME);
});
log.info("Indexes created successfully!");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Create indexes on tables in a particular ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateIndex {
public static final Logger log = LoggerFactory.getLogger(CreateIndex.class);
private CreateIndex() { }
/**
* In this example, create indexes for registrations and vehicles tables.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to be created.
* @param indexAttribute
* The index attribute to use.
* @return the number of tables created.
*/
public static int createIndex(final TransactionExecutor txn, final String tableName, final String indexAttribute) {
log.info("Creating an index on {}...", indexAttribute);
final String createIndex = String.format("CREATE INDEX ON %s (%s)", tableName, indexAttribute);
final Result r = txn.execute(createIndex);
return SampleData.toIonValues(r).size();
}
public static void main(final String... args) {
ConnectToLedger.getDriver().execute(txn -> {
createIndex(txn, Constants.PERSON_TABLE_NAME, Constants.PERSON_GOV_ID_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_TABLE_NAME, Constants.VIN_INDEX_NAME);
createIndex(txn, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.DRIVER_LICENSE_NUMBER_INDEX_NAME);
createIndex(txn, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.DRIVER_LICENSE_PERSONID_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME, Constants.VIN_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Constants.VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME);
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Indexes created successfully!");
}
}
```
------
1. 編譯並執行下列程式 (`InsertDocument.java`)，將範例資料插入資料表。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.DriversLicense;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.model.VehicleRegistration;
/**
* Insert documents into a table in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class InsertDocument {
public static final Logger log = LoggerFactory.getLogger(InsertDocument.class);
private InsertDocument() { }
/**
* Insert the given list of documents into the specified table and return the document IDs of the inserted documents.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to insert documents into.
* @param documents
* List of documents to insert into the specified table.
* @return a list of document IDs.
* @throws IllegalStateException if failed to convert documents into an {@link IonValue}.
*/
public static List insertDocuments(final TransactionExecutor txn, final String tableName,
final List documents) {
log.info("Inserting some documents in the {} table...", tableName);
try {
final String query = String.format("INSERT INTO %s ?", tableName);
final IonValue ionDocuments = Constants.MAPPER.writeValueAsIonValue(documents);
return SampleData.getDocumentIdsFromDmlResult(txn.execute(query, ionDocuments));
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Update PersonIds in driver's licenses and in vehicle registrations using document IDs.
*
* @param documentIds
* List of document IDs representing the PersonIds in DriversLicense and PrimaryOwners in VehicleRegistration.
* @param licenses
* List of driver's licenses to update.
* @param registrations
* List of registrations to update.
*/
public static void updatePersonId(final List documentIds, final List licenses,
final List registrations) {
for (int i = 0; i < documentIds.size(); ++i) {
DriversLicense license = SampleData.LICENSES.get(i);
VehicleRegistration registration = SampleData.REGISTRATIONS.get(i);
licenses.add(SampleData.updatePersonIdDriversLicense(license, documentIds.get(i)));
registrations.add(SampleData.updateOwnerVehicleRegistration(registration, documentIds.get(i)));
}
}
public static void main(final String... args) {
final List newDriversLicenses = new ArrayList<>();
final List newVehicleRegistrations = new ArrayList<>();
ConnectToLedger.getDriver().execute(txn -> {
List documentIds = insertDocuments(txn, Constants.PERSON_TABLE_NAME, SampleData.PEOPLE);
updatePersonId(documentIds, newDriversLicenses, newVehicleRegistrations);
insertDocuments(txn, Constants.VEHICLE_TABLE_NAME, SampleData.VEHICLES);
insertDocuments(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Collections.unmodifiableList(newVehicleRegistrations));
insertDocuments(txn, Constants.DRIVERS_LICENSE_TABLE_NAME,
Collections.unmodifiableList(newDriversLicenses));
});
log.info("Documents inserted successfully!");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonValue;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.DriversLicense;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.model.VehicleRegistration;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* Insert documents into a table in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class InsertDocument {
public static final Logger log = LoggerFactory.getLogger(InsertDocument.class);
private InsertDocument() { }
/**
* Insert the given list of documents into the specified table and return the document IDs of the inserted documents.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to insert documents into.
* @param documents
* List of documents to insert into the specified table.
* @return a list of document IDs.
* @throws IllegalStateException if failed to convert documents into an {@link IonValue}.
*/
public static List insertDocuments(final TransactionExecutor txn, final String tableName,
final List documents) {
log.info("Inserting some documents in the {} table...", tableName);
try {
final String statement = String.format("INSERT INTO %s ?", tableName);
final IonValue ionDocuments = Constants.MAPPER.writeValueAsIonValue(documents);
final List parameters = Collections.singletonList(ionDocuments);
return SampleData.getDocumentIdsFromDmlResult(txn.execute(statement, parameters));
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Update PersonIds in driver's licenses and in vehicle registrations using document IDs.
*
* @param documentIds
* List of document IDs representing the PersonIds in DriversLicense and PrimaryOwners in VehicleRegistration.
* @param licenses
* List of driver's licenses to update.
* @param registrations
* List of registrations to update.
*/
public static void updatePersonId(final List documentIds, final List licenses,
final List registrations) {
for (int i = 0; i < documentIds.size(); ++i) {
DriversLicense license = SampleData.LICENSES.get(i);
VehicleRegistration registration = SampleData.REGISTRATIONS.get(i);
licenses.add(SampleData.updatePersonIdDriversLicense(license, documentIds.get(i)));
registrations.add(SampleData.updateOwnerVehicleRegistration(registration, documentIds.get(i)));
}
}
public static void main(final String... args) {
final List newDriversLicenses = new ArrayList<>();
final List newVehicleRegistrations = new ArrayList<>();
ConnectToLedger.getDriver().execute(txn -> {
List documentIds = insertDocuments(txn, Constants.PERSON_TABLE_NAME, SampleData.PEOPLE);
updatePersonId(documentIds, newDriversLicenses, newVehicleRegistrations);
insertDocuments(txn, Constants.VEHICLE_TABLE_NAME, SampleData.VEHICLES);
insertDocuments(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Collections.unmodifiableList(newVehicleRegistrations));
insertDocuments(txn, Constants.DRIVERS_LICENSE_TABLE_NAME,
Collections.unmodifiableList(newDriversLicenses));
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Documents inserted successfully!");
}
}
```
------
**注意**
此程式示範如何使用參數化值呼叫 `execute`方法。除了要執行的 PartiQL 陳述式`IonValue`之外，您還可以傳遞 類型的資料參數。在陳述式字串中使用問號 (`?`) 做為變數預留位置。
如果`INSERT`陳述式成功，則會傳回每個插入文件`id`的 。
接下來，您可以使用`SELECT`陳述式從`vehicle-registration`分類帳中的資料表讀取資料。繼續執行「[步驟 4：查詢分類帳中的資料表](getting-started.java.step-4.md)」。
# 步驟 4：查詢分類帳中的資料表
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在 Amazon QLDB 分類帳中建立資料表並使用資料載入資料表之後，您可以執行查詢來檢閱您剛插入的車輛註冊資料。QLDB 使用 [PartiQL](ql-reference.md) 做為其查詢語言，而 [Amazon Ion](ion.md) 做為其文件導向資料模型。
PartiQL 是一種開放原始碼、與 SQL 相容的查詢語言，已擴充以使用 Ion。使用 PartiQL，您可以使用熟悉的 SQL 運算子插入、查詢和管理資料。Amazon Ion 是 JSON 的超集合。Ion 是一種開放原始碼、以文件為基礎的資料格式，可讓您靈活地儲存和處理結構化、半結構化和巢狀資料。
在此步驟中，您會使用`SELECT`陳述式從`vehicle-registration`分類帳中的資料表讀取資料。
**警告**
當您在沒有索引查詢的情況下在 QLDB 中執行查詢時，它會叫用完整資料表掃描。PartiQL 支援此類查詢，因為它與 SQL 相容。不過，*請勿*在 QLDB 中執行生產使用案例的資料表掃描。資料表掃描可能會導致大型資料表的效能問題，包括並行衝突和交易逾時。
若要避免資料表掃描，您必須在索引欄位或文件 ID 上使用*等式*運算子，以`WHERE`述詞子句執行陳述式；例如， `WHERE indexedField = 123`或 `WHERE indexedField IN (456, 789)`。如需詳細資訊，請參閱[最佳化查詢效能](working.optimize.md)。
**查詢資料表**
+ 編譯並執行下列程式 (`FindVehicles.java`)，以查詢在 分類帳中人員下註冊的所有車輛。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Find all vehicles registered under a person.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class FindVehicles {
public static final Logger log = LoggerFactory.getLogger(FindVehicles.class);
private FindVehicles() { }
/**
* Find vehicles registered under a driver using their government ID.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param govId
* The government ID of the owner.
* @throws IllegalStateException if failed to convert parameters into {@link IonValue}.
*/
public static void findVehiclesForOwner(final TransactionExecutor txn, final String govId) {
try {
final String documentId = Person.getDocumentIdByGovId(txn, govId);
final String query = "SELECT v FROM Vehicle AS v INNER JOIN VehicleRegistration AS r "
+ "ON v.VIN = r.VIN WHERE r.Owners.PrimaryOwner.PersonId = ?";
final Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(documentId));
log.info("List of Vehicles for owner with GovId: {}...", govId);
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final Person person = SampleData.PEOPLE.get(0);
ConnectToLedger.getDriver().execute(txn -> {
findVehiclesForOwner(txn, person.getGovId());
});
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Find all vehicles registered under a person.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class FindVehicles {
public static final Logger log = LoggerFactory.getLogger(FindVehicles.class);
private FindVehicles() { }
/**
* Find vehicles registered under a driver using their government ID.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param govId
* The government ID of the owner.
* @throws IllegalStateException if failed to convert parameters into {@link IonValue}.
*/
public static void findVehiclesForOwner(final TransactionExecutor txn, final String govId) {
try {
final String documentId = Person.getDocumentIdByGovId(txn, govId);
final String query = "SELECT v FROM Vehicle AS v INNER JOIN VehicleRegistration AS r "
+ "ON v.VIN = r.VIN WHERE r.Owners.PrimaryOwner.PersonId = ?";
final Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(documentId));
log.info("List of Vehicles for owner with GovId: {}...", govId);
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final Person person = SampleData.PEOPLE.get(0);
ConnectToLedger.getDriver().execute(txn -> {
findVehiclesForOwner(txn, person.getGovId());
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
}
}
```
------
**注意**
首先，此程式會使用 查詢文件的`Person`資料表`GovId LEWISR261LL`，以取得其`id`中繼資料欄位。
然後，它會使用本文件`id`做為外部索引鍵，透過 查詢`VehicleRegistration`資料表`PrimaryOwner.PersonId`。它也會`VehicleRegistration`與 `VIN` 欄位上的 `Vehicle` 資料表聯結。
若要了解如何修改 `vehicle-registration` 分類帳中資料表中的文件，請參閱 [步驟 5：修改分類帳中的文件](getting-started.java.step-5.md)。
# 步驟 5：修改分類帳中的文件
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
既然您擁有要使用的資料，您就可以開始變更 Amazon QLDB `vehicle-registration` 中分類帳中的文件。在此步驟中，下列程式碼範例示範如何執行資料處理語言 (DML) 陳述式。這些陳述式會更新一輛車的主要擁有者，並將次要擁有者新增至另一輛車。
**修改文件**
1. 編譯並執行下列程式 (`TransferVehicleOwnership.java`)，以使用 VIN 在您的分類帳`1N4AL11D75C109151`中更新車輛的主要擁有者。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import com.amazon.ion.system.IonReaderBuilder;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Owner;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Find primary owner for a particular vehicle's VIN.
* Transfer to another primary owner for a particular vehicle's VIN.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class TransferVehicleOwnership {
public static final Logger log = LoggerFactory.getLogger(TransferVehicleOwnership.class);
private TransferVehicleOwnership() { }
/**
* Query a driver's information using the given ID.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param documentId
* The unique ID of a document in the Person table.
* @return a {@link Person} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static Person findPersonFromDocumentId(final TransactionExecutor txn, final String documentId) {
try {
log.info("Finding person for documentId: {}...", documentId);
final String query = "SELECT p.* FROM Person AS p BY pid WHERE pid = ?";
Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(documentId));
if (result.isEmpty()) {
throw new IllegalStateException("Unable to find person with ID: " + documentId);
}
return Constants.MAPPER.readValue(result.iterator().next(), Person.class);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Find the primary owner for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @return a {@link Person} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static Person findPrimaryOwnerForVehicle(final TransactionExecutor txn, final String vin) {
try {
log.info("Finding primary owner for vehicle with Vin: {}...", vin);
final String query = "SELECT Owners.PrimaryOwner.PersonId FROM VehicleRegistration AS v WHERE v.VIN = ?";
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
Result result = txn.execute(query, parameters);
final List documents = ScanTable.toIonStructs(result);
ScanTable.printDocuments(documents);
if (documents.isEmpty()) {
throw new IllegalStateException("Unable to find registrations with VIN: " + vin);
}
final IonReader reader = IonReaderBuilder.standard().build(documents.get(0));
final String personId = Constants.MAPPER.readValue(reader, LinkedHashMap.class).get("PersonId").toString();
return findPersonFromDocumentId(txn, personId);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Update the primary owner for a vehicle registration with the given documentId.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param documentId
* New PersonId for the primary owner.
* @throws IllegalStateException if no vehicle registration was found using the given document ID and VIN, or if failed
* to convert parameters into {@link IonValue}.
*/
public static void updateVehicleRegistration(final TransactionExecutor txn, final String vin, final String documentId) {
try {
log.info("Updating primary owner for vehicle with Vin: {}...", vin);
final String query = "UPDATE VehicleRegistration AS v SET v.Owners.PrimaryOwner = ? WHERE v.VIN = ?";
final List parameters = new ArrayList<>();
parameters.add(Constants.MAPPER.writeValueAsIonValue(new Owner(documentId)));
parameters.add(Constants.MAPPER.writeValueAsIonValue(vin));
Result result = txn.execute(query, parameters);
ScanTable.printDocuments(result);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to transfer vehicle, could not find registration.");
} else {
log.info("Successfully transferred vehicle with VIN '{}' to new owner.", vin);
}
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String vin = SampleData.VEHICLES.get(0).getVin();
final String primaryOwnerGovId = SampleData.PEOPLE.get(0).getGovId();
final String newPrimaryOwnerGovId = SampleData.PEOPLE.get(1).getGovId();
ConnectToLedger.getDriver().execute(txn -> {
final Person primaryOwner = findPrimaryOwnerForVehicle(txn, vin);
if (!primaryOwner.getGovId().equals(primaryOwnerGovId)) {
// Verify the primary owner.
throw new IllegalStateException("Incorrect primary owner identified for vehicle, unable to transfer.");
}
final String newOwner = Person.getDocumentIdByGovId(txn, newPrimaryOwnerGovId);
updateVehicleRegistration(txn, vin, newOwner);
});
log.info("Successfully transferred vehicle ownership!");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import com.amazon.ion.system.IonReaderBuilder;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Owner;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Find primary owner for a particular vehicle's VIN.
* Transfer to another primary owner for a particular vehicle's VIN.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class TransferVehicleOwnership {
public static final Logger log = LoggerFactory.getLogger(TransferVehicleOwnership.class);
private TransferVehicleOwnership() { }
/**
* Query a driver's information using the given ID.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param documentId
* The unique ID of a document in the Person table.
* @return a {@link Person} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static Person findPersonFromDocumentId(final TransactionExecutor txn, final String documentId) {
try {
log.info("Finding person for documentId: {}...", documentId);
final String query = "SELECT p.* FROM Person AS p BY pid WHERE pid = ?";
Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(documentId));
if (result.isEmpty()) {
throw new IllegalStateException("Unable to find person with ID: " + documentId);
}
return Constants.MAPPER.readValue(result.iterator().next(), Person.class);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Find the primary owner for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @return a {@link Person} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static Person findPrimaryOwnerForVehicle(final TransactionExecutor txn, final String vin) {
try {
log.info("Finding primary owner for vehicle with Vin: {}...", vin);
final String query = "SELECT Owners.PrimaryOwner.PersonId FROM VehicleRegistration AS v WHERE v.VIN = ?";
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
Result result = txn.execute(query, parameters);
final List documents = ScanTable.toIonStructs(result);
ScanTable.printDocuments(documents);
if (documents.isEmpty()) {
throw new IllegalStateException("Unable to find registrations with VIN: " + vin);
}
final IonReader reader = IonReaderBuilder.standard().build(documents.get(0));
final String personId = Constants.MAPPER.readValue(reader, LinkedHashMap.class).get("PersonId").toString();
return findPersonFromDocumentId(txn, personId);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Update the primary owner for a vehicle registration with the given documentId.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param documentId
* New PersonId for the primary owner.
* @throws IllegalStateException if no vehicle registration was found using the given document ID and VIN, or if failed
* to convert parameters into {@link IonValue}.
*/
public static void updateVehicleRegistration(final TransactionExecutor txn, final String vin, final String documentId) {
try {
log.info("Updating primary owner for vehicle with Vin: {}...", vin);
final String query = "UPDATE VehicleRegistration AS v SET v.Owners.PrimaryOwner = ? WHERE v.VIN = ?";
final List parameters = new ArrayList<>();
parameters.add(Constants.MAPPER.writeValueAsIonValue(new Owner(documentId)));
parameters.add(Constants.MAPPER.writeValueAsIonValue(vin));
Result result = txn.execute(query, parameters);
ScanTable.printDocuments(result);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to transfer vehicle, could not find registration.");
} else {
log.info("Successfully transferred vehicle with VIN '{}' to new owner.", vin);
}
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String vin = SampleData.VEHICLES.get(0).getVin();
final String primaryOwnerGovId = SampleData.PEOPLE.get(0).getGovId();
final String newPrimaryOwnerGovId = SampleData.PEOPLE.get(1).getGovId();
ConnectToLedger.getDriver().execute(txn -> {
final Person primaryOwner = findPrimaryOwnerForVehicle(txn, vin);
if (!primaryOwner.getGovId().equals(primaryOwnerGovId)) {
// Verify the primary owner.
throw new IllegalStateException("Incorrect primary owner identified for vehicle, unable to transfer.");
}
final String newOwner = Person.getDocumentIdByGovId(txn, newPrimaryOwnerGovId);
updateVehicleRegistration(txn, vin, newOwner);
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Successfully transferred vehicle ownership!");
}
}
```
------
1. 編譯並執行下列程式 (`AddSecondaryOwner.java`)，將次要擁有者新增至您分類帳`KM8SRDHF6EU074761`中具有 VIN 的車輛。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Owner;
import software.amazon.qldb.tutorial.model.Owners;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Finds and adds secondary owners for a vehicle.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class AddSecondaryOwner {
public static final Logger log = LoggerFactory.getLogger(AddSecondaryOwner.class);
private AddSecondaryOwner() { }
/**
* Check whether a secondary owner has already been registered for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param secondaryOwnerId
* The secondary owner to add.
* @return {@code true} if the given secondary owner has already been registered, {@code false} otherwise.
* @throws IllegalStateException if failed to convert VIN to an {@link IonValue}.
*/
public static boolean isSecondaryOwnerForVehicle(final TransactionExecutor txn, final String vin,
final String secondaryOwnerId) {
try {
log.info("Finding secondary owners for vehicle with VIN: {}...", vin);
final String query = "SELECT Owners.SecondaryOwners FROM VehicleRegistration AS v WHERE v.VIN = ?";
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
final Result result = txn.execute(query, parameters);
final Iterator itr = result.iterator();
if (!itr.hasNext()) {
return false;
}
final Owners owners = Constants.MAPPER.readValue(itr.next(), Owners.class);
if (null != owners.getSecondaryOwners()) {
for (Owner owner : owners.getSecondaryOwners()) {
if (secondaryOwnerId.equalsIgnoreCase(owner.getPersonId())) {
return true;
}
}
}
return false;
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Adds a secondary owner for the specified VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param secondaryOwner
* The secondary owner to add.
* @throws IllegalStateException if failed to convert parameter into an {@link IonValue}.
*/
public static void addSecondaryOwnerForVin(final TransactionExecutor txn, final String vin,
final String secondaryOwner) {
try {
log.info("Inserting secondary owner for vehicle with VIN: {}...", vin);
final String query = String.format("FROM VehicleRegistration AS v WHERE v.VIN = ?" +
"INSERT INTO v.Owners.SecondaryOwners VALUE ?");
final IonValue newOwner = Constants.MAPPER.writeValueAsIonValue(new Owner(secondaryOwner));
final IonValue vinAsIonValue = Constants.MAPPER.writeValueAsIonValue(vin);
Result result = txn.execute(query, vinAsIonValue, newOwner);
log.info("VehicleRegistration Document IDs which had secondary owners added: ");
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String vin = SampleData.VEHICLES.get(1).getVin();
final String govId = SampleData.PEOPLE.get(0).getGovId();
ConnectToLedger.getDriver().execute(txn -> {
final String documentId = Person.getDocumentIdByGovId(txn, govId);
if (isSecondaryOwnerForVehicle(txn, vin, documentId)) {
log.info("Person with ID {} has already been added as a secondary owner of this vehicle.", govId);
} else {
addSecondaryOwnerForVin(txn, vin, documentId);
}
});
log.info("Secondary owners successfully updated.");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Owner;
import software.amazon.qldb.tutorial.model.Owners;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Finds and adds secondary owners for a vehicle.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class AddSecondaryOwner {
public static final Logger log = LoggerFactory.getLogger(AddSecondaryOwner.class);
private AddSecondaryOwner() { }
/**
* Check whether a secondary owner has already been registered for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param secondaryOwnerId
* The secondary owner to add.
* @return {@code true} if the given secondary owner has already been registered, {@code false} otherwise.
* @throws IllegalStateException if failed to convert VIN to an {@link IonValue}.
*/
public static boolean isSecondaryOwnerForVehicle(final TransactionExecutor txn, final String vin,
final String secondaryOwnerId) {
try {
log.info("Finding secondary owners for vehicle with VIN: {}...", vin);
final String query = "SELECT Owners.SecondaryOwners FROM VehicleRegistration AS v WHERE v.VIN = ?";
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
final Result result = txn.execute(query, parameters);
final Iterator itr = result.iterator();
if (!itr.hasNext()) {
return false;
}
final Owners owners = Constants.MAPPER.readValue(itr.next(), Owners.class);
if (null != owners.getSecondaryOwners()) {
for (Owner owner : owners.getSecondaryOwners()) {
if (secondaryOwnerId.equalsIgnoreCase(owner.getPersonId())) {
return true;
}
}
}
return false;
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Adds a secondary owner for the specified VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param secondaryOwner
* The secondary owner to add.
* @throws IllegalStateException if failed to convert parameter into an {@link IonValue}.
*/
public static void addSecondaryOwnerForVin(final TransactionExecutor txn, final String vin,
final String secondaryOwner) {
try {
log.info("Inserting secondary owner for vehicle with VIN: {}...", vin);
final String query = String.format("FROM VehicleRegistration AS v WHERE v.VIN = '%s' " +
"INSERT INTO v.Owners.SecondaryOwners VALUE ?", vin);
final IonValue newOwner = Constants.MAPPER.writeValueAsIonValue(new Owner(secondaryOwner));
Result result = txn.execute(query, newOwner);
log.info("VehicleRegistration Document IDs which had secondary owners added: ");
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String vin = SampleData.VEHICLES.get(1).getVin();
final String govId = SampleData.PEOPLE.get(0).getGovId();
ConnectToLedger.getDriver().execute(txn -> {
final String documentId = Person.getDocumentIdByGovId(txn, govId);
if (isSecondaryOwnerForVehicle(txn, vin, documentId)) {
log.info("Person with ID {} has already been added as a secondary owner of this vehicle.", govId);
} else {
addSecondaryOwnerForVin(txn, vin, documentId);
}
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Secondary owners successfully updated.");
}
}
```
------
若要檢閱`vehicle-registration`分類帳中的這些變更，請參閱 [步驟 6：檢視文件的修訂歷史記錄](getting-started.java.step-6.md)。
# 步驟 6：檢視文件的修訂歷史記錄
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在上一個步驟中修改車輛的註冊資料後，您可以查詢其所有已註冊擁有者的歷史記錄，以及任何其他更新的欄位。在此步驟中，您會查詢 `vehicle-registration` 分類帳中`VehicleRegistration`資料表中文件的修訂歷史記錄。
**檢視修訂歷史記錄**
1. 檢閱下列程式 (`QueryHistory.java`)。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.model.VehicleRegistration;
/**
* Query a table's history for a particular set of documents.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class QueryHistory {
public static final Logger log = LoggerFactory.getLogger(QueryHistory.class);
private static final int THREE_MONTHS = 90;
private QueryHistory() { }
/**
* In this example, query the 'VehicleRegistration' history table to find all previous primary owners for a VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* VIN to find previous primary owners for.
* @param query
* The query to find previous primary owners.
* @throws IllegalStateException if failed to convert document ID to an {@link IonValue}.
*/
public static void previousPrimaryOwners(final TransactionExecutor txn, final String vin, final String query) {
try {
final String docId = VehicleRegistration.getDocumentIdByVin(txn, vin);
log.info("Querying the 'VehicleRegistration' table's history using VIN: {}...", vin);
final Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(docId));
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String threeMonthsAgo = Instant.now().minus(THREE_MONTHS, ChronoUnit.DAYS).toString();
final String query = String.format("SELECT data.Owners.PrimaryOwner, metadata.version "
+ "FROM history(VehicleRegistration, `%s`) "
+ "AS h WHERE h.metadata.id = ?", threeMonthsAgo);
ConnectToLedger.getDriver().execute(txn -> {
final String vin = SampleData.VEHICLES.get(0).getVin();
previousPrimaryOwners(txn, vin, query);
});
log.info("Successfully queried history.");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonValue;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.model.VehicleRegistration;
import java.io.IOException;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.Collections;
import java.util.List;
/**
* Query a table's history for a particular set of documents.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class QueryHistory {
public static final Logger log = LoggerFactory.getLogger(QueryHistory.class);
private static final int THREE_MONTHS = 90;
private QueryHistory() { }
/**
* In this example, query the 'VehicleRegistration' history table to find all previous primary owners for a VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* VIN to find previous primary owners for.
* @param query
* The query to find previous primary owners.
* @throws IllegalStateException if failed to convert document ID to an {@link IonValue}.
*/
public static void previousPrimaryOwners(final TransactionExecutor txn, final String vin, final String query) {
try {
final String docId = VehicleRegistration.getDocumentIdByVin(txn, vin);
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(docId));
log.info("Querying the 'VehicleRegistration' table's history using VIN: {}...", vin);
final Result result = txn.execute(query, parameters);
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String threeMonthsAgo = Instant.now().minus(THREE_MONTHS, ChronoUnit.DAYS).toString();
final String query = String.format("SELECT data.Owners.PrimaryOwner, metadata.version "
+ "FROM history(VehicleRegistration, `%s`) "
+ "AS h WHERE h.metadata.id = ?", threeMonthsAgo);
ConnectToLedger.getDriver().execute(txn -> {
final String vin = SampleData.VEHICLES.get(0).getVin();
previousPrimaryOwners(txn, vin, query);
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Successfully queried history.");
}
}
```
------
**注意**
您可以在下列語法[歷史記錄函數](working.history.md#working.history.function)中查詢內建 來檢視文件的修訂歷史記錄。
```
SELECT * FROM history( table_name [, `start-time` [, `end-time` ] ] ) AS h
[ WHERE h.metadata.id = 'id' ]
```
*開始時間*和*結束時間*皆為選用。它們是 Amazon Ion 常值，可以用反引號表示 (``...``)。如需進一步了解，請參閱 [在 Amazon QLDB 中使用 PartiQL 查詢離子](ql-reference.query.md)。
最佳實務是，使用日期範圍 *（開始時間*和*結束時間*) 和文件 ID () 來限定歷史記錄查詢`metadata.id`。QLDB 會在交易中處理`SELECT`查詢，這些查詢受到[交易逾時限制](limits.md#limits.fixed)的限制。
QLDB 歷史記錄會依文件 ID 編製索引，此時您無法建立其他歷史記錄索引。包含開始時間和結束時間的歷史記錄查詢可受益於日期範圍資格。
1. 編譯並執行 `QueryHistory.java`程式，以使用 VIN 查詢`VehicleRegistration`文件的修訂歷史記錄`1N4AL11D75C109151`。
若要以密碼編譯方式驗證`vehicle-registration`分類帳中的文件修訂，請繼續 [步驟 7：驗證分類帳中的文件](getting-started.java.step-7.md)。
# 步驟 7：驗證分類帳中的文件
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
使用 Amazon QLDB，您可以搭配 SHA-256 使用密碼編譯雜湊，有效率地驗證分類帳日誌中文件的完整性。若要進一步了解驗證和密碼編譯雜湊如何在 QLDB 中運作，請參閱 [Amazon QLDB 中的資料驗證](verification.md)。
在此步驟中，您要驗證 `vehicle-registration` 分類帳中`VehicleRegistration`資料表中的文件修訂。首先，您請求摘要，該摘要會傳回為輸出檔案，並做為您分類帳整個變更歷史記錄的簽章。然後，您請求與該摘要相關的修訂證明。如果所有驗證檢查都通過，則會使用此驗證，驗證修訂的完整性。
**驗證文件修訂**
1. 檢閱下列`.java`檔案，其代表使用 Ion 和字串值的協助程式方法進行驗證和公用程式類別所需的 QLDB 物件。
1. `BlockAddress.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import java.util.Objects;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Represents the BlockAddress field of a QLDB document.
*/
public final class BlockAddress {
private static final Logger log = LoggerFactory.getLogger(BlockAddress.class);
private final String strandId;
private final long sequenceNo;
@JsonCreator
public BlockAddress(@JsonProperty("strandId") final String strandId,
@JsonProperty("sequenceNo") final long sequenceNo) {
this.strandId = strandId;
this.sequenceNo = sequenceNo;
}
public long getSequenceNo() {
return sequenceNo;
}
public String getStrandId() {
return strandId;
}
@Override
public String toString() {
return "BlockAddress{"
+ "strandId='" + strandId + '\''
+ ", sequenceNo=" + sequenceNo
+ '}';
}
@Override
public boolean equals(final Object o) {
if (this == o) {
return true;
}
if (o == null || getClass() != o.getClass()) {
return false;
}
BlockAddress that = (BlockAddress) o;
return sequenceNo == that.sequenceNo
&& strandId.equals(that.strandId);
}
@Override
public int hashCode() {
// CHECKSTYLE:OFF - Disabling as we are generating a hashCode of multiple properties.
return Objects.hash(strandId, sequenceNo);
// CHECKSTYLE:ON
}
}
```
1. `Proof.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;
import com.amazonaws.services.qldb.model.GetRevisionRequest;
import com.amazonaws.services.qldb.model.GetRevisionResult;
import java.util.ArrayList;
import java.util.List;
/**
* A Java representation of the {@link Proof} object.
* Returned from the {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision(GetRevisionRequest)} api.
*/
public final class Proof {
private static final IonSystem SYSTEM = IonSystemBuilder.standard().build();
private List internalHashes;
public Proof(final List internalHashes) {
this.internalHashes = internalHashes;
}
public List getInternalHashes() {
return internalHashes;
}
/**
* Decodes a {@link Proof} from an ion text String. This ion text is returned in
* a {@link GetRevisionResult#getProof()}
*
* @param ionText
* The ion text representing a {@link Proof} object.
* @return {@link JournalBlock} parsed from the ion text.
* @throws IllegalStateException if failed to parse the {@link Proof} object from the given ion text.
*/
public static Proof fromBlob(final String ionText) {
try {
IonReader reader = SYSTEM.newReader(ionText);
List list = new ArrayList<>();
reader.next();
reader.stepIn();
while (reader.next() != null) {
list.add(reader.newBytes());
}
return new Proof(list);
} catch (Exception e) {
throw new IllegalStateException("Failed to parse a Proof from byte array");
}
}
}
```
1. `QldbIonUtils.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonValue;
import com.amazon.ionhash.IonHashReader;
import com.amazon.ionhash.IonHashReaderBuilder;
import com.amazon.ionhash.MessageDigestIonHasherProvider;
import software.amazon.qldb.tutorial.Constants;
public class QldbIonUtils {
private static MessageDigestIonHasherProvider ionHasherProvider = new MessageDigestIonHasherProvider("SHA-256");
private QldbIonUtils() {}
/**
* Builds a hash value from the given {@link IonValue}.
*
* @param ionValue
* The {@link IonValue} to hash.
* @return a byte array representing the hash value.
*/
public static byte[] hashIonValue(final IonValue ionValue) {
IonReader reader = Constants.SYSTEM.newReader(ionValue);
IonHashReader hashReader = IonHashReaderBuilder.standard()
.withHasherProvider(ionHasherProvider)
.withReader(reader)
.build();
while (hashReader.next() != null) { }
return hashReader.digest();
}
}
```
1. `QldbStringUtils.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonWriter;
import com.amazon.ion.system.IonReaderBuilder;
import com.amazon.ion.system.IonTextWriterBuilder;
import com.amazonaws.services.qldb.model.GetBlockResult;
import com.amazonaws.services.qldb.model.GetDigestResult;
import com.amazonaws.services.qldb.model.ValueHolder;
import java.io.IOException;
/**
* Helper methods to pretty-print certain QLDB response types.
*/
public class QldbStringUtils {
private QldbStringUtils() {}
/**
* Returns the string representation of a given {@link ValueHolder}.
* Adapted from the AWS SDK autogenerated {@code toString()} method, with sensitive values un-redacted.
* Additionally, this method pretty-prints any IonText included in the {@link ValueHolder}.
*
* @param valueHolder the {@link ValueHolder} to convert to a String.
* @return the String representation of the supplied {@link ValueHolder}.
*/
public static String toUnredactedString(ValueHolder valueHolder) {
StringBuilder sb = new StringBuilder();
sb.append("{");
if (valueHolder.getIonText() != null) {
sb.append("IonText: ");
IonWriter prettyWriter = IonTextWriterBuilder.pretty().build(sb);
try {
prettyWriter.writeValues(IonReaderBuilder.standard().build(valueHolder.getIonText()));
} catch (IOException ioe) {
sb.append("**Exception while printing this IonText**");
}
}
sb.append("}");
return sb.toString();
}
/**
* Returns the string representation of a given {@link GetBlockResult}.
* Adapted from the AWS SDK autogenerated {@code toString()} method, with sensitive values un-redacted.
*
* @param getBlockResult the {@link GetBlockResult} to convert to a String.
* @return the String representation of the supplied {@link GetBlockResult}.
*/
public static String toUnredactedString(GetBlockResult getBlockResult) {
StringBuilder sb = new StringBuilder();
sb.append("{");
if (getBlockResult.getBlock() != null) {
sb.append("Block: ").append(toUnredactedString(getBlockResult.getBlock())).append(",");
}
if (getBlockResult.getProof() != null) {
sb.append("Proof: ").append(toUnredactedString(getBlockResult.getProof()));
}
sb.append("}");
return sb.toString();
}
/**
* Returns the string representation of a given {@link GetDigestResult}.
* Adapted from the AWS SDK autogenerated {@code toString()} method, with sensitive values un-redacted.
*
* @param getDigestResult the {@link GetDigestResult} to convert to a String.
* @return the String representation of the supplied {@link GetDigestResult}.
*/
public static String toUnredactedString(GetDigestResult getDigestResult) {
StringBuilder sb = new StringBuilder();
sb.append("{");
if (getDigestResult.getDigest() != null) {
sb.append("Digest: ").append(getDigestResult.getDigest()).append(",");
}
if (getDigestResult.getDigestTipAddress() != null) {
sb.append("DigestTipAddress: ").append(toUnredactedString(getDigestResult.getDigestTipAddress()));
}
sb.append("}");
return sb.toString();
}
}
```
1. `Verifier.java`
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import java.util.concurrent.ThreadLocalRandom;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazonaws.util.Base64;
import software.amazon.qldb.tutorial.qldb.Proof;
/**
* Encapsulates the logic to verify the integrity of revisions or blocks in a QLDB ledger.
*
* The main entry point is {@link #verify(byte[], byte[], String)}.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class Verifier {
public static final Logger log = LoggerFactory.getLogger(Verifier.class);
private static final int HASH_LENGTH = 32;
private static final int UPPER_BOUND = 8;
/**
* Compares two hashes by their signed byte values in little-endian order.
*/
private static Comparator hashComparator = (h1, h2) -> {
if (h1.length != HASH_LENGTH || h2.length != HASH_LENGTH) {
throw new IllegalArgumentException("Invalid hash.");
}
for (int i = h1.length - 1; i >= 0; i--) {
int byteEqual = Byte.compare(h1[i], h2[i]);
if (byteEqual != 0) {
return byteEqual;
}
}
return 0;
};
private Verifier() { }
/**
* Verify the integrity of a document with respect to a QLDB ledger digest.
*
* The verification algorithm includes the following steps:
*
* 1. {@link #buildCandidateDigest(Proof, byte[])} build the candidate digest from the internal hashes
* in the {@link Proof}.
* 2. Check that the {@code candidateLedgerDigest} is equal to the {@code ledgerDigest}.
*
* @param documentHash
* The hash of the document to be verified.
* @param digest
* The QLDB ledger digest. This digest should have been retrieved using
* {@link com.amazonaws.services.qldb.AmazonQLDB#getDigest}
* @param proofBlob
* The ion encoded bytes representing the {@link Proof} associated with the supplied
* {@code digestTipAddress} and {@code address} retrieved using
* {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision}.
* @return {@code true} if the record is verified or {@code false} if it is not verified.
*/
public static boolean verify(
final byte[] documentHash,
final byte[] digest,
final String proofBlob
) {
Proof proof = Proof.fromBlob(proofBlob);
byte[] candidateDigest = buildCandidateDigest(proof, documentHash);
return Arrays.equals(digest, candidateDigest);
}
/**
* Build the candidate digest representing the entire ledger from the internal hashes of the {@link Proof}.
*
* @param proof
* A Java representation of {@link Proof}
* returned from {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision}.
* @param leafHash
* Leaf hash to build the candidate digest with.
* @return a byte array of the candidate digest.
*/
private static byte[] buildCandidateDigest(final Proof proof, final byte[] leafHash) {
return calculateRootHashFromInternalHashes(proof.getInternalHashes(), leafHash);
}
/**
* Get a new instance of {@link MessageDigest} using the SHA-256 algorithm.
*
* @return an instance of {@link MessageDigest}.
* @throws IllegalStateException if the algorithm is not available on the current JVM.
*/
static MessageDigest newMessageDigest() {
try {
return MessageDigest.getInstance("SHA-256");
} catch (NoSuchAlgorithmException e) {
log.error("Failed to create SHA-256 MessageDigest", e);
throw new IllegalStateException("SHA-256 message digest is unavailable", e);
}
}
/**
* Takes two hashes, sorts them, concatenates them, and then returns the
* hash of the concatenated array.
*
* @param h1
* Byte array containing one of the hashes to compare.
* @param h2
* Byte array containing one of the hashes to compare.
* @return the concatenated array of hashes.
*/
public static byte[] dot(final byte[] h1, final byte[] h2) {
if (h1.length == 0) {
return h2;
}
if (h2.length == 0) {
return h1;
}
byte[] concatenated = new byte[h1.length + h2.length];
if (hashComparator.compare(h1, h2) < 0) {
System.arraycopy(h1, 0, concatenated, 0, h1.length);
System.arraycopy(h2, 0, concatenated, h1.length, h2.length);
} else {
System.arraycopy(h2, 0, concatenated, 0, h2.length);
System.arraycopy(h1, 0, concatenated, h2.length, h1.length);
}
MessageDigest messageDigest = newMessageDigest();
messageDigest.update(concatenated);
return messageDigest.digest();
}
/**
* Starting with the provided {@code leafHash} combined with the provided {@code internalHashes}
* pairwise until only the root hash remains.
*
* @param internalHashes
* Internal hashes of Merkle tree.
* @param leafHash
* Leaf hashes of Merkle tree.
* @return the root hash.
*/
private static byte[] calculateRootHashFromInternalHashes(final List internalHashes, final byte[] leafHash) {
return internalHashes.stream().reduce(leafHash, Verifier::dot);
}
/**
* Flip a single random bit in the given byte array. This method is used to demonstrate
* QLDB's verification features.
*
* @param original
* The original byte array.
* @return the altered byte array with a single random bit changed.
*/
public static byte[] flipRandomBit(final byte[] original) {
if (original.length == 0) {
throw new IllegalArgumentException("Array cannot be empty!");
}
int alteredPosition = ThreadLocalRandom.current().nextInt(original.length);
int b = ThreadLocalRandom.current().nextInt(UPPER_BOUND);
byte[] altered = new byte[original.length];
System.arraycopy(original, 0, altered, 0, original.length);
altered[alteredPosition] = (byte) (altered[alteredPosition] ^ (1 << b));
return altered;
}
public static String toBase64(byte[] arr) {
return new String(Base64.encode(arr), StandardCharsets.UTF_8);
}
/**
* Convert a {@link ByteBuffer} into byte array.
*
* @param buffer
* The {@link ByteBuffer} to convert.
* @return the converted byte array.
*/
public static byte[] convertByteBufferToByteArray(final ByteBuffer buffer) {
byte[] arr = new byte[buffer.remaining()];
buffer.get(arr);
return arr;
}
/**
* Calculates the root hash from a list of hashes that represent the base of a Merkle tree.
*
* @param hashes
* The list of byte arrays representing hashes making up base of a Merkle tree.
* @return a byte array that is the root hash of the given list of hashes.
*/
public static byte[] calculateMerkleTreeRootHash(List hashes) {
if (hashes.isEmpty()) {
return new byte[0];
}
List remaining = combineLeafHashes(hashes);
while (remaining.size() > 1) {
remaining = combineLeafHashes(remaining);
}
return remaining.get(0);
}
private static List combineLeafHashes(List hashes) {
List combinedHashes = new ArrayList<>();
Iterator it = hashes.stream().iterator();
while (it.hasNext()) {
byte[] left = it.next();
if (it.hasNext()) {
byte[] right = it.next();
byte[] combined = dot(left, right);
combinedHashes.add(combined);
} else {
combinedHashes.add(left);
}
}
return combinedHashes;
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.util.Base64;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.qldb.Proof;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.*;
import java.util.concurrent.ThreadLocalRandom;
/**
* Encapsulates the logic to verify the integrity of revisions or blocks in a QLDB ledger.
*
* The main entry point is {@link #verify(byte[], byte[], String)}.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class Verifier {
public static final Logger log = LoggerFactory.getLogger(Verifier.class);
private static final int HASH_LENGTH = 32;
private static final int UPPER_BOUND = 8;
/**
* Compares two hashes by their signed byte values in little-endian order.
*/
private static Comparator hashComparator = (h1, h2) -> {
if (h1.length != HASH_LENGTH || h2.length != HASH_LENGTH) {
throw new IllegalArgumentException("Invalid hash.");
}
for (int i = h1.length - 1; i >= 0; i--) {
int byteEqual = Byte.compare(h1[i], h2[i]);
if (byteEqual != 0) {
return byteEqual;
}
}
return 0;
};
private Verifier() { }
/**
* Verify the integrity of a document with respect to a QLDB ledger digest.
*
* The verification algorithm includes the following steps:
*
* 1. {@link #buildCandidateDigest(Proof, byte[])} build the candidate digest from the internal hashes
* in the {@link Proof}.
* 2. Check that the {@code candidateLedgerDigest} is equal to the {@code ledgerDigest}.
*
* @param documentHash
* The hash of the document to be verified.
* @param digest
* The QLDB ledger digest. This digest should have been retrieved using
* {@link com.amazonaws.services.qldb.AmazonQLDB#getDigest}
* @param proofBlob
* The ion encoded bytes representing the {@link Proof} associated with the supplied
* {@code digestTipAddress} and {@code address} retrieved using
* {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision}.
* @return {@code true} if the record is verified or {@code false} if it is not verified.
*/
public static boolean verify(
final byte[] documentHash,
final byte[] digest,
final String proofBlob
) {
Proof proof = Proof.fromBlob(proofBlob);
byte[] candidateDigest = buildCandidateDigest(proof, documentHash);
return Arrays.equals(digest, candidateDigest);
}
/**
* Build the candidate digest representing the entire ledger from the internal hashes of the {@link Proof}.
*
* @param proof
* A Java representation of {@link Proof}
* returned from {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision}.
* @param leafHash
* Leaf hash to build the candidate digest with.
* @return a byte array of the candidate digest.
*/
private static byte[] buildCandidateDigest(final Proof proof, final byte[] leafHash) {
return calculateRootHashFromInternalHashes(proof.getInternalHashes(), leafHash);
}
/**
* Get a new instance of {@link MessageDigest} using the SHA-256 algorithm.
*
* @return an instance of {@link MessageDigest}.
* @throws IllegalStateException if the algorithm is not available on the current JVM.
*/
static MessageDigest newMessageDigest() {
try {
return MessageDigest.getInstance("SHA-256");
} catch (NoSuchAlgorithmException e) {
log.error("Failed to create SHA-256 MessageDigest", e);
throw new IllegalStateException("SHA-256 message digest is unavailable", e);
}
}
/**
* Takes two hashes, sorts them, concatenates them, and then returns the
* hash of the concatenated array.
*
* @param h1
* Byte array containing one of the hashes to compare.
* @param h2
* Byte array containing one of the hashes to compare.
* @return the concatenated array of hashes.
*/
public static byte[] dot(final byte[] h1, final byte[] h2) {
if (h1.length == 0) {
return h2;
}
if (h2.length == 0) {
return h1;
}
byte[] concatenated = new byte[h1.length + h2.length];
if (hashComparator.compare(h1, h2) < 0) {
System.arraycopy(h1, 0, concatenated, 0, h1.length);
System.arraycopy(h2, 0, concatenated, h1.length, h2.length);
} else {
System.arraycopy(h2, 0, concatenated, 0, h2.length);
System.arraycopy(h1, 0, concatenated, h2.length, h1.length);
}
MessageDigest messageDigest = newMessageDigest();
messageDigest.update(concatenated);
return messageDigest.digest();
}
/**
* Starting with the provided {@code leafHash} combined with the provided {@code internalHashes}
* pairwise until only the root hash remains.
*
* @param internalHashes
* Internal hashes of Merkle tree.
* @param leafHash
* Leaf hashes of Merkle tree.
* @return the root hash.
*/
private static byte[] calculateRootHashFromInternalHashes(final List internalHashes, final byte[] leafHash) {
return internalHashes.stream().reduce(leafHash, Verifier::dot);
}
/**
* Flip a single random bit in the given byte array. This method is used to demonstrate
* QLDB's verification features.
*
* @param original
* The original byte array.
* @return the altered byte array with a single random bit changed.
*/
public static byte[] flipRandomBit(final byte[] original) {
if (original.length == 0) {
throw new IllegalArgumentException("Array cannot be empty!");
}
int alteredPosition = ThreadLocalRandom.current().nextInt(original.length);
int b = ThreadLocalRandom.current().nextInt(UPPER_BOUND);
byte[] altered = new byte[original.length];
System.arraycopy(original, 0, altered, 0, original.length);
altered[alteredPosition] = (byte) (altered[alteredPosition] ^ (1 << b));
return altered;
}
public static String toBase64(byte[] arr) {
return new String(Base64.encode(arr), StandardCharsets.UTF_8);
}
/**
* Convert a {@link ByteBuffer} into byte array.
*
* @param buffer
* The {@link ByteBuffer} to convert.
* @return the converted byte array.
*/
public static byte[] convertByteBufferToByteArray(final ByteBuffer buffer) {
byte[] arr = new byte[buffer.remaining()];
buffer.get(arr);
return arr;
}
/**
* Calculates the root hash from a list of hashes that represent the base of a Merkle tree.
*
* @param hashes
* The list of byte arrays representing hashes making up base of a Merkle tree.
* @return a byte array that is the root hash of the given list of hashes.
*/
public static byte[] calculateMerkleTreeRootHash(List hashes) {
if (hashes.isEmpty()) {
return new byte[0];
}
List remaining = combineLeafHashes(hashes);
while (remaining.size() > 1) {
remaining = combineLeafHashes(remaining);
}
return remaining.get(0);
}
private static List combineLeafHashes(List hashes) {
List combinedHashes = new ArrayList<>();
Iterator it = hashes.stream().iterator();
while (it.hasNext()) {
byte[] left = it.next();
if (it.hasNext()) {
byte[] right = it.next();
byte[] combined = dot(left, right);
combinedHashes.add(combined);
} else {
combinedHashes.add(left);
}
}
return combinedHashes;
}
}
```
------
1. 使用兩個`.java`檔案 (`GetDigest.java` 和 `GetRevision.java`) 來執行下列步驟：
+ 從`vehicle-registration`分類帳請求新的摘要。
+ 從 `VehicleRegistration` 資料表請求文件每次修訂的證明。
+ 透過重新計算摘要，使用傳回的摘要和驗證來驗證修訂。
`GetDigest.java` 程式包含下列程式碼。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.GetDigestRequest;
import com.amazonaws.services.qldb.model.GetDigestResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.qldb.QldbStringUtils;
/**
* This is an example for retrieving the digest of a particular ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class GetDigest {
public static final Logger log = LoggerFactory.getLogger(GetDigest.class);
public static AmazonQLDB client = CreateLedger.getClient();
private GetDigest() { }
/**
* Calls {@link #getDigest(String)} for a ledger.
*
* @param args
* Arbitrary command-line arguments.
* @throws Exception if failed to get a ledger digest.
*/
public static void main(final String... args) throws Exception {
try {
getDigest(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to get a ledger digest!", e);
throw e;
}
}
/**
* Get the digest for the specified ledger.
*
* @param ledgerName
* The ledger to get digest from.
* @return {@link GetDigestResult}.
*/
public static GetDigestResult getDigest(final String ledgerName) {
log.info("Let's get the current digest of the ledger named {}.", ledgerName);
GetDigestRequest request = new GetDigestRequest()
.withName(ledgerName);
GetDigestResult result = client.getDigest(request);
log.info("Success. LedgerDigest: {}.", QldbStringUtils.toUnredactedString(result));
return result;
}
}
```
**注意**
使用 `getDigest`方法請求摘要，涵蓋您分類帳中日誌的目前*尖端*。日誌的提示是指截至 QLDB 收到您的請求時的最新遞交區塊。
`GetRevision.java` 程式包含下列程式碼。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonSystem;
import com.amazon.ion.IonValue;
import com.amazon.ion.IonWriter;
import com.amazon.ion.system.IonReaderBuilder;
import com.amazon.ion.system.IonSystemBuilder;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.GetDigestResult;
import com.amazonaws.services.qldb.model.GetRevisionRequest;
import com.amazonaws.services.qldb.model.GetRevisionResult;
import com.amazonaws.services.qldb.model.ValueHolder;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.QldbDriver;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.qldb.BlockAddress;
import software.amazon.qldb.tutorial.qldb.QldbRevision;
import software.amazon.qldb.tutorial.qldb.QldbStringUtils;
/**
* Verify the integrity of a document revision in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class GetRevision {
public static final Logger log = LoggerFactory.getLogger(GetRevision.class);
public static AmazonQLDB client = CreateLedger.getClient();
private static final IonSystem SYSTEM = IonSystemBuilder.standard().build();
private GetRevision() { }
public static void main(String... args) throws Exception {
final String vin = SampleData.REGISTRATIONS.get(0).getVin();
verifyRegistration(ConnectToLedger.getDriver(), Constants.LEDGER_NAME, vin);
}
/**
* Verify each version of the registration for the given VIN.
*
* @param driver
* A QLDB driver.
* @param ledgerName
* The ledger to get digest from.
* @param vin
* VIN to query the revision history of a specific registration with.
* @throws Exception if failed to verify digests.
* @throws AssertionError if document revision verification failed.
*/
public static void verifyRegistration(final QldbDriver driver, final String ledgerName, final String vin)
throws Exception {
log.info(String.format("Let's verify the registration with VIN=%s, in ledger=%s.", vin, ledgerName));
try {
log.info("First, let's get a digest.");
GetDigestResult digestResult = GetDigest.getDigest(ledgerName);
ValueHolder digestTipAddress = digestResult.getDigestTipAddress();
byte[] digestBytes = Verifier.convertByteBufferToByteArray(digestResult.getDigest());
log.info("Got a ledger digest. Digest end address={}, digest={}.",
QldbStringUtils.toUnredactedString(digestTipAddress),
Verifier.toBase64(digestBytes));
log.info(String.format("Next, let's query the registration with VIN=%s. "
+ "Then we can verify each version of the registration.", vin));
List documentsWithMetadataList = new ArrayList<>();
driver.execute(txn -> {
documentsWithMetadataList.addAll(queryRegistrationsByVin(txn, vin));
});
log.info("Registrations queried successfully!");
log.info(String.format("Found %s revisions of the registration with VIN=%s.",
documentsWithMetadataList.size(), vin));
for (IonStruct ionStruct : documentsWithMetadataList) {
QldbRevision document = QldbRevision.fromIon(ionStruct);
log.info(String.format("Let's verify the document: %s", document));
log.info("Let's get a proof for the document.");
GetRevisionResult proofResult = getRevision(
ledgerName,
document.getMetadata().getId(),
digestTipAddress,
document.getBlockAddress()
);
final IonValue proof = Constants.MAPPER.writeValueAsIonValue(proofResult.getProof());
final IonReader reader = IonReaderBuilder.standard().build(proof);
reader.next();
ByteArrayOutputStream baos = new ByteArrayOutputStream();
IonWriter writer = SYSTEM.newBinaryWriter(baos);
writer.writeValue(reader);
writer.close();
baos.flush();
baos.close();
byte[] byteProof = baos.toByteArray();
log.info(String.format("Got back a proof: %s", Verifier.toBase64(byteProof)));
boolean verified = Verifier.verify(
document.getHash(),
digestBytes,
proofResult.getProof().getIonText()
);
if (!verified) {
throw new AssertionError("Document revision is not verified!");
} else {
log.info("Success! The document is verified");
}
byte[] alteredDigest = Verifier.flipRandomBit(digestBytes);
log.info(String.format("Flipping one bit in the digest and assert that the document is NOT verified. "
+ "The altered digest is: %s", Verifier.toBase64(alteredDigest)));
verified = Verifier.verify(
document.getHash(),
alteredDigest,
proofResult.getProof().getIonText()
);
if (verified) {
throw new AssertionError("Expected document to not be verified against altered digest.");
} else {
log.info("Success! As expected flipping a bit in the digest causes verification to fail.");
}
byte[] alteredDocumentHash = Verifier.flipRandomBit(document.getHash());
log.info(String.format("Flipping one bit in the document's hash and assert that it is NOT verified. "
+ "The altered document hash is: %s.", Verifier.toBase64(alteredDocumentHash)));
verified = Verifier.verify(
alteredDocumentHash,
digestBytes,
proofResult.getProof().getIonText()
);
if (verified) {
throw new AssertionError("Expected altered document hash to not be verified against digest.");
} else {
log.info("Success! As expected flipping a bit in the document hash causes verification to fail.");
}
}
} catch (Exception e) {
log.error("Failed to verify digests.", e);
throw e;
}
log.info(String.format("Finished verifying the registration with VIN=%s in ledger=%s.", vin, ledgerName));
}
/**
* Get the revision of a particular document specified by the given document ID and block address.
*
* @param ledgerName
* Name of the ledger containing the document.
* @param documentId
* Unique ID for the document to be verified, contained in the committed view of the document.
* @param digestTipAddress
* The latest block location covered by the digest.
* @param blockAddress
* The location of the block to request.
* @return the requested revision.
*/
public static GetRevisionResult getRevision(final String ledgerName, final String documentId,
final ValueHolder digestTipAddress, final BlockAddress blockAddress) {
try {
GetRevisionRequest request = new GetRevisionRequest()
.withName(ledgerName)
.withDigestTipAddress(digestTipAddress)
.withBlockAddress(new ValueHolder().withIonText(Constants.MAPPER.writeValueAsIonValue(blockAddress)
.toString()))
.withDocumentId(documentId);
return client.getRevision(request);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Query the registration history for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* The unique VIN to query.
* @return a list of {@link IonStruct} representing the registration history.
* @throws IllegalStateException if failed to convert parameters into {@link IonValue}
*/
public static List queryRegistrationsByVin(final TransactionExecutor txn, final String vin) {
log.info(String.format("Let's query the 'VehicleRegistration' table for VIN: %s...", vin));
log.info("Let's query the 'VehicleRegistration' table for VIN: {}...", vin);
final String query = String.format("SELECT * FROM _ql_committed_%s WHERE data.VIN = ?",
Constants.VEHICLE_REGISTRATION_TABLE_NAME);
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
final Result result = txn.execute(query, parameters);
List list = ScanTable.toIonStructs(result);
log.info(String.format("Found %d document(s)!", list.size()));
return list;
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import com.amazon.ion.IonWriter;
import com.amazon.ion.system.IonReaderBuilder;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.GetDigestResult;
import com.amazonaws.services.qldb.model.GetRevisionRequest;
import com.amazonaws.services.qldb.model.GetRevisionResult;
import com.amazonaws.services.qldb.model.ValueHolder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.qldb.BlockAddress;
import software.amazon.qldb.tutorial.qldb.QldbRevision;
import software.amazon.qldb.tutorial.qldb.QldbStringUtils;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* Verify the integrity of a document revision in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class GetRevision {
public static final Logger log = LoggerFactory.getLogger(GetRevision.class);
public static AmazonQLDB client = CreateLedger.getClient();
private GetRevision() { }
public static void main(String... args) throws Exception {
final String vin = SampleData.REGISTRATIONS.get(0).getVin();
try (QldbSession qldbSession = ConnectToLedger.createQldbSession()) {
verifyRegistration(qldbSession, Constants.LEDGER_NAME, vin);
}
}
/**
* Verify each version of the registration for the given VIN.
*
* @param qldbSession
* A QLDB session.
* @param ledgerName
* The ledger to get digest from.
* @param vin
* VIN to query the revision history of a specific registration with.
* @throws Exception if failed to verify digests.
* @throws AssertionError if document revision verification failed.
*/
public static void verifyRegistration(final QldbSession qldbSession, final String ledgerName, final String vin)
throws Exception {
log.info(String.format("Let's verify the registration with VIN=%s, in ledger=%s.", vin, ledgerName));
try {
log.info("First, let's get a digest.");
GetDigestResult digestResult = GetDigest.getDigest(ledgerName);
ValueHolder digestTipAddress = digestResult.getDigestTipAddress();
byte[] digestBytes = Verifier.convertByteBufferToByteArray(digestResult.getDigest());
log.info("Got a ledger digest. Digest end address={}, digest={}.",
QldbStringUtils.toUnredactedString(digestTipAddress),
Verifier.toBase64(digestBytes));
log.info(String.format("Next, let's query the registration with VIN=%s. "
+ "Then we can verify each version of the registration.", vin));
List documentsWithMetadataList = new ArrayList<>();
qldbSession.execute(txn -> {
documentsWithMetadataList.addAll(queryRegistrationsByVin(txn, vin));
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Registrations queried successfully!");
log.info(String.format("Found %s revisions of the registration with VIN=%s.",
documentsWithMetadataList.size(), vin));
for (IonStruct ionStruct : documentsWithMetadataList) {
QldbRevision document = QldbRevision.fromIon(ionStruct);
log.info(String.format("Let's verify the document: %s", document));
log.info("Let's get a proof for the document.");
GetRevisionResult proofResult = getRevision(
ledgerName,
document.getMetadata().getId(),
digestTipAddress,
document.getBlockAddress()
);
final IonValue proof = Constants.MAPPER.writeValueAsIonValue(proofResult.getProof());
final IonReader reader = IonReaderBuilder.standard().build(proof);
reader.next();
ByteArrayOutputStream baos = new ByteArrayOutputStream();
IonWriter writer = Constants.SYSTEM.newBinaryWriter(baos);
writer.writeValue(reader);
writer.close();
baos.flush();
baos.close();
byte[] byteProof = baos.toByteArray();
log.info(String.format("Got back a proof: %s", Verifier.toBase64(byteProof)));
boolean verified = Verifier.verify(
document.getHash(),
digestBytes,
proofResult.getProof().getIonText()
);
if (!verified) {
throw new AssertionError("Document revision is not verified!");
} else {
log.info("Success! The document is verified");
}
byte[] alteredDigest = Verifier.flipRandomBit(digestBytes);
log.info(String.format("Flipping one bit in the digest and assert that the document is NOT verified. "
+ "The altered digest is: %s", Verifier.toBase64(alteredDigest)));
verified = Verifier.verify(
document.getHash(),
alteredDigest,
proofResult.getProof().getIonText()
);
if (verified) {
throw new AssertionError("Expected document to not be verified against altered digest.");
} else {
log.info("Success! As expected flipping a bit in the digest causes verification to fail.");
}
byte[] alteredDocumentHash = Verifier.flipRandomBit(document.getHash());
log.info(String.format("Flipping one bit in the document's hash and assert that it is NOT verified. "
+ "The altered document hash is: %s.", Verifier.toBase64(alteredDocumentHash)));
verified = Verifier.verify(
alteredDocumentHash,
digestBytes,
proofResult.getProof().getIonText()
);
if (verified) {
throw new AssertionError("Expected altered document hash to not be verified against digest.");
} else {
log.info("Success! As expected flipping a bit in the document hash causes verification to fail.");
}
}
} catch (Exception e) {
log.error("Failed to verify digests.", e);
throw e;
}
log.info(String.format("Finished verifying the registration with VIN=%s in ledger=%s.", vin, ledgerName));
}
/**
* Get the revision of a particular document specified by the given document ID and block address.
*
* @param ledgerName
* Name of the ledger containing the document.
* @param documentId
* Unique ID for the document to be verified, contained in the committed view of the document.
* @param digestTipAddress
* The latest block location covered by the digest.
* @param blockAddress
* The location of the block to request.
* @return the requested revision.
*/
public static GetRevisionResult getRevision(final String ledgerName, final String documentId,
final ValueHolder digestTipAddress, final BlockAddress blockAddress) {
try {
GetRevisionRequest request = new GetRevisionRequest()
.withName(ledgerName)
.withDigestTipAddress(digestTipAddress)
.withBlockAddress(new ValueHolder().withIonText(Constants.MAPPER.writeValueAsIonValue(blockAddress)
.toString()))
.withDocumentId(documentId);
return client.getRevision(request);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Query the registration history for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* The unique VIN to query.
* @return a list of {@link IonStruct} representing the registration history.
* @throws IllegalStateException if failed to convert parameters into {@link IonValue}
*/
public static List queryRegistrationsByVin(final TransactionExecutor txn, final String vin) {
log.info(String.format("Let's query the 'VehicleRegistration' table for VIN: %s...", vin));
log.info("Let's query the 'VehicleRegistration' table for VIN: {}...", vin);
final String query = String.format("SELECT * FROM _ql_committed_%s WHERE data.VIN = ?",
Constants.VEHICLE_REGISTRATION_TABLE_NAME);
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
final Result result = txn.execute(query, parameters);
List list = ScanTable.toIonStructs(result);
log.info(String.format("Found %d document(s)!", list.size()));
return list;
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
}
```
------
**注意**
`getRevision` 方法傳回指定文件修訂的證明後，此程式會使用用戶端 API 來驗證該修訂。如需此 API 使用的演算法概觀，請參閱 [使用證明重新計算摘要](verification.results.md#verification.results.recalc)。
1. 編譯並執行 `GetRevision.java`程式，以密碼編譯方式驗證具有 VIN `VehicleRegistration`的文件`1N4AL11D75C109151`。
若要在`vehicle-registration`分類帳中匯出和驗證日誌資料，請繼續[步驟 8：在分類帳中匯出和驗證日誌資料](getting-started.java.step-8.md)。
# 步驟 8：在分類帳中匯出和驗證日誌資料
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在 Amazon QLDB 中，您可以存取 分類帳中的日誌內容，用於各種目的，例如資料保留、分析和稽核。如需詳細資訊，請參閱[從 Amazon QLDB 匯出日誌資料](export-journal.md)。
在此步驟中，您將[日誌區塊](journal-contents.md)從分類帳匯出至 Amazon S3 `vehicle-registration` 儲存貯體。然後，您可以使用匯出的資料來驗證日誌區塊與每個區塊中個別雜湊元件之間的雜湊鏈。
您使用的 AWS Identity and Access Management (IAM) 主體實體必須具有足夠的 IAM 許可，才能在您的 中建立 Amazon S3 儲存貯體 AWS 帳戶。如需詳細資訊，請參閱《[Amazon S3 使用者指南》中的 Amazon S3 中的政策和許可](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html)。 *Amazon S3 * 您還必須擁有許可，才能建立具有連接許可政策的 IAM 角色，允許 QLDB 將物件寫入您的 Amazon S3 儲存貯體。若要進一步了解，請參閱《[IAM 使用者指南》中的存取 IAM 資源所需的許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions-required.html)。 **
**匯出和驗證日誌資料**
1. 檢閱下列檔案 (`JournalBlock.java`)，其代表日誌區塊及其資料內容。它包含名為 的方法`verifyBlockHash()`，示範如何計算區塊雜湊的每個個別元件。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.dataformat.ion.IonTimestampSerializers;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.Verifier;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.Arrays;
import java.util.Date;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.stream.Collectors;
import static java.nio.ByteBuffer.wrap;
/**
* Represents a JournalBlock that was recorded after executing a transaction
* in the ledger.
*/
public final class JournalBlock {
private static final Logger log = LoggerFactory.getLogger(JournalBlock.class);
private BlockAddress blockAddress;
private String transactionId;
@JsonSerialize(using = IonTimestampSerializers.IonTimestampJavaDateSerializer.class)
private Date blockTimestamp;
private byte[] blockHash;
private byte[] entriesHash;
private byte[] previousBlockHash;
private byte[][] entriesHashList;
private TransactionInfo transactionInfo;
private RedactionInfo redactionInfo;
private List revisions;
@JsonCreator
public JournalBlock(@JsonProperty("blockAddress") final BlockAddress blockAddress,
@JsonProperty("transactionId") final String transactionId,
@JsonProperty("blockTimestamp") final Date blockTimestamp,
@JsonProperty("blockHash") final byte[] blockHash,
@JsonProperty("entriesHash") final byte[] entriesHash,
@JsonProperty("previousBlockHash") final byte[] previousBlockHash,
@JsonProperty("entriesHashList") final byte[][] entriesHashList,
@JsonProperty("transactionInfo") final TransactionInfo transactionInfo,
@JsonProperty("redactionInfo") final RedactionInfo redactionInfo,
@JsonProperty("revisions") final List revisions) {
this.blockAddress = blockAddress;
this.transactionId = transactionId;
this.blockTimestamp = blockTimestamp;
this.blockHash = blockHash;
this.entriesHash = entriesHash;
this.previousBlockHash = previousBlockHash;
this.entriesHashList = entriesHashList;
this.transactionInfo = transactionInfo;
this.redactionInfo = redactionInfo;
this.revisions = revisions;
}
public BlockAddress getBlockAddress() {
return blockAddress;
}
public String getTransactionId() {
return transactionId;
}
public Date getBlockTimestamp() {
return blockTimestamp;
}
public byte[][] getEntriesHashList() {
return entriesHashList;
}
public TransactionInfo getTransactionInfo() {
return transactionInfo;
}
public RedactionInfo getRedactionInfo() {
return redactionInfo;
}
public List getRevisions() {
return revisions;
}
public byte[] getEntriesHash() {
return entriesHash;
}
public byte[] getBlockHash() {
return blockHash;
}
public byte[] getPreviousBlockHash() {
return previousBlockHash;
}
@Override
public String toString() {
return "JournalBlock{"
+ "blockAddress=" + blockAddress
+ ", transactionId='" + transactionId + '\''
+ ", blockTimestamp=" + blockTimestamp
+ ", blockHash=" + Arrays.toString(blockHash)
+ ", entriesHash=" + Arrays.toString(entriesHash)
+ ", previousBlockHash=" + Arrays.toString(previousBlockHash)
+ ", entriesHashList=" + Arrays.toString(entriesHashList)
+ ", transactionInfo=" + transactionInfo
+ ", redactionInfo=" + redactionInfo
+ ", revisions=" + revisions
+ '}';
}
@Override
public boolean equals(final Object o) {
if (this == o) {
return true;
}
if (!(o instanceof JournalBlock)) {
return false;
}
final JournalBlock that = (JournalBlock) o;
if (!getBlockAddress().equals(that.getBlockAddress())) {
return false;
}
if (!getTransactionId().equals(that.getTransactionId())) {
return false;
}
if (!getBlockTimestamp().equals(that.getBlockTimestamp())) {
return false;
}
if (!Arrays.equals(getBlockHash(), that.getBlockHash())) {
return false;
}
if (!Arrays.equals(getEntriesHash(), that.getEntriesHash())) {
return false;
}
if (!Arrays.equals(getPreviousBlockHash(), that.getPreviousBlockHash())) {
return false;
}
if (!Arrays.deepEquals(getEntriesHashList(), that.getEntriesHashList())) {
return false;
}
if (!getTransactionInfo().equals(that.getTransactionInfo())) {
return false;
}
if (getRedactionInfo() != null ? !getRedactionInfo().equals(that.getRedactionInfo()) : that.getRedactionInfo() != null) {
return false;
}
return getRevisions() != null ? getRevisions().equals(that.getRevisions()) : that.getRevisions() == null;
}
@Override
public int hashCode() {
int result = getBlockAddress().hashCode();
result = 31 * result + getTransactionId().hashCode();
result = 31 * result + getBlockTimestamp().hashCode();
result = 31 * result + Arrays.hashCode(getBlockHash());
result = 31 * result + Arrays.hashCode(getEntriesHash());
result = 31 * result + Arrays.hashCode(getPreviousBlockHash());
result = 31 * result + Arrays.deepHashCode(getEntriesHashList());
result = 31 * result + getTransactionInfo().hashCode();
result = 31 * result + (getRedactionInfo() != null ? getRedactionInfo().hashCode() : 0);
result = 31 * result + (getRevisions() != null ? getRevisions().hashCode() : 0);
return result;
}
/**
* This method validates that the hashes of the components of a journal block make up the block
* hash that is provided with the block itself.
*
* The components that contribute to the hash of the journal block consist of the following:
* - user transaction information (contained in [transactionInfo])
* - user redaction information (contained in [redactionInfo])
* - user revisions (contained in [revisions])
* - hashes of internal-only system metadata (contained in [revisions] and in [entriesHashList])
* - the previous block hash
*
* If any of the computed hashes of user information cannot be validated or any of the system
* hashes do not result in the correct computed values, this method will throw an IllegalArgumentException.
*
* Internal-only system metadata is represented by its hash, and can be present in the form of certain
* items in the [revisions] list that only contain a hash and no user data, as well as some hashes
* in [entriesHashList].
*
* To validate that the hashes of the user data are valid components of the [blockHash], this method
* performs the following steps:
*
* 1. Compute the hash of the [transactionInfo] and validate that it is included in the [entriesHashList].
* 2. Compute the hash of the [redactionInfo], if present, and validate that it is included in the [entriesHashList].
* 3. Validate the hash of each user revision was correctly computed and matches the hash published
* with that revision.
* 4. Compute the hash of the [revisions] by treating the revision hashes as the leaf nodes of a Merkle tree
* and calculating the root hash of that tree. Then validate that hash is included in the [entriesHashList].
* 5. Compute the hash of the [entriesHashList] by treating the hashes as the leaf nodes of a Merkle tree
* and calculating the root hash of that tree. Then validate that hash matches [entriesHash].
* 6. Finally, compute the block hash by computing the hash resulting from concatenating the [entriesHash]
* and previous block hash, and validate that the result matches the [blockHash] provided by QLDB with the block.
*
* This method is called by ValidateQldbHashChain::verify for each journal block to validate its
* contents before verifying that the hash chain between consecutive blocks is correct.
*/
public void verifyBlockHash() {
Set entriesHashSet = new HashSet<>();
Arrays.stream(entriesHashList).forEach(hash -> entriesHashSet.add(wrap(hash).asReadOnlyBuffer()));
byte[] computedTransactionInfoHash = computeTransactionInfoHash();
if (!entriesHashSet.contains(wrap(computedTransactionInfoHash).asReadOnlyBuffer())) {
throw new IllegalArgumentException(
"Block transactionInfo hash is not contained in the QLDB block entries hash list.");
}
if (redactionInfo != null) {
byte[] computedRedactionInfoHash = computeRedactionInfoHash();
if (!entriesHashSet.contains(wrap(computedRedactionInfoHash).asReadOnlyBuffer())) {
throw new IllegalArgumentException(
"Block redactionInfo hash is not contained in the QLDB block entries hash list.");
}
}
if (revisions != null) {
revisions.forEach(QldbRevision::verifyRevisionHash);
byte[] computedRevisionsHash = computeRevisionsHash();
if (!entriesHashSet.contains(wrap(computedRevisionsHash).asReadOnlyBuffer())) {
throw new IllegalArgumentException(
"Block revisions list hash is not contained in the QLDB block entries hash list.");
}
}
byte[] computedEntriesHash = computeEntriesHash();
if (!Arrays.equals(computedEntriesHash, entriesHash)) {
throw new IllegalArgumentException("Computed entries hash does not match entries hash provided in the block.");
}
byte[] computedBlockHash = Verifier.dot(computedEntriesHash, previousBlockHash);
if (!Arrays.equals(computedBlockHash, blockHash)) {
throw new IllegalArgumentException("Computed block hash does not match block hash provided in the block.");
}
}
private byte[] computeTransactionInfoHash() {
try {
return QldbIonUtils.hashIonValue(Constants.MAPPER.writeValueAsIonValue(transactionInfo));
} catch (IOException e) {
throw new IllegalArgumentException("Could not compute transactionInfo hash to verify block hash.", e);
}
}
private byte[] computeRedactionInfoHash() {
try {
return QldbIonUtils.hashIonValue(Constants.MAPPER.writeValueAsIonValue(redactionInfo));
} catch (IOException e) {
throw new IllegalArgumentException("Could not compute redactionInfo hash to verify block hash.", e);
}
}
private byte[] computeRevisionsHash() {
return Verifier.calculateMerkleTreeRootHash(revisions.stream().map(QldbRevision::getHash).collect(Collectors.toList()));
}
private byte[] computeEntriesHash() {
return Verifier.calculateMerkleTreeRootHash(Arrays.asList(entriesHashList));
}
}
```
1. 編譯並執行下列程式 (`ValidateQldbHashChain.java`)，以執行下列步驟：
1. 將日誌區塊從分類帳匯出到名為 的 Amazon S3 `vehicle-registration` 儲存貯體 **qldb-tutorial-journal-export-*111122223333***（以您的 AWS 帳戶 數字取代）。
1. 呼叫 來驗證每個區塊中的個別雜湊元件`verifyBlockHash()`。
1. 驗證日誌區塊之間的雜湊鏈。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.model.ExportJournalToS3Result;
import com.amazonaws.services.qldb.model.S3EncryptionConfiguration;
import com.amazonaws.services.qldb.model.S3ObjectEncryptionType;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import java.time.Instant;
import java.util.Arrays;
import java.util.List;
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClientBuilder;
import com.amazonaws.services.securitytoken.model.GetCallerIdentityRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.qldb.JournalBlock;
/**
* Validate the hash chain of a QLDB ledger by stepping through its S3 export.
*
* This code accepts an exportId as an argument, if exportId is passed the code
* will use that or request QLDB to generate a new export to perform QLDB hash
* chain validation.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class ValidateQldbHashChain {
public static final Logger log = LoggerFactory.getLogger(ValidateQldbHashChain.class);
private static final int TIME_SKEW = 20;
private ValidateQldbHashChain() { }
/**
* Export journal contents to a S3 bucket.
*
* @return the ExportId of the journal export.
* @throws InterruptedException if the thread is interrupted while waiting for export to complete.
*/
private static String createExport() throws InterruptedException {
String accountId = AWSSecurityTokenServiceClientBuilder.defaultClient()
.getCallerIdentity(new GetCallerIdentityRequest()).getAccount();
String bucketName = Constants.JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX + "-" + accountId;
String prefix = Constants.LEDGER_NAME + "-" + Instant.now().getEpochSecond() + "/";
S3EncryptionConfiguration encryptionConfiguration = new S3EncryptionConfiguration()
.withObjectEncryptionType(S3ObjectEncryptionType.SSE_S3);
ExportJournalToS3Result exportJournalToS3Result =
ExportJournal.createJournalExportAndAwaitCompletion(Constants.LEDGER_NAME,
bucketName, prefix, null, encryptionConfiguration, ExportJournal.DEFAULT_EXPORT_TIMEOUT_MS);
return exportJournalToS3Result.getExportId();
}
/**
* Validates that the chain hash on the {@link JournalBlock} is valid.
*
* @param journalBlocks
* {@link JournalBlock} containing hashes to validate.
* @throws IllegalStateException if previous block hash does not match.
*/
public static void verify(final List journalBlocks) {
if (journalBlocks.size() == 0) {
return;
}
journalBlocks.stream().reduce(null, (previousJournalBlock, journalBlock) -> {
journalBlock.verifyBlockHash();
if (previousJournalBlock == null) { return journalBlock; }
if (!Arrays.equals(previousJournalBlock.getBlockHash(), journalBlock.getPreviousBlockHash())) {
throw new IllegalStateException("Previous block hash doesn't match.");
}
byte[] blockHash = Verifier.dot(journalBlock.getEntriesHash(), previousJournalBlock.getBlockHash());
if (!Arrays.equals(blockHash, journalBlock.getBlockHash())) {
throw new IllegalStateException("Block hash doesn't match entriesHash dot previousBlockHash, the chain is "
+ "broken.");
}
return journalBlock;
});
}
public static void main(final String... args) throws InterruptedException {
try {
String exportId;
if (args.length == 1) {
exportId = args[0];
log.info("Validating QLDB hash chain for exportId: " + exportId);
} else {
log.info("Requesting QLDB to create an export.");
exportId = createExport();
}
List journalBlocks =
JournalS3ExportReader.readExport(DescribeJournalExport.describeExport(Constants.LEDGER_NAME,
exportId), AmazonS3ClientBuilder.defaultClient());
verify(journalBlocks);
} catch (Exception e) {
log.error("Unable to perform hash chain verification.", e);
throw e;
}
}
}
```
如果您不再需要使用`vehicle-registration`分類帳，請繼續 [步驟 9 （選用）：清除資源](getting-started.java.step-9.md)。
# 步驟 9 （選用）：清除資源
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
您可以繼續使用`vehicle-registration`分類帳。不過，如果您不再需要它，您應該將其刪除。
**刪除分類帳**
1. 編譯並執行下列程式 `vehicle-registration` (`DeleteLedger.java`)，以刪除您的分類帳及其所有內容。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.DeleteLedgerRequest;
import com.amazonaws.services.qldb.model.DeleteLedgerResult;
import com.amazonaws.services.qldb.model.ResourceNotFoundException;
import com.amazonaws.services.qldb.model.UpdateLedgerRequest;
import com.amazonaws.services.qldb.model.UpdateLedgerResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Delete a ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class DeleteLedger {
public static final Logger log = LoggerFactory.getLogger(DeleteLedger.class);
public static final Long LEDGER_DELETION_POLL_PERIOD_MS = 20_000L;
public static AmazonQLDB client = CreateLedger.getClient();
private DeleteLedger() { }
public static void main(String... args) throws Exception {
try {
setDeletionProtection(Constants.LEDGER_NAME, false);
delete(Constants.LEDGER_NAME);
waitForDeleted(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to delete the ledger.", e);
throw e;
}
}
/**
* Send a request to the QLDB database to delete the specified ledger.
*
* @param ledgerName
* Name of the ledger to be deleted.
* @return DeleteLedgerResult.
*/
public static DeleteLedgerResult delete(final String ledgerName) {
log.info("Attempting to delete the ledger with name: {}...", ledgerName);
DeleteLedgerRequest request = new DeleteLedgerRequest().withName(ledgerName);
DeleteLedgerResult result = client.deleteLedger(request);
log.info("Success.");
return result;
}
/**
* Wait for the ledger to be deleted.
*
* @param ledgerName
* Name of the ledger being deleted.
* @throws InterruptedException if thread is being interrupted.
*/
public static void waitForDeleted(final String ledgerName) throws InterruptedException {
log.info("Waiting for the ledger to be deleted...");
while (true) {
try {
DescribeLedger.describe(ledgerName);
log.info("The ledger is still being deleted. Please wait...");
Thread.sleep(LEDGER_DELETION_POLL_PERIOD_MS);
} catch (ResourceNotFoundException ex) {
log.info("Success. The ledger is deleted.");
break;
}
}
}
public static UpdateLedgerResult setDeletionProtection(String ledgerName, boolean deletionProtection) {
log.info("Let's set deletionProtection to {} for the ledger with name {}", deletionProtection, ledgerName);
UpdateLedgerRequest request = new UpdateLedgerRequest()
.withName(ledgerName)
.withDeletionProtection(deletionProtection);
UpdateLedgerResult result = client.updateLedger(request);
log.info("Success. Ledger updated: {}", result);
return result;
}
}
```
**注意**
如果您的分類帳已啟用刪除保護，您必須先停用它，才能使用 QLDB API 刪除分類帳。
1. 如果您在[上一個步驟](getting-started.java.step-8.md)中匯出日誌資料，但不再需要，請使用 Amazon S3 主控台來刪除 S3 儲存貯體。
開啟位於 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。
# Amazon QLDB Node.js 教學課程
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此教學課程範例應用程式的實作中，您可以使用 Amazon QLDB 驅動程式搭配 Node.js 中的適用於 JavaScript 的 AWS SDK 來建立 QLDB 分類帳，並填入範例資料。
當您完成本教學課程時，您可以參閱管理 API 操作的 API [適用於 JavaScript 的 AWS SDK 參考](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/)。對於交易資料操作，您可以參考適用於 [Node.js 的 QLDB 驅動程式 API 參考](https://amazon-qldb-docs.s3.amazonaws.com/drivers/nodejs/3.1.0/index.html)。
**注意**
在適用的情況下，某些教學課程步驟對於每個支援的主要版本的 Node.js QLDB 驅動程式都有不同的命令或程式碼範例。
**Topics**
+ [
# 安裝 Amazon QLDB Node.js 範例應用程式
](sample-app.nodejs.md)
+ [
# 步驟 1：建立新的分類帳
](getting-started.nodejs.step-1.md)
+ [
# 步驟 2：測試與分類帳的連線
](getting-started.nodejs.step-2.md)
+ [
# 步驟 3：建立資料表、索引和範例資料
](getting-started.nodejs.step-3.md)
+ [
# 步驟 4：查詢分類帳中的資料表
](getting-started.nodejs.step-4.md)
+ [
# 步驟 5：修改分類帳中的文件
](getting-started.nodejs.step-5.md)
+ [
# 步驟 6：檢視文件的修訂歷史記錄
](getting-started.nodejs.step-6.md)
+ [
# 步驟 7：驗證分類帳中的文件
](getting-started.nodejs.step-7.md)
+ [
# 步驟 8 （選用）：清除資源
](getting-started.nodejs.step-8.md)
# 安裝 Amazon QLDB Node.js 範例應用程式
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
本節說明如何為step-by-step Node.js 教學課程安裝和執行提供的 Amazon QLDB 範例應用程式。此範例應用程式的使用案例是機動車輛 (DMV) 資料庫部門，可追蹤車輛註冊的完整歷史資訊。
Node.js 的 DMV 範例應用程式是 GitHub 儲存庫 [aws-samples/amazon-qldb-dmv-sample-nodejs](https://github.com/aws-samples/amazon-qldb-dmv-sample-nodejs) 中的開放原始碼。
## 先決條件
開始之前，請確定您已完成 Node.js 的 QLDB 驅動程式[先決條件](getting-started.nodejs.md#getting-started.nodejs.prereqs)。這包括安裝 Node.js 和執行下列動作：
1. 註冊 AWS。
1. 建立具有適當 QLDB 許可的使用者。
1. 授予開發的程式設計存取權。
若要完成本教學課程中的所有步驟，您需要透過 QLDB API 完整存取您的分類帳資源。
## 安裝
**安裝範例應用程式**
1. 輸入下列命令，從 GitHub 複製範例應用程式。
------
#### [ 2.x ]
```
git clone https://github.com/aws-samples/amazon-qldb-dmv-sample-nodejs.git
```
------
#### [ 1.x ]
```
git clone -b v1.0.0 https://github.com/aws-samples/amazon-qldb-dmv-sample-nodejs.git
```
------
範例應用程式會封裝本教學課程的完整原始程式碼及其相依性，包括 Node.js 驅動程式和 [AWS Node.js 中適用於 JavaScript 的 SDK。](https://aws.amazon.com/sdk-for-node-js)此應用程式是以 TypeScript 撰寫。
1. 切換到複製`amazon-qldb-dmv-sample-nodejs`套件的目錄。
```
cd amazon-qldb-dmv-sample-nodejs
```
1. 對相依性進行乾淨的安裝。
```
npm ci
```
1. 傳輸套件。
```
npm run build
```
轉載的 JavaScript 檔案會寫入 `./dist`目錄中。
1. 前往 [步驟 1：建立新的分類帳](getting-started.nodejs.step-1.md) 開始教學課程並建立分類帳。
# 步驟 1：建立新的分類帳
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步驟中，您會建立新的 Amazon QLDB 分類帳，名為 `vehicle-registration`。
**建立新的分類帳**
1. 檢閱下列檔案 (`Constants.ts`)，其中包含本教學課程中所有其他程式所使用的常數值。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
/**
* Constant values used throughout this tutorial.
*/
export const LEDGER_NAME = "vehicle-registration";
export const LEDGER_NAME_WITH_TAGS = "tags";
export const DRIVERS_LICENSE_TABLE_NAME = "DriversLicense";
export const PERSON_TABLE_NAME = "Person";
export const VEHICLE_REGISTRATION_TABLE_NAME = "VehicleRegistration";
export const VEHICLE_TABLE_NAME = "Vehicle";
export const GOV_ID_INDEX_NAME = "GovId";
export const LICENSE_NUMBER_INDEX_NAME = "LicenseNumber";
export const LICENSE_PLATE_NUMBER_INDEX_NAME = "LicensePlateNumber";
export const PERSON_ID_INDEX_NAME = "PersonId";
export const VIN_INDEX_NAME = "VIN";
export const RETRY_LIMIT = 4;
export const JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX = "qldb-tutorial-journal-export";
export const USER_TABLES = "information_schema.user_tables";
```
1. 使用下列程式 (`CreateLedger.ts`) 建立名為 的分類帳`vehicle-registration`。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QLDB } from "aws-sdk";
import {
CreateLedgerRequest,
CreateLedgerResponse,
DescribeLedgerRequest,
DescribeLedgerResponse
} from "aws-sdk/clients/qldb";
import { LEDGER_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { sleep } from "./qldb/Util";
const LEDGER_CREATION_POLL_PERIOD_MS = 10000;
const ACTIVE_STATE = "ACTIVE";
/**
* Create a new ledger with the specified name.
* @param ledgerName Name of the ledger to be created.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with a CreateLedgerResponse.
*/
export async function createLedger(ledgerName: string, qldbClient: QLDB): Promise {
log(`Creating a ledger named: ${ledgerName}...`);
const request: CreateLedgerRequest = {
Name: ledgerName,
PermissionsMode: "ALLOW_ALL"
}
const result: CreateLedgerResponse = await qldbClient.createLedger(request).promise();
log(`Success. Ledger state: ${result.State}.`);
return result;
}
/**
* Wait for the newly created ledger to become active.
* @param ledgerName Name of the ledger to be checked on.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with a DescribeLedgerResponse.
*/
export async function waitForActive(ledgerName: string, qldbClient: QLDB): Promise {
log(`Waiting for ledger ${ledgerName} to become active...`);
const request: DescribeLedgerRequest = {
Name: ledgerName
}
while (true) {
const result: DescribeLedgerResponse = await qldbClient.describeLedger(request).promise();
if (result.State === ACTIVE_STATE) {
log("Success. Ledger is active and ready to be used.");
return result;
}
log("The ledger is still creating. Please wait...");
await sleep(LEDGER_CREATION_POLL_PERIOD_MS);
}
}
/**
* Create a ledger and wait for it to be active.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbClient: QLDB = new QLDB();
await createLedger(LEDGER_NAME, qldbClient);
await waitForActive(LEDGER_NAME, qldbClient);
} catch (e) {
error(`Unable to create the ledger: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
在`createLedger`通話中，您必須指定分類帳名稱和許可模式。我們建議您使用 `STANDARD` 許可模式，以最大限度地提高分類帳資料的安全性。
當您建立分類帳時，預設會啟用*刪除保護*。這是 QLDB 中的一項功能，可防止任何使用者刪除分類帳。您可以選擇使用 QLDB API 或 AWS Command Line Interface () 在建立分類帳時停用刪除保護AWS CLI。
或者，您也可以指定要連接到分類帳的標籤。
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/CreateLedger.js
```
若要驗證與新分類帳的連線，請繼續[步驟 2：測試與分類帳的連線](getting-started.nodejs.step-2.md)。
# 步驟 2：測試與分類帳的連線
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步驟中，您會驗證您可以使用交易資料 API `vehicle-registration` 端點連線到 Amazon QLDB 中的分類帳。
**測試與分類帳的連線**
1. 使用下列程式 `vehicle-registration` (`ConnectToLedger.ts`) 建立與分類帳的資料工作階段連線。
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver, RetryConfig } from "amazon-qldb-driver-nodejs";
import { ClientConfiguration } from "aws-sdk/clients/qldbsession";
import { LEDGER_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
const qldbDriver: QldbDriver = createQldbDriver();
/**
* Create a driver for creating sessions.
* @param ledgerName The name of the ledger to create the driver on.
* @param serviceConfigurationOptions The configurations for the AWS SDK client that the driver uses.
* @returns The driver for creating sessions.
*/
export function createQldbDriver(
ledgerName: string = LEDGER_NAME,
serviceConfigurationOptions: ClientConfiguration = {}
): QldbDriver {
const retryLimit = 4;
const maxConcurrentTransactions = 10;
//Use driver's default backoff function (and hence, no second parameter provided to RetryConfig)
const retryConfig: RetryConfig = new RetryConfig(retryLimit);
const qldbDriver: QldbDriver = new QldbDriver(ledgerName, serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);
return qldbDriver;
}
export function getQldbDriver(): QldbDriver {
return qldbDriver;
}
/**
* Connect to a session for a given ledger using default settings.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
log("Listing table names...");
const tableNames: string[] = await qldbDriver.getTableNames();
tableNames.forEach((tableName: string): void => {
log(tableName);
});
} catch (e) {
error(`Unable to create session: ${e}`);
}
}
if (require.main === module) {
main();
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver } from "amazon-qldb-driver-nodejs";
import { ClientConfiguration } from "aws-sdk/clients/qldbsession";
import { LEDGER_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
const qldbDriver: QldbDriver = createQldbDriver();
/**
* Create a driver for creating sessions.
* @param ledgerName The name of the ledger to create the driver on.
* @param serviceConfigurationOptions The configurations for the AWS SDK client that the driver uses.
* @returns The driver for creating sessions.
*/
export function createQldbDriver(
ledgerName: string = LEDGER_NAME,
serviceConfigurationOptions: ClientConfiguration = {}
): QldbDriver {
const qldbDriver: QldbDriver = new QldbDriver(ledgerName, serviceConfigurationOptions);
return qldbDriver;
}
export function getQldbDriver(): QldbDriver {
return qldbDriver;
}
/**
* Connect to a session for a given ledger using default settings.
* @returns Promise which fulfills with void.
*/
var main = async function(): Promise {
try {
log("Listing table names...");
const tableNames: string[] = await qldbDriver.getTableNames();
tableNames.forEach((tableName: string): void => {
log(tableName);
});
} catch (e) {
error(`Unable to create session: ${e}`);
}
}
if (require.main === module) {
main();
}
```
------
**注意**
若要在分類帳上執行資料交易，您必須建立 QLDB 驅動程式物件以連線到指定的分類帳。這是與您在[上一個步驟](getting-started.nodejs.step-1.md)中用來建立分類帳的物件不同的用戶端`qldbClient`物件。先前的用戶端僅用於執行 中列出的管理 API 操作[Amazon QLDB API 參考](api-reference.md)。
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/ConnectToLedger.js
```
若要在`vehicle-registration`分類帳中建立資料表，請繼續執行 [步驟 3：建立資料表、索引和範例資料](getting-started.nodejs.step-3.md)。
# 步驟 3：建立資料表、索引和範例資料
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
當您的 Amazon QLDB 分類帳處於作用中狀態並接受連線時，您可以開始為車輛、其擁有者及其註冊資訊的資料建立資料表。建立資料表和索引之後，您可以使用資料載入資料表和索引。
在此步驟中，您會在`vehicle-registration`分類帳中建立四個資料表：
+ `VehicleRegistration`
+ `Vehicle`
+ `Person`
+ `DriversLicense`
您也可以建立下列索引。
****
| 資料表名稱 | 欄位 |
| --- | --- |
| VehicleRegistration | VIN |
| VehicleRegistration | LicensePlateNumber |
| Vehicle | VIN |
| Person | GovId |
| DriversLicense | LicenseNumber |
| DriversLicense | PersonId |
插入範例資料時，您會先將文件插入`Person`資料表。然後，您可以使用`id`每個`Person`文件中由系統指派的 ，在適當的 `VehicleRegistration`和 `DriversLicense` 文件中填入對應的欄位。
**提示**
最佳實務是使用文件的系統指派`id`為外部金鑰。雖然您可以定義旨在成為唯一識別符的欄位 （例如，車輛的 VIN)，但文件的真正唯一識別符是其 `id`。此欄位包含在文件的中繼資料中，您可以在*遞交檢視* （資料表的系統定義檢視） 中查詢。
如需 QLDB 中檢視的詳細資訊，請參閱[核心概念](ledger-structure.md)。若要進一步了解中繼資料，請參閱 [查詢文件中繼資料](working.metadata.md)。
**建立資料表和索引**
1. 使用下列程式 (`CreateTable.ts`) 來建立先前提到的資料表。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { getQldbDriver } from "./ConnectToLedger";
import {
DRIVERS_LICENSE_TABLE_NAME,
PERSON_TABLE_NAME,
VEHICLE_REGISTRATION_TABLE_NAME,
VEHICLE_TABLE_NAME
} from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
/**
* Create multiple tables in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param tableName Name of the table to create.
* @returns Promise which fulfills with the number of changes to the database.
*/
export async function createTable(txn: TransactionExecutor, tableName: string): Promise {
const statement: string = `CREATE TABLE ${tableName}`;
return await txn.execute(statement).then((result: Result) => {
log(`Successfully created table ${tableName}.`);
return result.getResultList().length;
});
}
/**
* Create tables in a QLDB ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
Promise.all([
createTable(txn, VEHICLE_REGISTRATION_TABLE_NAME),
createTable(txn, VEHICLE_TABLE_NAME),
createTable(txn, PERSON_TABLE_NAME),
createTable(txn, DRIVERS_LICENSE_TABLE_NAME)
]);
});
} catch (e) {
error(`Unable to create tables: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
此程式示範如何在 QLDB 驅動程式執行個體中使用 `executeLambda`函數。在此範例中，您會使用單一 lambda 表達式執行多個 `CREATE TABLE` PartiQL 陳述式。
此執行函數會隱含地啟動交易、執行 lambda 中的所有陳述式，然後自動認可交易。
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/CreateTable.js
```
1. 使用下列程式 (`CreateIndex.ts`) 在資料表上建立索引，如前所述。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { getQldbDriver } from "./ConnectToLedger";
import {
DRIVERS_LICENSE_TABLE_NAME,
GOV_ID_INDEX_NAME,
LICENSE_NUMBER_INDEX_NAME,
LICENSE_PLATE_NUMBER_INDEX_NAME,
PERSON_ID_INDEX_NAME,
PERSON_TABLE_NAME,
VEHICLE_REGISTRATION_TABLE_NAME,
VEHICLE_TABLE_NAME,
VIN_INDEX_NAME
} from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
/**
* Create an index for a particular table.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param tableName Name of the table to add indexes for.
* @param indexAttribute Index to create on a single attribute.
* @returns Promise which fulfills with the number of changes to the database.
*/
export async function createIndex(
txn: TransactionExecutor,
tableName: string,
indexAttribute: string
): Promise {
const statement: string = `CREATE INDEX on ${tableName} (${indexAttribute})`;
return await txn.execute(statement).then((result) => {
log(`Successfully created index ${indexAttribute} on table ${tableName}.`);
return result.getResultList().length;
});
}
/**
* Create indexes on tables in a particular ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
Promise.all([
createIndex(txn, PERSON_TABLE_NAME, GOV_ID_INDEX_NAME),
createIndex(txn, VEHICLE_TABLE_NAME, VIN_INDEX_NAME),
createIndex(txn, VEHICLE_REGISTRATION_TABLE_NAME, VIN_INDEX_NAME),
createIndex(txn, VEHICLE_REGISTRATION_TABLE_NAME, LICENSE_PLATE_NUMBER_INDEX_NAME),
createIndex(txn, DRIVERS_LICENSE_TABLE_NAME, PERSON_ID_INDEX_NAME),
createIndex(txn, DRIVERS_LICENSE_TABLE_NAME, LICENSE_NUMBER_INDEX_NAME)
]);
});
} catch (e) {
error(`Unable to create indexes: ${e}`);
}
}
if (require.main === module) {
main();
}
```
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/CreateIndex.js
```
**將資料載入資料表**
1. 檢閱下列`.ts`檔案。
1. `SampleData.ts` – 包含您插入`vehicle-registration`資料表的範例資料。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { Decimal } from "ion-js";
const EMPTY_SECONDARY_OWNERS: object[] = [];
export const DRIVERS_LICENSE = [
{
PersonId: "",
LicenseNumber: "LEWISR261LL",
LicenseType: "Learner",
ValidFromDate: new Date("2016-12-20"),
ValidToDate: new Date("2020-11-15")
},
{
PersonId: "",
LicenseNumber : "LOGANB486CG",
LicenseType: "Probationary",
ValidFromDate : new Date("2016-04-06"),
ValidToDate : new Date("2020-11-15")
},
{
PersonId: "",
LicenseNumber : "744 849 301",
LicenseType: "Full",
ValidFromDate : new Date("2017-12-06"),
ValidToDate : new Date("2022-10-15")
},
{
PersonId: "",
LicenseNumber : "P626-168-229-765",
LicenseType: "Learner",
ValidFromDate : new Date("2017-08-16"),
ValidToDate : new Date("2021-11-15")
},
{
PersonId: "",
LicenseNumber : "S152-780-97-415-0",
LicenseType: "Probationary",
ValidFromDate : new Date("2015-08-15"),
ValidToDate : new Date("2021-08-21")
}
];
export const PERSON = [
{
FirstName : "Raul",
LastName : "Lewis",
DOB : new Date("1963-08-19"),
Address : "1719 University Street, Seattle, WA, 98109",
GovId : "LEWISR261LL",
GovIdType : "Driver License"
},
{
FirstName : "Brent",
LastName : "Logan",
DOB : new Date("1967-07-03"),
Address : "43 Stockert Hollow Road, Everett, WA, 98203",
GovId : "LOGANB486CG",
GovIdType : "Driver License"
},
{
FirstName : "Alexis",
LastName : "Pena",
DOB : new Date("1974-02-10"),
Address : "4058 Melrose Street, Spokane Valley, WA, 99206",
GovId : "744 849 301",
GovIdType : "SSN"
},
{
FirstName : "Melvin",
LastName : "Parker",
DOB : new Date("1976-05-22"),
Address : "4362 Ryder Avenue, Seattle, WA, 98101",
GovId : "P626-168-229-765",
GovIdType : "Passport"
},
{
FirstName : "Salvatore",
LastName : "Spencer",
DOB : new Date("1997-11-15"),
Address : "4450 Honeysuckle Lane, Seattle, WA, 98101",
GovId : "S152-780-97-415-0",
GovIdType : "Passport"
}
];
export const VEHICLE = [
{
VIN : "1N4AL11D75C109151",
Type : "Sedan",
Year : 2011,
Make : "Audi",
Model : "A5",
Color : "Silver"
},
{
VIN : "KM8SRDHF6EU074761",
Type : "Sedan",
Year : 2015,
Make : "Tesla",
Model : "Model S",
Color : "Blue"
},
{
VIN : "3HGGK5G53FM761765",
Type : "Motorcycle",
Year : 2011,
Make : "Ducati",
Model : "Monster 1200",
Color : "Yellow"
},
{
VIN : "1HVBBAANXWH544237",
Type : "Semi",
Year : 2009,
Make : "Ford",
Model : "F 150",
Color : "Black"
},
{
VIN : "1C4RJFAG0FC625797",
Type : "Sedan",
Year : 2019,
Make : "Mercedes",
Model : "CLK 350",
Color : "White"
}
];
export const VEHICLE_REGISTRATION = [
{
VIN : "1N4AL11D75C109151",
LicensePlateNumber : "LEWISR261LL",
State : "WA",
City : "Seattle",
ValidFromDate : new Date("2017-08-21"),
ValidToDate : new Date("2020-05-11"),
PendingPenaltyTicketAmount : new Decimal(9025, -2),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
},
{
VIN : "KM8SRDHF6EU074761",
LicensePlateNumber : "CA762X",
State : "WA",
City : "Kent",
PendingPenaltyTicketAmount : new Decimal(13075, -2),
ValidFromDate : new Date("2017-09-14"),
ValidToDate : new Date("2020-06-25"),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
},
{
VIN : "3HGGK5G53FM761765",
LicensePlateNumber : "CD820Z",
State : "WA",
City : "Everett",
PendingPenaltyTicketAmount : new Decimal(44230, -2),
ValidFromDate : new Date("2011-03-17"),
ValidToDate : new Date("2021-03-24"),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
},
{
VIN : "1HVBBAANXWH544237",
LicensePlateNumber : "LS477D",
State : "WA",
City : "Tacoma",
PendingPenaltyTicketAmount : new Decimal(4220, -2),
ValidFromDate : new Date("2011-10-26"),
ValidToDate : new Date("2023-09-25"),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
},
{
VIN : "1C4RJFAG0FC625797",
LicensePlateNumber : "TH393F",
State : "WA",
City : "Olympia",
PendingPenaltyTicketAmount : new Decimal(3045, -2),
ValidFromDate : new Date("2013-09-02"),
ValidToDate : new Date("2024-03-19"),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
}
];
```
1. `Util.ts` – 從`ion-js`套件匯入的公用程式模組，可提供轉換、剖析和列印 [Amazon Ion](ion.md) 資料的協助函式。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { GetBlockResponse, GetDigestResponse, ValueHolder } from "aws-sdk/clients/qldb";
import {
Decimal,
decodeUtf8,
dom,
IonTypes,
makePrettyWriter,
makeReader,
Reader,
Timestamp,
toBase64,
Writer
} from "ion-js";
import { error } from "./LogUtil";
/**
* TODO: Replace this with json.stringify
* Returns the string representation of a given BlockResponse.
* @param blockResponse The BlockResponse to convert to string.
* @returns The string representation of the supplied BlockResponse.
*/
export function blockResponseToString(blockResponse: GetBlockResponse): string {
let stringBuilder: string = "";
if (blockResponse.Block.IonText) {
stringBuilder = stringBuilder + "Block: " + blockResponse.Block.IonText + ", ";
}
if (blockResponse.Proof.IonText) {
stringBuilder = stringBuilder + "Proof: " + blockResponse.Proof.IonText;
}
stringBuilder = "{" + stringBuilder + "}";
const writer: Writer = makePrettyWriter();
const reader: Reader = makeReader(stringBuilder);
writer.writeValues(reader);
return decodeUtf8(writer.getBytes());
}
/**
* TODO: Replace this with json.stringify
* Returns the string representation of a given GetDigestResponse.
* @param digestResponse The GetDigestResponse to convert to string.
* @returns The string representation of the supplied GetDigestResponse.
*/
export function digestResponseToString(digestResponse: GetDigestResponse): string {
let stringBuilder: string = "";
if (digestResponse.Digest) {
stringBuilder += "Digest: " + JSON.stringify(toBase64( digestResponse.Digest)) + ", ";
}
if (digestResponse.DigestTipAddress.IonText) {
stringBuilder += "DigestTipAddress: " + digestResponse.DigestTipAddress.IonText;
}
stringBuilder = "{" + stringBuilder + "}";
const writer: Writer = makePrettyWriter();
const reader: Reader = makeReader(stringBuilder);
writer.writeValues(reader);
return decodeUtf8(writer.getBytes());
}
/**
* Get the document IDs from the given table.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param tableName The table name to query.
* @param field A field to query.
* @param value The key of the given field.
* @returns Promise which fulfills with the document ID as a string.
*/
export async function getDocumentId(
txn: TransactionExecutor,
tableName: string,
field: string,
value: string
): Promise {
const query: string = `SELECT id FROM ${tableName} AS t BY id WHERE t.${field} = ?`;
let documentId: string = undefined;
await txn.execute(query, value).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
if (resultList.length === 0) {
throw new Error(`Unable to retrieve document ID using ${value}.`);
}
documentId = resultList[0].get("id").stringValue();
}).catch((err: any) => {
error(`Error getting documentId: ${err}`);
});
return documentId;
}
/**
* Sleep for the specified amount of time.
* @param ms The amount of time to sleep in milliseconds.
* @returns Promise which fulfills with void.
*/
export function sleep(ms: number): Promise {
return new Promise(resolve => setTimeout(resolve, ms));
}
/**
* Find the value of a given path in an Ion value. The path should contain a blob value.
* @param value The Ion value that contains the journal block attributes.
* @param path The path to a certain attribute.
* @returns Uint8Array value of the blob, or null if the attribute cannot be found in the Ion value
* or is not of type Blob
*/
export function getBlobValue(value: dom.Value, path: string): Uint8Array | null {
const attribute: dom.Value = value.get(path);
if (attribute !== null && attribute.getType() === IonTypes.BLOB) {
return attribute.uInt8ArrayValue();
}
return null;
}
/**
* TODO: Replace this with json.stringify
* Returns the string representation of a given ValueHolder.
* @param valueHolder The ValueHolder to convert to string.
* @returns The string representation of the supplied ValueHolder.
*/
export function valueHolderToString(valueHolder: ValueHolder): string {
const stringBuilder: string = `{ IonText: ${valueHolder.IonText}}`;
const writer: Writer = makePrettyWriter();
const reader: Reader = makeReader(stringBuilder);
writer.writeValues(reader);
return decodeUtf8(writer.getBytes());
}
/**
* Converts a given value to Ion using the provided writer.
* @param value The value to convert to Ion.
* @param ionWriter The Writer to pass the value into.
* @throws Error: If the given value cannot be converted to Ion.
*/
export function writeValueAsIon(value: any, ionWriter: Writer): void {
switch (typeof value) {
case "string":
ionWriter.writeString(value);
break;
case "boolean":
ionWriter.writeBoolean(value);
break;
case "number":
ionWriter.writeInt(value);
break;
case "object":
if (Array.isArray(value)) {
// Object is an array.
ionWriter.stepIn(IonTypes.LIST);
for (const element of value) {
writeValueAsIon(element, ionWriter);
}
ionWriter.stepOut();
} else if (value instanceof Date) {
// Object is a Date.
ionWriter.writeTimestamp(Timestamp.parse(value.toISOString()));
} else if (value instanceof Decimal) {
// Object is a Decimal.
ionWriter.writeDecimal(value);
} else if (value === null) {
ionWriter.writeNull(IonTypes.NULL);
} else {
// Object is a struct.
ionWriter.stepIn(IonTypes.STRUCT);
for (const key of Object.keys(value)) {
ionWriter.writeFieldName(key);
writeValueAsIon(value[key], ionWriter);
}
ionWriter.stepOut();
}
break;
default:
throw new Error(`Cannot convert to Ion for type: ${(typeof value)}.`);
}
}
```
**注意**
`getDocumentId` 函數會執行查詢，從資料表傳回系統指派的文件 IDs。如需進一步了解，請參閱 [使用 BY 子句查詢文件 ID](working.metadata.by-clause.md)。
1. 使用下列程式 (`InsertDocument.ts`) 將範例資料插入資料表。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { DRIVERS_LICENSE, PERSON, VEHICLE, VEHICLE_REGISTRATION } from "./model/SampleData";
import {
DRIVERS_LICENSE_TABLE_NAME,
PERSON_TABLE_NAME,
VEHICLE_REGISTRATION_TABLE_NAME,
VEHICLE_TABLE_NAME
} from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
/**
* Insert the given list of documents into a table in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param tableName Name of the table to insert documents into.
* @param documents List of documents to insert.
* @returns Promise which fulfills with a {@linkcode Result} object.
*/
export async function insertDocument(
txn: TransactionExecutor,
tableName: string,
documents: object[]
): Promise {
const statement: string = `INSERT INTO ${tableName} ?`;
const result: Result = await txn.execute(statement, documents);
return result;
}
/**
* Handle the insertion of documents and updating PersonIds all in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @returns Promise which fulfills with void.
*/
async function updateAndInsertDocuments(txn: TransactionExecutor): Promise {
log("Inserting multiple documents into the 'Person' table...");
const documentIds: Result = await insertDocument(txn, PERSON_TABLE_NAME, PERSON);
const listOfDocumentIds: dom.Value[] = documentIds.getResultList();
log("Updating PersonIds for 'DriversLicense' and PrimaryOwner for 'VehicleRegistration'...");
updatePersonId(listOfDocumentIds);
log("Inserting multiple documents into the remaining tables...");
await Promise.all([
insertDocument(txn, DRIVERS_LICENSE_TABLE_NAME, DRIVERS_LICENSE),
insertDocument(txn, VEHICLE_REGISTRATION_TABLE_NAME, VEHICLE_REGISTRATION),
insertDocument(txn, VEHICLE_TABLE_NAME, VEHICLE)
]);
}
/**
* Update the PersonId value for DriversLicense records and the PrimaryOwner value for VehicleRegistration records.
* @param documentIds List of document IDs.
*/
export function updatePersonId(documentIds: dom.Value[]): void {
documentIds.forEach((value: dom.Value, i: number) => {
const documentId: string = value.get("documentId").stringValue();
DRIVERS_LICENSE[i].PersonId = documentId;
VEHICLE_REGISTRATION[i].Owners.PrimaryOwner.PersonId = documentId;
});
}
/**
* Insert documents into a table in a QLDB ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await updateAndInsertDocuments(txn);
});
} catch (e) {
error(`Unable to insert documents: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
此程式示範如何使用參數化值呼叫 `execute`函數。除了要執行的 PartiQL 陳述式之外，您還可以傳遞資料參數。在陳述式字串中使用問號 (`?`) 做為變數預留位置。
如果`INSERT`陳述式成功，則會傳回每個插入文件`id`的 。
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/InsertDocument.js
```
接下來，您可以使用`SELECT`陳述式從`vehicle-registration`分類帳中的資料表讀取資料。繼續執行「[步驟 4：查詢分類帳中的資料表](getting-started.nodejs.step-4.md)」。
# 步驟 4：查詢分類帳中的資料表
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在 Amazon QLDB 分類帳中建立資料表並使用資料載入資料表後，您可以執行查詢來檢閱您剛插入的車輛註冊資料。QLDB 使用 [PartiQL](ql-reference.md) 作為其查詢語言，而 [Amazon Ion](ion.md) 作為其文件導向資料模型。
PartiQL 是一種開放原始碼、與 SQL 相容的查詢語言，已擴充以使用 Ion。使用 PartiQL，您可以使用熟悉的 SQL 運算子插入、查詢和管理資料。Amazon Ion 是 JSON 的超集合。Ion 是一種開放原始碼、以文件為基礎的資料格式，可讓您靈活地儲存和處理結構化、半結構化和巢狀資料。
在此步驟中，您可以使用`SELECT`陳述式從`vehicle-registration`分類帳中的資料表讀取資料。
**警告**
當您在沒有索引查詢的情況下在 QLDB 中執行查詢時，它會叫用完整資料表掃描。PartiQL 支援此類查詢，因為它與 SQL 相容。不過，*請勿*在 QLDB 中執行生產使用案例的資料表掃描。資料表掃描可能會導致大型資料表的效能問題，包括並行衝突和交易逾時。
若要避免資料表掃描，您必須在索引欄位或文件 ID 上使用*等式*運算子，以`WHERE`述詞子句執行陳述式；例如， `WHERE indexedField = 123`或 `WHERE indexedField IN (456, 789)`。如需詳細資訊，請參閱[最佳化查詢效能](working.optimize.md)。
**查詢資料表**
1. 使用下列程式 (`FindVehicles.ts`) 來查詢您分類帳中人員下註冊的所有車輛。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { PERSON } from "./model/SampleData";
import { PERSON_TABLE_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { getDocumentId } from "./qldb/Util";
import { prettyPrintResultList } from "./ScanTable";
/**
* Query 'Vehicle' and 'VehicleRegistration' tables using a unique document ID in one transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param govId The owner's government ID.
* @returns Promise which fulfills with void.
*/
async function findVehiclesForOwner(txn: TransactionExecutor, govId: string): Promise {
const documentId: string = await getDocumentId(txn, PERSON_TABLE_NAME, "GovId", govId);
const query: string = "SELECT Vehicle FROM Vehicle INNER JOIN VehicleRegistration AS r " +
"ON Vehicle.VIN = r.VIN WHERE r.Owners.PrimaryOwner.PersonId = ?";
await txn.execute(query, documentId).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
log(`List of vehicles for owner with GovId: ${govId}`);
prettyPrintResultList(resultList);
});
}
/**
* Find all vehicles registered under a person.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await findVehiclesForOwner(txn, PERSON[0].GovId);
});
} catch (e) {
error(`Error getting vehicles for owner: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
首先，此程式會使用 查詢文件的`Person`資料表`GovId LEWISR261LL`，以取得其`id`中繼資料欄位。
然後，它會使用本文件`id`做為外部索引鍵，透過 查詢`VehicleRegistration`資料表`PrimaryOwner.PersonId`。它也會`VehicleRegistration`與 `VIN` 欄位上的 `Vehicle` 資料表聯結。
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/FindVehicles.js
```
若要了解如何修改 `vehicle-registration` 分類帳中資料表中的文件，請參閱 [步驟 5：修改分類帳中的文件](getting-started.nodejs.step-5.md)。
# 步驟 5：修改分類帳中的文件
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
既然您擁有要使用的資料，您就可以開始變更 Amazon QLDB `vehicle-registration` 中分類帳中的文件。在此步驟中，下列程式碼範例示範如何執行資料處理語言 (DML) 陳述式。這些陳述式會更新一輛車的主要擁有者，並將次要擁有者新增至另一輛車。
**修改文件**
1. 使用下列程式 (`TransferVehicleOwnership.ts`) 更新您分類帳`1N4AL11D75C109151`中具有 VIN 的車輛主要擁有者。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { PERSON, VEHICLE } from "./model/SampleData";
import { PERSON_TABLE_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { getDocumentId } from "./qldb/Util";
/**
* Query a driver's information using the given ID.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param documentId The unique ID of a document in the Person table.
* @returns Promise which fulfills with an Ion value containing the person.
*/
export async function findPersonFromDocumentId(txn: TransactionExecutor, documentId: string): Promise {
const query: string = "SELECT p.* FROM Person AS p BY pid WHERE pid = ?";
let personId: dom.Value;
await txn.execute(query, documentId).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
if (resultList.length === 0) {
throw new Error(`Unable to find person with ID: ${documentId}.`);
}
personId = resultList[0];
});
return personId;
}
/**
* Find the primary owner for the given VIN.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin The VIN to find primary owner for.
* @returns Promise which fulfills with an Ion value containing the primary owner.
*/
export async function findPrimaryOwnerForVehicle(txn: TransactionExecutor, vin: string): Promise {
log(`Finding primary owner for vehicle with VIN: ${vin}`);
const query: string = "SELECT Owners.PrimaryOwner.PersonId FROM VehicleRegistration AS v WHERE v.VIN = ?";
let documentId: string = undefined;
await txn.execute(query, vin).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
if (resultList.length === 0) {
throw new Error(`Unable to retrieve document ID using ${vin}.`);
}
const PersonIdValue: dom.Value = resultList[0].get("PersonId");
if (PersonIdValue === null) {
throw new Error(`Expected field name PersonId not found.`);
}
documentId = PersonIdValue.stringValue();
});
return findPersonFromDocumentId(txn, documentId);
}
/**
* Update the primary owner for a vehicle using the given VIN.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin The VIN for the vehicle to operate on.
* @param documentId New PersonId for the primary owner.
* @returns Promise which fulfills with void.
*/
async function updateVehicleRegistration(txn: TransactionExecutor, vin: string, documentId: string): Promise {
const statement: string = "UPDATE VehicleRegistration AS r SET r.Owners.PrimaryOwner.PersonId = ? WHERE r.VIN = ?";
log(`Updating the primary owner for vehicle with VIN: ${vin}...`);
await txn.execute(statement, documentId, vin).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
if (resultList.length === 0) {
throw new Error("Unable to transfer vehicle, could not find registration.");
}
log(`Successfully transferred vehicle with VIN ${vin} to new owner.`);
});
}
/**
* Validate the current owner of the given vehicle and transfer its ownership to a new owner in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin The VIN of the vehicle to transfer ownership of.
* @param currentOwner The GovId of the current owner of the vehicle.
* @param newOwner The GovId of the new owner of the vehicle.
*/
export async function validateAndUpdateRegistration(
txn: TransactionExecutor,
vin: string,
currentOwner: string,
newOwner: string
): Promise {
const primaryOwner: dom.Value = await findPrimaryOwnerForVehicle(txn, vin);
const govIdValue: dom.Value = primaryOwner.get("GovId");
if (govIdValue !== null && govIdValue.stringValue() !== currentOwner) {
log("Incorrect primary owner identified for vehicle, unable to transfer.");
}
else {
const documentId: string = await getDocumentId(txn, PERSON_TABLE_NAME, "GovId", newOwner);
await updateVehicleRegistration(txn, vin, documentId);
log("Successfully transferred vehicle ownership!");
}
}
/**
* Find primary owner for a particular vehicle's VIN.
* Transfer to another primary owner for a particular vehicle's VIN.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
const vin: string = VEHICLE[0].VIN;
const previousOwnerGovId: string = PERSON[0].GovId;
const newPrimaryOwnerGovId: string = PERSON[1].GovId;
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await validateAndUpdateRegistration(txn, vin, previousOwnerGovId, newPrimaryOwnerGovId);
});
} catch (e) {
error(`Unable to connect and run queries: ${e}`);
}
}
if (require.main === module) {
main();
}
```
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/TransferVehicleOwnership.js
```
1. 使用下列程式 (`AddSecondaryOwner.ts`) 將次要擁有者新增至您分類帳`KM8SRDHF6EU074761`中具有 VIN 的車輛。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { PERSON, VEHICLE_REGISTRATION } from "./model/SampleData";
import { PERSON_TABLE_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { getDocumentId } from "./qldb/Util";
import { prettyPrintResultList } from "./ScanTable";
/**
* Add a secondary owner into 'VehicleRegistration' table for a particular VIN.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin VIN of the vehicle to query.
* @param secondaryOwnerId The secondary owner's person ID.
* @returns Promise which fulfills with void.
*/
export async function addSecondaryOwner(
txn: TransactionExecutor,
vin: string,
secondaryOwnerId: string
): Promise {
log(`Inserting secondary owner for vehicle with VIN: ${vin}`);
const query: string =
`FROM VehicleRegistration AS v WHERE v.VIN = ? INSERT INTO v.Owners.SecondaryOwners VALUE ?`;
const personToInsert = {PersonId: secondaryOwnerId};
await txn.execute(query, vin, personToInsert).then(async (result: Result) => {
const resultList: dom.Value[] = result.getResultList();
log("VehicleRegistration Document IDs which had secondary owners added: ");
prettyPrintResultList(resultList);
});
}
/**
* Query for a document ID with a government ID.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param governmentId The government ID to query with.
* @returns Promise which fulfills with the document ID as a string.
*/
export async function getDocumentIdByGovId(txn: TransactionExecutor, governmentId: string): Promise {
const documentId: string = await getDocumentId(txn, PERSON_TABLE_NAME, "GovId", governmentId);
return documentId;
}
/**
* Check whether a driver has already been registered for the given VIN.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin VIN of the vehicle to query.
* @param secondaryOwnerId The secondary owner's person ID.
* @returns Promise which fulfills with a boolean.
*/
export async function isSecondaryOwnerForVehicle(
txn: TransactionExecutor,
vin: string,
secondaryOwnerId: string
): Promise {
log(`Finding secondary owners for vehicle with VIN: ${vin}`);
const query: string = "SELECT Owners.SecondaryOwners FROM VehicleRegistration AS v WHERE v.VIN = ?";
let doesExist: boolean = false;
await txn.execute(query, vin).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
resultList.forEach((value: dom.Value) => {
const secondaryOwnersList: dom.Value[] = value.get("SecondaryOwners").elements();
secondaryOwnersList.forEach((secondaryOwner) => {
const personId: dom.Value = secondaryOwner.get("PersonId");
if (personId !== null && personId.stringValue() === secondaryOwnerId) {
doesExist = true;
}
});
});
});
return doesExist;
}
/**
* Finds and adds secondary owners for a vehicle.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
const vin: string = VEHICLE_REGISTRATION[1].VIN;
const govId: string = PERSON[0].GovId;
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
const documentId: string = await getDocumentIdByGovId(txn, govId);
if (await isSecondaryOwnerForVehicle(txn, vin, documentId)) {
log(`Person with ID ${documentId} has already been added as a secondary owner of this vehicle.`);
} else {
await addSecondaryOwner(txn, vin, documentId);
}
});
log("Secondary owners successfully updated.");
} catch (e) {
error(`Unable to add secondary owner: ${e}`);
}
}
if (require.main === module) {
main();
}
```
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/AddSecondaryOwner.js
```
若要檢閱`vehicle-registration`分類帳中的這些變更，請參閱 [步驟 6：檢視文件的修訂歷史記錄](getting-started.nodejs.step-6.md)。
# 步驟 6：檢視文件的修訂歷史記錄
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在[上一個步驟](getting-started.nodejs.step-5.md)中修改車輛的註冊資料後，您可以查詢其所有已註冊擁有者的歷史記錄和任何其他更新的欄位。在此步驟中，您會查詢 `vehicle-registration` 分類帳中`VehicleRegistration`資料表中文件的修訂歷史記錄。
**檢視修訂歷史記錄**
1. 使用下列程式 (`QueryHistory.ts`) 查詢具有 VIN `VehicleRegistration`的文件修訂歷史記錄`1N4AL11D75C109151`。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { VEHICLE_REGISTRATION } from "./model/SampleData";
import { VEHICLE_REGISTRATION_TABLE_NAME } from "./qldb/Constants";
import { prettyPrintResultList } from "./ScanTable";
import { error, log } from "./qldb/LogUtil";
import { getDocumentId } from "./qldb/Util";
/**
* Find previous primary owners for the given VIN in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin The VIN to find previous primary owners for.
* @returns Promise which fulfills with void.
*/
async function previousPrimaryOwners(txn: TransactionExecutor, vin: string): Promise {
const documentId: string = await getDocumentId(txn, VEHICLE_REGISTRATION_TABLE_NAME, "VIN", vin);
const todaysDate: Date = new Date();
// set todaysDate back one minute to ensure end time is in the past
// by the time the request reaches our backend
todaysDate.setMinutes(todaysDate.getMinutes() - 1);
const threeMonthsAgo: Date = new Date(todaysDate);
threeMonthsAgo.setMonth(todaysDate.getMonth() - 3);
const query: string =
`SELECT data.Owners.PrimaryOwner, metadata.version FROM history ` +
`(${VEHICLE_REGISTRATION_TABLE_NAME}, \`${threeMonthsAgo.toISOString()}\`, \`${todaysDate.toISOString()}\`) ` +
`AS h WHERE h.metadata.id = ?`;
await txn.execute(query, documentId).then((result: Result) => {
log(`Querying the 'VehicleRegistration' table's history using VIN: ${vin}.`);
const resultList: dom.Value[] = result.getResultList();
prettyPrintResultList(resultList);
});
}
/**
* Query a table's history for a particular set of documents.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
const vin: string = VEHICLE_REGISTRATION[0].VIN;
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await previousPrimaryOwners(txn, vin);
});
} catch (e) {
error(`Unable to query history to find previous owners: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
您可以在下列語法[歷史記錄函數](working.history.md#working.history.function)中查詢內建 ，以檢視文件的修訂歷史記錄。
```
SELECT * FROM history( table_name [, `start-time` [, `end-time` ] ] ) AS h
[ WHERE h.metadata.id = 'id' ]
```
*開始時間*和*結束時間*皆為選用。它們是 Amazon Ion 常值，可以用反引號表示 (``...``)。如需詳細資訊，請參閱[在 Amazon QLDB 中使用 PartiQL 查詢離子](ql-reference.query.md)。
最佳實務是，使用日期範圍 *（開始時間*和*結束時間*) 和文件 ID () 來限定歷史記錄查詢`metadata.id`。QLDB 會在交易中處理`SELECT`查詢，這些查詢受到[交易逾時限制](limits.md#limits.fixed)的限制。
QLDB 歷史記錄會依文件 ID 編製索引，此時您無法建立其他歷史記錄索引。包含開始時間和結束時間的歷史記錄查詢，可受益於日期範圍資格。
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/QueryHistory.js
```
若要以密碼編譯方式驗證`vehicle-registration`分類帳中的文件修訂，請繼續 [步驟 7：驗證分類帳中的文件](getting-started.nodejs.step-7.md)。
# 步驟 7：驗證分類帳中的文件
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
使用 Amazon QLDB，您可以搭配 SHA-256 使用密碼編譯雜湊，有效率地驗證分類帳日誌中文件的完整性。若要進一步了解驗證和密碼編譯雜湊如何在 QLDB 中運作，請參閱[Amazon QLDB 中的資料驗證](verification.md)。
在此步驟中，您要驗證 `vehicle-registration` 分類帳中`VehicleRegistration`資料表中的文件修訂。首先，您請求摘要，該摘要會傳回為輸出檔案，並做為您分類帳整個變更歷史記錄的簽章。然後，您請求修訂相對於該摘要的證明。如果所有驗證檢查都通過，則會使用此驗證，驗證修訂的完整性。
**驗證文件修訂**
1. 檢閱下列`.ts`檔案，其中包含驗證所需的 QLDB 物件。
1. `BlockAddress.ts`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { ValueHolder } from "aws-sdk/clients/qldb";
import { dom, IonTypes } from "ion-js";
export class BlockAddress {
_strandId: string;
_sequenceNo: number;
constructor(strandId: string, sequenceNo: number) {
this._strandId = strandId;
this._sequenceNo = sequenceNo;
}
}
/**
* Convert a block address from an Ion value into a ValueHolder.
* Shape of the ValueHolder must be: {'IonText': "{strandId: <"strandId">, sequenceNo: }"}
* @param value The Ion value that contains the block address values to convert.
* @returns The ValueHolder that contains the strandId and sequenceNo.
*/
export function blockAddressToValueHolder(value: dom.Value): ValueHolder {
const blockAddressValue : dom.Value = getBlockAddressValue(value);
const strandId: string = getStrandId(blockAddressValue);
const sequenceNo: number = getSequenceNo(blockAddressValue);
const valueHolder: string = `{strandId: "${strandId}", sequenceNo: ${sequenceNo}}`;
const blockAddress: ValueHolder = {IonText: valueHolder};
return blockAddress;
}
/**
* Helper method that to get the Metadata ID.
* @param value The Ion value.
* @returns The Metadata ID.
*/
export function getMetadataId(value: dom.Value): string {
const metaDataId: dom.Value = value.get("id");
if (metaDataId === null) {
throw new Error(`Expected field name id, but not found.`);
}
return metaDataId.stringValue();
}
/**
* Helper method to get the Sequence No.
* @param value The Ion value.
* @returns The Sequence No.
*/
export function getSequenceNo(value : dom.Value): number {
const sequenceNo: dom.Value = value.get("sequenceNo");
if (sequenceNo === null) {
throw new Error(`Expected field name sequenceNo, but not found.`);
}
return sequenceNo.numberValue();
}
/**
* Helper method to get the Strand ID.
* @param value The Ion value.
* @returns The Strand ID.
*/
export function getStrandId(value: dom.Value): string {
const strandId: dom.Value = value.get("strandId");
if (strandId === null) {
throw new Error(`Expected field name strandId, but not found.`);
}
return strandId.stringValue();
}
export function getBlockAddressValue(value: dom.Value) : dom.Value {
const type = value.getType();
if (type !== IonTypes.STRUCT) {
throw new Error(`Unexpected format: expected struct, but got IonType: ${type.name}`);
}
const blockAddress: dom.Value = value.get("blockAddress");
if (blockAddress == null) {
throw new Error(`Expected field name blockAddress, but not found.`);
}
return blockAddress;
}
```
1. `Verifier.ts`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { Digest, ValueHolder } from "aws-sdk/clients/qldb";
import { createHash } from "crypto";
import { dom, toBase64 } from "ion-js";
import { getBlobValue } from "./Util";
const HASH_LENGTH: number = 32;
const UPPER_BOUND: number = 8;
/**
* Build the candidate digest representing the entire ledger from the Proof hashes.
* @param proof The Proof object.
* @param leafHash The revision hash to pair with the first hash in the Proof hashes list.
* @returns The calculated root hash.
*/
function buildCandidateDigest(proof: ValueHolder, leafHash: Uint8Array): Uint8Array {
const parsedProof: Uint8Array[] = parseProof(proof);
const rootHash: Uint8Array = calculateRootHashFromInternalHash(parsedProof, leafHash);
return rootHash;
}
/**
* Combine the internal hashes and the leaf hash until only one root hash remains.
* @param internalHashes An array of hash values.
* @param leafHash The revision hash to pair with the first hash in the Proof hashes list.
* @returns The root hash constructed by combining internal hashes.
*/
function calculateRootHashFromInternalHash(internalHashes: Uint8Array[], leafHash: Uint8Array): Uint8Array {
const rootHash: Uint8Array = internalHashes.reduce(joinHashesPairwise, leafHash);
return rootHash;
}
/**
* Compare two hash values by converting each Uint8Array byte, which is unsigned by default,
* into a signed byte, assuming they are little endian.
* @param hash1 The hash value to compare.
* @param hash2 The hash value to compare.
* @returns Zero if the hash values are equal, otherwise return the difference of the first pair of non-matching bytes.
*/
function compareHashValues(hash1: Uint8Array, hash2: Uint8Array): number {
if (hash1.length !== HASH_LENGTH || hash2.length !== HASH_LENGTH) {
throw new Error("Invalid hash.");
}
for (let i = hash1.length-1; i >= 0; i--) {
const difference: number = (hash1[i]<<24 >>24) - (hash2[i]<<24 >>24);
if (difference !== 0) {
return difference;
}
}
return 0;
}
/**
* Helper method that concatenates two Uint8Array.
* @param arrays List of array to concatenate, in the order provided.
* @returns The concatenated array.
*/
function concatenate(...arrays: Uint8Array[]): Uint8Array {
let totalLength = 0;
for (const arr of arrays) {
totalLength += arr.length;
}
const result = new Uint8Array(totalLength);
let offset = 0;
for (const arr of arrays) {
result.set(arr, offset);
offset += arr.length;
}
return result;
}
/**
* Flip a single random bit in the given hash value.
* This method is intended to be used for purpose of demonstrating the QLDB verification features only.
* @param original The hash value to alter.
* @returns The altered hash with a single random bit changed.
*/
export function flipRandomBit(original: any): Uint8Array {
if (original.length === 0) {
throw new Error("Array cannot be empty!");
}
const bytePos: number = Math.floor(Math.random() * original.length);
const bitShift: number = Math.floor(Math.random() * UPPER_BOUND);
const alteredHash: Uint8Array = original;
alteredHash[bytePos] = alteredHash[bytePos] ^ (1 << bitShift);
return alteredHash;
}
/**
* Take two hash values, sort them, concatenate them, and generate a new hash value from the concatenated values.
* @param h1 Byte array containing one of the hashes to compare.
* @param h2 Byte array containing one of the hashes to compare.
* @returns The concatenated array of hashes.
*/
export function joinHashesPairwise(h1: Uint8Array, h2: Uint8Array): Uint8Array {
if (h1.length === 0) {
return h2;
}
if (h2.length === 0) {
return h1;
}
let concat: Uint8Array;
if (compareHashValues(h1, h2) < 0) {
concat = concatenate(h1, h2);
} else {
concat = concatenate(h2, h1);
}
const hash = createHash('sha256');
hash.update(concat);
const newDigest: Uint8Array = hash.digest();
return newDigest;
}
/**
* Parse the Block object returned by QLDB and retrieve block hash.
* @param valueHolder A structure containing an Ion string value.
* @returns The block hash.
*/
export function parseBlock(valueHolder: ValueHolder): Uint8Array {
const block: dom.Value = dom.load(valueHolder.IonText);
const blockHash: Uint8Array = getBlobValue(block, "blockHash");
return blockHash;
}
/**
* Parse the Proof object returned by QLDB into an iterator.
* The Proof object returned by QLDB is a dictionary like the following:
* {'IonText': '[{{}},{{}}]'}
* @param valueHolder A structure containing an Ion string value.
* @returns A list of hash values.
*/
function parseProof(valueHolder: ValueHolder): Uint8Array[] {
const proofs : dom.Value = dom.load(valueHolder.IonText);
return proofs.elements().map(proof => proof.uInt8ArrayValue());
}
/**
* Verify document revision against the provided digest.
* @param documentHash The SHA-256 value representing the document revision to be verified.
* @param digest The SHA-256 hash value representing the ledger digest.
* @param proof The Proof object retrieved from GetRevision.getRevision.
* @returns If the document revision verifies against the ledger digest.
*/
export function verifyDocument(documentHash: Uint8Array, digest: Digest, proof: ValueHolder): boolean {
const candidateDigest = buildCandidateDigest(proof, documentHash);
return (toBase64( digest) === toBase64(candidateDigest));
}
```
1. 使用兩個`.ts`程式 (`GetDigest.ts` 和 `GetRevision.ts`) 來執行下列步驟：
+ 從`vehicle-registration`分類帳請求新的摘要。
+ 從 `1N4AL11D75C109151` `VehicleRegistration` 資料表請求具有 VIN 之文件的每個修訂的證明。
+ 透過重新計算摘要，使用傳回的摘要和驗證來驗證修訂。
`GetDigest.ts` 程式包含下列程式碼。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QLDB } from "aws-sdk";
import { GetDigestRequest, GetDigestResponse } from "aws-sdk/clients/qldb";
import { LEDGER_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { digestResponseToString } from "./qldb/Util";
/**
* Get the digest of a ledger's journal.
* @param ledgerName Name of the ledger to operate on.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with a GetDigestResponse.
*/
export async function getDigestResult(ledgerName: string, qldbClient: QLDB): Promise {
const request: GetDigestRequest = {
Name: ledgerName
};
const result: GetDigestResponse = await qldbClient.getDigest(request).promise();
return result;
}
/**
* This is an example for retrieving the digest of a particular ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbClient: QLDB = new QLDB();
log(`Retrieving the current digest for ledger: ${LEDGER_NAME}.`);
const digest: GetDigestResponse = await getDigestResult(LEDGER_NAME, qldbClient);
log(`Success. Ledger digest: \n${digestResponseToString(digest)}.`);
} catch (e) {
error(`Unable to get a ledger digest: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
使用 `getDigest`函數來請求摘要，其中涵蓋您分類帳中日誌的目前*提示*。日誌的提示是指截至 QLDB 收到您的請求時的最新遞交區塊。
`GetRevision.ts` 程式包含下列程式碼。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { QLDB } from "aws-sdk";
import { Digest, GetDigestResponse, GetRevisionRequest, GetRevisionResponse, ValueHolder } from "aws-sdk/clients/qldb";
import { dom, toBase64 } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { getDigestResult } from './GetDigest';
import { VEHICLE_REGISTRATION } from "./model/SampleData"
import { blockAddressToValueHolder, getMetadataId } from './qldb/BlockAddress';
import { LEDGER_NAME } from './qldb/Constants';
import { error, log } from "./qldb/LogUtil";
import { getBlobValue, valueHolderToString } from "./qldb/Util";
import { flipRandomBit, verifyDocument } from "./qldb/Verifier";
/**
* Get the revision data object for a specified document ID and block address.
* Also returns a proof of the specified revision for verification.
* @param ledgerName Name of the ledger containing the document to query.
* @param documentId Unique ID for the document to be verified, contained in the committed view of the document.
* @param blockAddress The location of the block to request.
* @param digestTipAddress The latest block location covered by the digest.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with a GetRevisionResponse.
*/
async function getRevision(
ledgerName: string,
documentId: string,
blockAddress: ValueHolder,
digestTipAddress: ValueHolder,
qldbClient: QLDB
): Promise {
const request: GetRevisionRequest = {
Name: ledgerName,
BlockAddress: blockAddress,
DocumentId: documentId,
DigestTipAddress: digestTipAddress
};
const result: GetRevisionResponse = await qldbClient.getRevision(request).promise();
return result;
}
/**
* Query the table metadata for a particular vehicle for verification.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin VIN to query the table metadata of a specific registration with.
* @returns Promise which fulfills with a list of Ion values that contains the results of the query.
*/
export async function lookupRegistrationForVin(txn: TransactionExecutor, vin: string): Promise {
log(`Querying the 'VehicleRegistration' table for VIN: ${vin}...`);
let resultList: dom.Value[];
const query: string = "SELECT blockAddress, metadata.id FROM _ql_committed_VehicleRegistration WHERE data.VIN = ?";
await txn.execute(query, vin).then(function(result) {
resultList = result.getResultList();
});
return resultList;
}
/**
* Verify each version of the registration for the given VIN.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param ledgerName The ledger to get the digest from.
* @param vin VIN to query the revision history of a specific registration with.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with void.
* @throws Error: When verification fails.
*/
export async function verifyRegistration(
txn: TransactionExecutor,
ledgerName: string,
vin: string,
qldbClient: QLDB
): Promise {
log(`Let's verify the registration with VIN = ${vin}, in ledger = ${ledgerName}.`);
const digest: GetDigestResponse = await getDigestResult(ledgerName, qldbClient);
const digestBytes: Digest = digest.Digest;
const digestTipAddress: ValueHolder = digest.DigestTipAddress;
log(
`Got a ledger digest: digest tip address = \n${valueHolderToString(digestTipAddress)},
digest = \n${toBase64( digestBytes)}.`
);
log(`Querying the registration with VIN = ${vin} to verify each version of the registration...`);
const resultList: dom.Value[] = await lookupRegistrationForVin(txn, vin);
log("Getting a proof for the document.");
for (const result of resultList) {
const blockAddress: ValueHolder = blockAddressToValueHolder(result);
const documentId: string = getMetadataId(result);
const revisionResponse: GetRevisionResponse = await getRevision(
ledgerName,
documentId,
blockAddress,
digestTipAddress,
qldbClient
);
const revision: dom.Value = dom.load(revisionResponse.Revision.IonText);
const documentHash: Uint8Array = getBlobValue(revision, "hash");
const proof: ValueHolder = revisionResponse.Proof;
log(`Got back a proof: ${valueHolderToString(proof)}.`);
let verified: boolean = verifyDocument(documentHash, digestBytes, proof);
if (!verified) {
throw new Error("Document revision is not verified.");
} else {
log("Success! The document is verified.");
}
const alteredDocumentHash: Uint8Array = flipRandomBit(documentHash);
log(
`Flipping one bit in the document's hash and assert that the document is NOT verified.
The altered document hash is: ${toBase64(alteredDocumentHash)}`
);
verified = verifyDocument(alteredDocumentHash, digestBytes, proof);
if (verified) {
throw new Error("Expected altered document hash to not be verified against digest.");
} else {
log("Success! As expected flipping a bit in the document hash causes verification to fail.");
}
log(`Finished verifying the registration with VIN = ${vin} in ledger = ${ledgerName}.`);
}
}
/**
* Verify the integrity of a document revision in a QLDB ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbClient: QLDB = new QLDB();
const qldbDriver: QldbDriver = getQldbDriver();
const registration = VEHICLE_REGISTRATION[0];
const vin: string = registration.VIN;
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await verifyRegistration(txn, LEDGER_NAME, vin, qldbClient);
});
} catch (e) {
error(`Unable to verify revision: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
`getRevision` 函數傳回指定文件修訂的證明後，此程式會使用用戶端 API 來驗證該修訂。
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/GetRevision.js
```
如果您不再需要使用`vehicle-registration`分類帳，請繼續 [步驟 8 （選用）：清除資源](getting-started.nodejs.step-8.md)。
# 步驟 8 （選用）：清除資源
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
您可以繼續使用`vehicle-registration`分類帳。不過，如果您不再需要它，您應該將其刪除。
**刪除分類帳**
1. 使用下列程式 `vehicle-registration` (`DeleteLedger.ts`) 刪除您的分類帳及其所有內容。
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
import { isResourceNotFoundException } from "amazon-qldb-driver-nodejs";
import { AWSError, QLDB } from "aws-sdk";
import { DeleteLedgerRequest, DescribeLedgerRequest } from "aws-sdk/clients/qldb";
import { setDeletionProtection } from "./DeletionProtection";
import { LEDGER_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { sleep } from "./qldb/Util";
const LEDGER_DELETION_POLL_PERIOD_MS = 20000;
/**
* Send a request to QLDB to delete the specified ledger.
* @param ledgerName Name of the ledger to be deleted.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with void.
*/
export async function deleteLedger(ledgerName: string, qldbClient: QLDB): Promise {
log(`Attempting to delete the ledger with name: ${ledgerName}`);
const request: DeleteLedgerRequest = {
Name: ledgerName
};
await qldbClient.deleteLedger(request).promise();
log("Success.");
}
/**
* Wait for the ledger to be deleted.
* @param ledgerName Name of the ledger to be deleted.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with void.
*/
export async function waitForDeleted(ledgerName: string, qldbClient: QLDB): Promise {
log("Waiting for the ledger to be deleted...");
const request: DescribeLedgerRequest = {
Name: ledgerName
};
let isDeleted: boolean = false;
while (true) {
await qldbClient.describeLedger(request).promise().catch((error: AWSError) => {
if (isResourceNotFoundException(error)) {
isDeleted = true;
log("Success. Ledger is deleted.");
}
});
if (isDeleted) {
break;
}
log("The ledger is still being deleted. Please wait...");
await sleep(LEDGER_DELETION_POLL_PERIOD_MS);
}
}
/**
* Delete a ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbClient: QLDB = new QLDB();
await setDeletionProtection(LEDGER_NAME, qldbClient, false);
await deleteLedger(LEDGER_NAME, qldbClient);
await waitForDeleted(LEDGER_NAME, qldbClient);
} catch (e) {
error(`Unable to delete the ledger: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
如果您的分類帳已啟用刪除保護，您必須先停用它，才能使用 QLDB API 刪除分類帳。
1. 若要執行轉載程式，請輸入下列命令。
```
node dist/DeleteLedger.js
```
# Amazon QLDB Python 教學課程
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此教學課程範例應用程式的實作中，您可以使用 Amazon QLDB 驅動程式搭配 適用於 Python (Boto3) 的 AWS SDK 來建立 QLDB 分類帳，並填入範例資料。
當您完成本教學課程時，可以在適用於 *AWS Python (Boto3) 的 SDK API 參考*中參考 [QLDB 低階用戶端](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/qldb.html)，以進行管理 API 操作。對於交易資料操作，您可以參考 [QLDB Driver for Python API Reference](https://amazon-qldb-driver-python.readthedocs.io/en/stable/)。
**注意**
在適用的情況下，某些教學課程步驟對於 Python 的 QLDB 驅動程式的每個支援主要版本都有不同的命令或程式碼範例。
**Topics**
+ [
# 安裝 Amazon QLDB Python 範例應用程式
](sample-app.python.md)
+ [
# 步驟 1：建立新的分類帳
](getting-started.python.step-1.md)
+ [
# 步驟 2：測試與分類帳的連線
](getting-started.python.step-2.md)
+ [
# 步驟 3：建立資料表、索引和範例資料
](getting-started.python.step-3.md)
+ [
# 步驟 4：查詢分類帳中的資料表
](getting-started.python.step-4.md)
+ [
# 步驟 5：修改分類帳中的文件
](getting-started.python.step-5.md)
+ [
# 步驟 6：檢視文件的修訂歷史記錄
](getting-started.python.step-6.md)
+ [
# 步驟 7：驗證分類帳中的文件
](getting-started.python.step-7.md)
+ [
# 步驟 8 （選用）：清除資源
](getting-started.python.step-8.md)
# 安裝 Amazon QLDB Python 範例應用程式
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
本節說明如何安裝和執行逐步 Python step-by-step 教學課程提供的 Amazon QLDB 範例應用程式。此範例應用程式的使用案例是機動車輛 (DMV) 資料庫的部門，可追蹤車輛註冊的完整歷史資訊。
Python 的 DMV 範例應用程式是 GitHub 儲存庫 [aws-samples/amazon-qldb-dmv-sample-python](https://github.com/aws-samples/amazon-qldb-dmv-sample-python) 中的開放原始碼。
## 先決條件
開始之前，請確定您已完成適用於 Python 的 QLDB 驅動程式[先決條件](getting-started.python.md#getting-started.python.prereqs)。這包括安裝 Python 並執行下列動作：
1. 註冊 AWS。
1. 建立具有適當 QLDB 許可的使用者。
1. 授予開發的程式設計存取權。
若要完成本教學課程中的所有步驟，您需要透過 QLDB API 完整存取您的分類帳資源。
## 安裝
**安裝範例應用程式**
1. 輸入下列`pip`命令，從 GitHub 複製並安裝範例應用程式。
------
#### [ 3.x ]
```
pip install git+https://github.com/aws-samples/amazon-qldb-dmv-sample-python.git
```
------
#### [ 2.x ]
```
pip install git+https://github.com/aws-samples/amazon-qldb-dmv-sample-python.git@v1.0.0
```
------
範例應用程式會封裝本教學課程的完整原始程式碼及其相依性，包括 Python 驅動程式和 [適用於 Python (Boto3) 的 AWS SDK](https://aws.amazon.com/sdk-for-python)。
1. 在您開始在命令列執行程式碼之前，請將您目前的工作目錄切換到安裝`pyqldbsamples`套件的位置。輸入以下命令。
```
cd $(python -c "import pyqldbsamples; print(pyqldbsamples.__path__[0])")
```
1. 前往 [步驟 1：建立新的分類帳](getting-started.python.step-1.md) 以開始教學課程並建立分類帳。
# 步驟 1：建立新的分類帳
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步驟中，您會建立新的 Amazon QLDB 分類帳，名稱為 `vehicle-registration`。
**建立新的分類帳**
1. 檢閱下列檔案 (`constants.py`)，其中包含本教學課程中所有其他程式所使用的常數值。
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
class Constants:
"""
Constant values used throughout this tutorial.
"""
LEDGER_NAME = "vehicle-registration"
VEHICLE_REGISTRATION_TABLE_NAME = "VehicleRegistration"
VEHICLE_TABLE_NAME = "Vehicle"
PERSON_TABLE_NAME = "Person"
DRIVERS_LICENSE_TABLE_NAME = "DriversLicense"
LICENSE_NUMBER_INDEX_NAME = "LicenseNumber"
GOV_ID_INDEX_NAME = "GovId"
VEHICLE_VIN_INDEX_NAME = "VIN"
LICENSE_PLATE_NUMBER_INDEX_NAME = "LicensePlateNumber"
PERSON_ID_INDEX_NAME = "PersonId"
JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX = "qldb-tutorial-journal-export"
USER_TABLES = "information_schema.user_tables"
S3_BUCKET_ARN_TEMPLATE = "arn:aws:s3:::"
LEDGER_NAME_WITH_TAGS = "tags"
RETRY_LIMIT = 4
```
1. 使用下列程式 (`create_ledger.py`) 來建立名為 的分類帳`vehicle-registration`。
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from time import sleep
from boto3 import client
from pyqldbsamples.constants import Constants
logger = getLogger(__name__)
basicConfig(level=INFO)
qldb_client = client('qldb')
LEDGER_CREATION_POLL_PERIOD_SEC = 10
ACTIVE_STATE = "ACTIVE"
def create_ledger(name):
"""
Create a new ledger with the specified name.
:type name: str
:param name: Name for the ledger to be created.
:rtype: dict
:return: Result from the request.
"""
logger.info("Let's create the ledger named: {}...".format(name))
result = qldb_client.create_ledger(Name=name, PermissionsMode='ALLOW_ALL')
logger.info('Success. Ledger state: {}.'.format(result.get('State')))
return result
def wait_for_active(name):
"""
Wait for the newly created ledger to become active.
:type name: str
:param name: The ledger to check on.
:rtype: dict
:return: Result from the request.
"""
logger.info('Waiting for ledger to become active...')
while True:
result = qldb_client.describe_ledger(Name=name)
if result.get('State') == ACTIVE_STATE:
logger.info('Success. Ledger is active and ready to use.')
return result
logger.info('The ledger is still creating. Please wait...')
sleep(LEDGER_CREATION_POLL_PERIOD_SEC)
def main(ledger_name=Constants.LEDGER_NAME):
"""
Create a ledger and wait for it to be active.
"""
try:
create_ledger(ledger_name)
wait_for_active(ledger_name)
except Exception as e:
logger.exception('Unable to create the ledger!')
raise e
if __name__ == '__main__':
main()
```
**注意**
在`create_ledger`通話中，您必須指定分類帳名稱和許可模式。我們建議您使用 `STANDARD` 許可模式，將分類帳資料的安全性最大化。
當您建立分類帳時，預設會啟用*刪除保護*。這是 QLDB 中的一項功能，可防止任何使用者刪除分類帳。您可以選擇使用 QLDB API 或 AWS Command Line Interface () 在建立分類帳時停用刪除保護AWS CLI。
您也可以選擇性地指定要連接到分類帳的標籤。
1. 若要執行程式，請輸入下列命令。
```
python create_ledger.py
```
若要驗證與新分類帳的連線，請繼續 [步驟 2：測試與分類帳的連線](getting-started.python.step-2.md)。
# 步驟 2：測試與分類帳的連線
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步驟中，您會驗證您可以使用交易資料 API `vehicle-registration` 端點連線到 Amazon QLDB 中的分類帳。
**測試與分類帳的連線**
1. 使用下列程式 `vehicle-registration` (`connect_to_ledger.py`) 建立與分類帳的資料工作階段連線。
------
#### [ 3.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from botocore.exceptions import ClientError
from pyqldb.driver.qldb_driver import QldbDriver
from pyqldbsamples.constants import Constants
logger = getLogger(__name__)
basicConfig(level=INFO)
def create_qldb_driver(ledger_name=Constants.LEDGER_NAME, region_name=None, endpoint_url=None, boto3_session=None):
"""
Create a QLDB driver for executing transactions.
:type ledger_name: str
:param ledger_name: The QLDB ledger name.
:type region_name: str
:param region_name: See [1].
:type endpoint_url: str
:param endpoint_url: See [1].
:type boto3_session: :py:class:`boto3.session.Session`
:param boto3_session: The boto3 session to create the client with (see [1]).
:rtype: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:return: A QLDB driver object.
[1]: `Boto3 Session.client Reference `.
"""
qldb_driver = QldbDriver(ledger_name=ledger_name, region_name=region_name, endpoint_url=endpoint_url,
boto3_session=boto3_session)
return qldb_driver
def main(ledger_name=Constants.LEDGER_NAME):
"""
Connect to a given ledger using default settings.
"""
try:
with create_qldb_driver(ledger_name) as driver:
logger.info('Listing table names ')
for table in driver.list_tables():
logger.info(table)
except ClientError as ce:
logger.exception('Unable to list tables.')
raise ce
if __name__ == '__main__':
main()
```
**注意**
若要在分類帳上執行資料交易，您必須建立 QLDB 驅動程式物件以連線到特定分類帳。這是與您在上一個步驟中用來建立分類帳的物件不同的用戶端`qldb_client`物件。先前的用戶端僅用於執行 中列出的管理 API 操作[Amazon QLDB API 參考](api-reference.md)。
建立此驅動程式物件時，您必須指定分類帳名稱。
------
#### [ 2.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from botocore.exceptions import ClientError
from pyqldb.driver.pooled_qldb_driver import PooledQldbDriver
from pyqldbsamples.constants import Constants
logger = getLogger(__name__)
basicConfig(level=INFO)
def create_qldb_driver(ledger_name=Constants.LEDGER_NAME, region_name=None, endpoint_url=None, boto3_session=None):
"""
Create a QLDB driver for creating sessions.
:type ledger_name: str
:param ledger_name: The QLDB ledger name.
:type region_name: str
:param region_name: See [1].
:type endpoint_url: str
:param endpoint_url: See [1].
:type boto3_session: :py:class:`boto3.session.Session`
:param boto3_session: The boto3 session to create the client with (see [1]).
:rtype: :py:class:`pyqldb.driver.pooled_qldb_driver.PooledQldbDriver`
:return: A pooled QLDB driver object.
[1]: `Boto3 Session.client Reference `.
"""
qldb_driver = PooledQldbDriver(ledger_name=ledger_name, region_name=region_name, endpoint_url=endpoint_url,
boto3_session=boto3_session)
return qldb_driver
def create_qldb_session():
"""
Retrieve a QLDB session object.
:rtype: :py:class:`pyqldb.session.pooled_qldb_session.PooledQldbSession`
:return: A pooled QLDB session object.
"""
qldb_session = pooled_qldb_driver.get_session()
return qldb_session
pooled_qldb_driver = create_qldb_driver()
if __name__ == '__main__':
"""
Connect to a session for a given ledger using default settings.
"""
try:
qldb_session = create_qldb_session()
logger.info('Listing table names ')
for table in qldb_session.list_tables():
logger.info(table)
except ClientError:
logger.exception('Unable to create session.')
```
**注意**
若要在分類帳上執行資料交易，您必須建立 QLDB 驅動程式物件以連線到特定分類帳。這是與您在上一個步驟中用來建立分類帳的物件不同的用戶端`qldb_client`物件。先前的用戶端僅用於執行 中列出的管理 API 操作[Amazon QLDB API 參考](api-reference.md)。
首先，建立集區 QLDB 驅動程式物件。建立此驅動程式時，您必須指定分類帳名稱。
然後，您可以從此集區驅動程式物件建立工作階段。
------
1. 若要執行程式，請輸入下列命令。
```
python connect_to_ledger.py
```
若要在`vehicle-registration`分類帳中建立資料表，請繼續執行 [步驟 3：建立資料表、索引和範例資料](getting-started.python.step-3.md)。
# 步驟 3：建立資料表、索引和範例資料
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
當您的 Amazon QLDB 分類帳處於作用中狀態並接受連線時，您可以開始為車輛、其擁有者及其註冊資訊的資料建立資料表。建立資料表和索引之後，您可以使用資料載入它們。
在此步驟中，您會在`vehicle-registration`分類帳中建立四個資料表：
+ `VehicleRegistration`
+ `Vehicle`
+ `Person`
+ `DriversLicense`
您也可以建立下列索引。
****
| 資料表名稱 | 欄位 |
| --- | --- |
| VehicleRegistration | VIN |
| VehicleRegistration | LicensePlateNumber |
| Vehicle | VIN |
| Person | GovId |
| DriversLicense | LicenseNumber |
| DriversLicense | PersonId |
插入範例資料時，首先將文件插入`Person`資料表。然後，您可以使用`id`每個`Person`文件中由系統指派的 ，在適當的 `VehicleRegistration`和 `DriversLicense` 文件中填入對應的欄位。
**提示**
最佳實務是使用文件的系統指派`id`為外部金鑰。雖然您可以定義旨在作為唯一識別符的欄位 （例如，車輛的 VIN)，但文件的真正唯一識別符是其 `id`。此欄位包含在文件的中繼資料中，您可以在*遞交檢視*中查詢 （資料表的系統定義檢視）。
如需 QLDB 中檢視的詳細資訊，請參閱[核心概念](ledger-structure.md)。若要進一步了解中繼資料，請參閱 [查詢文件中繼資料](working.metadata.md)。
**建立資料表和索引**
1. 使用下列程式 (`create_table.py`) 來建立先前提到的資料表。
------
#### [ 3.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_driver
logger = getLogger(__name__)
basicConfig(level=INFO)
def create_table(driver, table_name):
"""
Create a table with the specified name.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type table_name: str
:param table_name: Name of the table to create.
:rtype: int
:return: The number of changes to the database.
"""
logger.info("Creating the '{}' table...".format(table_name))
statement = 'CREATE TABLE {}'.format(table_name)
cursor = driver.execute_lambda(lambda executor: executor.execute_statement(statement))
logger.info('{} table created successfully.'.format(table_name))
return len(list(cursor))
def main(ledger_name=Constants.LEDGER_NAME):
"""
Create registrations, vehicles, owners, and licenses tables.
"""
try:
with create_qldb_driver(ledger_name) as driver:
create_table(driver, Constants.DRIVERS_LICENSE_TABLE_NAME)
create_table(driver, Constants.PERSON_TABLE_NAME)
create_table(driver, Constants.VEHICLE_TABLE_NAME)
create_table(driver, Constants.VEHICLE_REGISTRATION_TABLE_NAME)
logger.info('Tables created successfully.')
except Exception as e:
logger.exception('Errors creating tables.')
raise e
if __name__ == '__main__':
main()
```
------
#### [ 2.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_session
logger = getLogger(__name__)
basicConfig(level=INFO)
def create_table(transaction_executor, table_name):
"""
Create a table with the specified name using an Executor object.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type table_name: str
:param table_name: Name of the table to create.
:rtype: int
:return: The number of changes to the database.
"""
logger.info("Creating the '{}' table...".format(table_name))
statement = 'CREATE TABLE {}'.format(table_name)
cursor = transaction_executor.execute_statement(statement)
logger.info('{} table created successfully.'.format(table_name))
return len(list(cursor))
if __name__ == '__main__':
"""
Create registrations, vehicles, owners, and licenses tables in a single transaction.
"""
try:
with create_qldb_session() as session:
session.execute_lambda(lambda x: create_table(x, Constants.DRIVERS_LICENSE_TABLE_NAME) and
create_table(x, Constants.PERSON_TABLE_NAME) and
create_table(x, Constants.VEHICLE_TABLE_NAME) and
create_table(x, Constants.VEHICLE_REGISTRATION_TABLE_NAME),
lambda retry_attempt: logger.info('Retrying due to OCC conflict...'))
logger.info('Tables created successfully.')
except Exception:
logger.exception('Errors creating tables.')
```
------
**注意**
此程式示範如何使用 `execute_lambda`函數。在此範例中，您會使用單一 lambda 表達式執行多個 `CREATE TABLE` PartiQL 陳述式。
此執行函數會隱含地啟動交易、執行 lambda 中的所有陳述式，然後自動遞交交易。
1. 若要執行程式，請輸入下列命令。
```
python create_table.py
```
1. 使用下列程式 (`create_index.py`) 在資料表上建立索引，如前所述。
------
#### [ 3.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_driver
logger = getLogger(__name__)
basicConfig(level=INFO)
def create_index(driver, table_name, index_attribute):
"""
Create an index for a particular table.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type table_name: str
:param table_name: Name of the table to add indexes for.
:type index_attribute: str
:param index_attribute: Index to create on a single attribute.
:rtype: int
:return: The number of changes to the database.
"""
logger.info("Creating index on '{}'...".format(index_attribute))
statement = 'CREATE INDEX on {} ({})'.format(table_name, index_attribute)
cursor = driver.execute_lambda(lambda executor: executor.execute_statement(statement))
return len(list(cursor))
def main(ledger_name=Constants.LEDGER_NAME):
"""
Create indexes on tables in a particular ledger.
"""
logger.info('Creating indexes on all tables...')
try:
with create_qldb_driver(ledger_name) as driver:
create_index(driver, Constants.PERSON_TABLE_NAME, Constants.GOV_ID_INDEX_NAME)
create_index(driver, Constants.VEHICLE_TABLE_NAME, Constants.VEHICLE_VIN_INDEX_NAME)
create_index(driver, Constants.VEHICLE_REGISTRATION_TABLE_NAME, Constants.LICENSE_PLATE_NUMBER_INDEX_NAME)
create_index(driver, Constants.VEHICLE_REGISTRATION_TABLE_NAME, Constants.VEHICLE_VIN_INDEX_NAME)
create_index(driver, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.PERSON_ID_INDEX_NAME)
create_index(driver, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.LICENSE_NUMBER_INDEX_NAME)
logger.info('Indexes created successfully.')
except Exception as e:
logger.exception('Unable to create indexes.')
raise e
if __name__ == '__main__':
main()
```
------
#### [ 2.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_session
logger = getLogger(__name__)
basicConfig(level=INFO)
def create_index(transaction_executor, table_name, index_attribute):
"""
Create an index for a particular table.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type table_name: str
:param table_name: Name of the table to add indexes for.
:type index_attribute: str
:param index_attribute: Index to create on a single attribute.
:rtype: int
:return: The number of changes to the database.
"""
logger.info("Creating index on '{}'...".format(index_attribute))
statement = 'CREATE INDEX on {} ({})'.format(table_name, index_attribute)
cursor = transaction_executor.execute_statement(statement)
return len(list(cursor))
if __name__ == '__main__':
"""
Create indexes on tables in a particular ledger.
"""
logger.info('Creating indexes on all tables in a single transaction...')
try:
with create_qldb_session() as session:
session.execute_lambda(lambda x: create_index(x, Constants.PERSON_TABLE_NAME,
Constants.GOV_ID_INDEX_NAME)
and create_index(x, Constants.VEHICLE_TABLE_NAME,
Constants.VEHICLE_VIN_INDEX_NAME)
and create_index(x, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Constants.LICENSE_PLATE_NUMBER_INDEX_NAME)
and create_index(x, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Constants.VEHICLE_VIN_INDEX_NAME)
and create_index(x, Constants.DRIVERS_LICENSE_TABLE_NAME,
Constants.PERSON_ID_INDEX_NAME)
and create_index(x, Constants.DRIVERS_LICENSE_TABLE_NAME,
Constants.LICENSE_NUMBER_INDEX_NAME),
lambda retry_attempt: logger.info('Retrying due to OCC conflict...'))
logger.info('Indexes created successfully.')
except Exception:
logger.exception('Unable to create indexes.')
```
------
1. 若要執行程式，請輸入下列命令。
```
python create_index.py
```
**將資料載入資料表**
1. 檢閱下列檔案 (`sample_data.py`)，其代表您插入`vehicle-registration`資料表的範例資料。此檔案也會從`amazon.ion`套件匯入，以提供協助程式函數來轉換、剖析和列印 [Amazon Ion](ion.md) 資料。
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
from datetime import datetime
from decimal import Decimal
from logging import basicConfig, getLogger, INFO
from amazon.ion.simple_types import IonPyBool, IonPyBytes, IonPyDecimal, IonPyDict, IonPyFloat, IonPyInt, IonPyList, \
IonPyNull, IonPySymbol, IonPyText, IonPyTimestamp
from amazon.ion.simpleion import dumps, loads
logger = getLogger(__name__)
basicConfig(level=INFO)
IonValue = (IonPyBool, IonPyBytes, IonPyDecimal, IonPyDict, IonPyFloat, IonPyInt, IonPyList, IonPyNull, IonPySymbol,
IonPyText, IonPyTimestamp)
class SampleData:
"""
Sample domain objects for use throughout this tutorial.
"""
DRIVERS_LICENSE = [
{
'PersonId': '',
'LicenseNumber': 'LEWISR261LL',
'LicenseType': 'Learner',
'ValidFromDate': datetime(2016, 12, 20),
'ValidToDate': datetime(2020, 11, 15)
},
{
'PersonId': '',
'LicenseNumber': 'LOGANB486CG',
'LicenseType': 'Probationary',
'ValidFromDate': datetime(2016, 4, 6),
'ValidToDate': datetime(2020, 11, 15)
},
{
'PersonId': '',
'LicenseNumber': '744 849 301',
'LicenseType': 'Full',
'ValidFromDate': datetime(2017, 12, 6),
'ValidToDate': datetime(2022, 10, 15)
},
{
'PersonId': '',
'LicenseNumber': 'P626-168-229-765',
'LicenseType': 'Learner',
'ValidFromDate': datetime(2017, 8, 16),
'ValidToDate': datetime(2021, 11, 15)
},
{
'PersonId': '',
'LicenseNumber': 'S152-780-97-415-0',
'LicenseType': 'Probationary',
'ValidFromDate': datetime(2015, 8, 15),
'ValidToDate': datetime(2021, 8, 21)
}
]
PERSON = [
{
'FirstName': 'Raul',
'LastName': 'Lewis',
'Address': '1719 University Street, Seattle, WA, 98109',
'DOB': datetime(1963, 8, 19),
'GovId': 'LEWISR261LL',
'GovIdType': 'Driver License'
},
{
'FirstName': 'Brent',
'LastName': 'Logan',
'DOB': datetime(1967, 7, 3),
'Address': '43 Stockert Hollow Road, Everett, WA, 98203',
'GovId': 'LOGANB486CG',
'GovIdType': 'Driver License'
},
{
'FirstName': 'Alexis',
'LastName': 'Pena',
'DOB': datetime(1974, 2, 10),
'Address': '4058 Melrose Street, Spokane Valley, WA, 99206',
'GovId': '744 849 301',
'GovIdType': 'SSN'
},
{
'FirstName': 'Melvin',
'LastName': 'Parker',
'DOB': datetime(1976, 5, 22),
'Address': '4362 Ryder Avenue, Seattle, WA, 98101',
'GovId': 'P626-168-229-765',
'GovIdType': 'Passport'
},
{
'FirstName': 'Salvatore',
'LastName': 'Spencer',
'DOB': datetime(1997, 11, 15),
'Address': '4450 Honeysuckle Lane, Seattle, WA, 98101',
'GovId': 'S152-780-97-415-0',
'GovIdType': 'Passport'
}
]
VEHICLE = [
{
'VIN': '1N4AL11D75C109151',
'Type': 'Sedan',
'Year': 2011,
'Make': 'Audi',
'Model': 'A5',
'Color': 'Silver'
},
{
'VIN': 'KM8SRDHF6EU074761',
'Type': 'Sedan',
'Year': 2015,
'Make': 'Tesla',
'Model': 'Model S',
'Color': 'Blue'
},
{
'VIN': '3HGGK5G53FM761765',
'Type': 'Motorcycle',
'Year': 2011,
'Make': 'Ducati',
'Model': 'Monster 1200',
'Color': 'Yellow'
},
{
'VIN': '1HVBBAANXWH544237',
'Type': 'Semi',
'Year': 2009,
'Make': 'Ford',
'Model': 'F 150',
'Color': 'Black'
},
{
'VIN': '1C4RJFAG0FC625797',
'Type': 'Sedan',
'Year': 2019,
'Make': 'Mercedes',
'Model': 'CLK 350',
'Color': 'White'
}
]
VEHICLE_REGISTRATION = [
{
'VIN': '1N4AL11D75C109151',
'LicensePlateNumber': 'LEWISR261LL',
'State': 'WA',
'City': 'Seattle',
'ValidFromDate': datetime(2017, 8, 21),
'ValidToDate': datetime(2020, 5, 11),
'PendingPenaltyTicketAmount': Decimal('90.25'),
'Owners': {
'PrimaryOwner': {'PersonId': ''},
'SecondaryOwners': []
}
},
{
'VIN': 'KM8SRDHF6EU074761',
'LicensePlateNumber': 'CA762X',
'State': 'WA',
'City': 'Kent',
'PendingPenaltyTicketAmount': Decimal('130.75'),
'ValidFromDate': datetime(2017, 9, 14),
'ValidToDate': datetime(2020, 6, 25),
'Owners': {
'PrimaryOwner': {'PersonId': ''},
'SecondaryOwners': []
}
},
{
'VIN': '3HGGK5G53FM761765',
'LicensePlateNumber': 'CD820Z',
'State': 'WA',
'City': 'Everett',
'PendingPenaltyTicketAmount': Decimal('442.30'),
'ValidFromDate': datetime(2011, 3, 17),
'ValidToDate': datetime(2021, 3, 24),
'Owners': {
'PrimaryOwner': {'PersonId': ''},
'SecondaryOwners': []
}
},
{
'VIN': '1HVBBAANXWH544237',
'LicensePlateNumber': 'LS477D',
'State': 'WA',
'City': 'Tacoma',
'PendingPenaltyTicketAmount': Decimal('42.20'),
'ValidFromDate': datetime(2011, 10, 26),
'ValidToDate': datetime(2023, 9, 25),
'Owners': {
'PrimaryOwner': {'PersonId': ''},
'SecondaryOwners': []
}
},
{
'VIN': '1C4RJFAG0FC625797',
'LicensePlateNumber': 'TH393F',
'State': 'WA',
'City': 'Olympia',
'PendingPenaltyTicketAmount': Decimal('30.45'),
'ValidFromDate': datetime(2013, 9, 2),
'ValidToDate': datetime(2024, 3, 19),
'Owners': {
'PrimaryOwner': {'PersonId': ''},
'SecondaryOwners': []
}
}
]
def convert_object_to_ion(py_object):
"""
Convert a Python object into an Ion object.
:type py_object: object
:param py_object: The object to convert.
:rtype: :py:class:`amazon.ion.simple_types.IonPyValue`
:return: The converted Ion object.
"""
ion_object = loads(dumps(py_object))
return ion_object
def to_ion_struct(key, value):
"""
Convert the given key and value into an Ion struct.
:type key: str
:param key: The key which serves as an unique identifier.
:type value: str
:param value: The value associated with a given key.
:rtype: :py:class:`amazon.ion.simple_types.IonPyDict`
:return: The Ion dictionary object.
"""
ion_struct = dict()
ion_struct[key] = value
return loads(str(ion_struct))
def get_document_ids(transaction_executor, table_name, field, value):
"""
Gets the document IDs from the given table.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type table_name: str
:param table_name: The table name to query.
:type field: str
:param field: A field to query.
:type value: str
:param value: The key of the given field.
:rtype: list
:return: A list of document IDs.
"""
query = "SELECT id FROM {} AS t BY id WHERE t.{} = ?".format(table_name, field)
cursor = transaction_executor.execute_statement(query, convert_object_to_ion(value))
return list(map(lambda table: table.get('id'), cursor))
def get_document_ids_from_dml_results(result):
"""
Return a list of modified document IDs as strings from DML results.
:type result: :py:class:`pyqldb.cursor.buffered_cursor.BufferedCursor`
:param: result: The result set from DML operation.
:rtype: list
:return: List of document IDs.
"""
ret_val = list(map(lambda x: x.get('documentId'), result))
return ret_val
def print_result(cursor):
"""
Pretty print the result set. Returns the number of documents in the result set.
:type cursor: :py:class:`pyqldb.cursor.stream_cursor.StreamCursor`/
:py:class:`pyqldb.cursor.buffered_cursor.BufferedCursor`
:param cursor: An instance of the StreamCursor or BufferedCursor class.
:rtype: int
:return: Number of documents in the result set.
"""
result_counter = 0
for row in cursor:
# Each row would be in Ion format.
print_ion(row)
result_counter += 1
return result_counter
def print_ion(ion_value):
"""
Pretty print an Ion Value.
:type ion_value: :py:class:`amazon.ion.simple_types.IonPySymbol`
:param ion_value: Any Ion Value to be pretty printed.
"""
logger.info(dumps(ion_value, binary=False, indent=' ', omit_version_marker=True))
```
**注意**
`get_document_ids` 函數會執行查詢，從資料表傳回系統指派的文件 IDs。如需進一步了解，請參閱 [使用 BY 子句查詢文件 ID](working.metadata.by-clause.md)。
1. 使用下列程式 (`insert_document.py`) 將範例資料插入資料表。
------
#### [ 3.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.constants import Constants
from pyqldbsamples.model.sample_data import convert_object_to_ion, SampleData, get_document_ids_from_dml_results
from pyqldbsamples.connect_to_ledger import create_qldb_driver
logger = getLogger(__name__)
basicConfig(level=INFO)
def update_person_id(document_ids):
"""
Update the PersonId value for DriversLicense records and the PrimaryOwner value for VehicleRegistration records.
:type document_ids: list
:param document_ids: List of document IDs.
:rtype: list
:return: Lists of updated DriversLicense records and updated VehicleRegistration records.
"""
new_drivers_licenses = SampleData.DRIVERS_LICENSE.copy()
new_vehicle_registrations = SampleData.VEHICLE_REGISTRATION.copy()
for i in range(len(SampleData.PERSON)):
drivers_license = new_drivers_licenses[i]
registration = new_vehicle_registrations[i]
drivers_license.update({'PersonId': str(document_ids[i])})
registration['Owners']['PrimaryOwner'].update({'PersonId': str(document_ids[i])})
return new_drivers_licenses, new_vehicle_registrations
def insert_documents(driver, table_name, documents):
"""
Insert the given list of documents into a table in a single transaction.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type table_name: str
:param table_name: Name of the table to insert documents into.
:type documents: list
:param documents: List of documents to insert.
:rtype: list
:return: List of documents IDs for the newly inserted documents.
"""
logger.info('Inserting some documents in the {} table...'.format(table_name))
statement = 'INSERT INTO {} ?'.format(table_name)
cursor = driver.execute_lambda(lambda executor: executor.execute_statement(statement,
convert_object_to_ion(documents)))
list_of_document_ids = get_document_ids_from_dml_results(cursor)
return list_of_document_ids
def update_and_insert_documents(driver):
"""
Handle the insertion of documents and updating PersonIds.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
"""
list_ids = insert_documents(driver, Constants.PERSON_TABLE_NAME, SampleData.PERSON)
logger.info("Updating PersonIds for 'DriversLicense' and PrimaryOwner for 'VehicleRegistration'...")
new_licenses, new_registrations = update_person_id(list_ids)
insert_documents(driver, Constants.VEHICLE_TABLE_NAME, SampleData.VEHICLE)
insert_documents(driver, Constants.VEHICLE_REGISTRATION_TABLE_NAME, new_registrations)
insert_documents(driver, Constants.DRIVERS_LICENSE_TABLE_NAME, new_licenses)
def main(ledger_name=Constants.LEDGER_NAME):
"""
Insert documents into a table in a QLDB ledger.
"""
try:
with create_qldb_driver(ledger_name) as driver:
# An INSERT statement creates the initial revision of a document with a version number of zero.
# QLDB also assigns a unique document identifier in GUID format as part of the metadata.
update_and_insert_documents(driver)
logger.info('Documents inserted successfully!')
except Exception as e:
logger.exception('Error inserting or updating documents.')
raise e
if __name__ == '__main__':
main()
```
------
#### [ 2.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.constants import Constants
from pyqldbsamples.model.sample_data import convert_object_to_ion, SampleData, get_document_ids_from_dml_results
from pyqldbsamples.connect_to_ledger import create_qldb_session
logger = getLogger(__name__)
basicConfig(level=INFO)
def update_person_id(document_ids):
"""
Update the PersonId value for DriversLicense records and the PrimaryOwner value for VehicleRegistration records.
:type document_ids: list
:param document_ids: List of document IDs.
:rtype: list
:return: Lists of updated DriversLicense records and updated VehicleRegistration records.
"""
new_drivers_licenses = SampleData.DRIVERS_LICENSE.copy()
new_vehicle_registrations = SampleData.VEHICLE_REGISTRATION.copy()
for i in range(len(SampleData.PERSON)):
drivers_license = new_drivers_licenses[i]
registration = new_vehicle_registrations[i]
drivers_license.update({'PersonId': str(document_ids[i])})
registration['Owners']['PrimaryOwner'].update({'PersonId': str(document_ids[i])})
return new_drivers_licenses, new_vehicle_registrations
def insert_documents(transaction_executor, table_name, documents):
"""
Insert the given list of documents into a table in a single transaction.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type table_name: str
:param table_name: Name of the table to insert documents into.
:type documents: list
:param documents: List of documents to insert.
:rtype: list
:return: List of documents IDs for the newly inserted documents.
"""
logger.info('Inserting some documents in the {} table...'.format(table_name))
statement = 'INSERT INTO {} ?'.format(table_name)
cursor = transaction_executor.execute_statement(statement, convert_object_to_ion(documents))
list_of_document_ids = get_document_ids_from_dml_results(cursor)
return list_of_document_ids
def update_and_insert_documents(transaction_executor):
"""
Handle the insertion of documents and updating PersonIds all in a single transaction.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
"""
list_ids = insert_documents(transaction_executor, Constants.PERSON_TABLE_NAME, SampleData.PERSON)
logger.info("Updating PersonIds for 'DriversLicense' and PrimaryOwner for 'VehicleRegistration'...")
new_licenses, new_registrations = update_person_id(list_ids)
insert_documents(transaction_executor, Constants.VEHICLE_TABLE_NAME, SampleData.VEHICLE)
insert_documents(transaction_executor, Constants.VEHICLE_REGISTRATION_TABLE_NAME, new_registrations)
insert_documents(transaction_executor, Constants.DRIVERS_LICENSE_TABLE_NAME, new_licenses)
if __name__ == '__main__':
"""
Insert documents into a table in a QLDB ledger.
"""
try:
with create_qldb_session() as session:
# An INSERT statement creates the initial revision of a document with a version number of zero.
# QLDB also assigns a unique document identifier in GUID format as part of the metadata.
session.execute_lambda(lambda executor: update_and_insert_documents(executor),
lambda retry_attempt: logger.info('Retrying due to OCC conflict...'))
logger.info('Documents inserted successfully!')
except Exception:
logger.exception('Error inserting or updating documents.')
```
------
**注意**
此程式示範如何使用參數化值呼叫 `execute_statement`函數。除了要執行的 PartiQL 陳述式之外，您還可以傳遞資料參數。在陳述式字串中使用問號 (`?`) 做為變數預留位置。
如果`INSERT`陳述式成功，則會傳回每個插入文件`id`的 。
1. 若要執行程式，請輸入下列命令。
```
python insert_document.py
```
接下來，您可以使用`SELECT`陳述式從`vehicle-registration`分類帳中的資料表讀取資料。繼續執行「[步驟 4：查詢分類帳中的資料表](getting-started.python.step-4.md)」。
# 步驟 4：查詢分類帳中的資料表
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在 Amazon QLDB 分類帳中建立資料表並使用資料載入資料表之後，您可以執行查詢來檢閱您剛插入的車輛註冊資料。QLDB 使用 [PartiQL](ql-reference.md) 做為其查詢語言，而 [Amazon Ion](ion.md) 做為其文件導向資料模型。
PartiQL 是一種開放原始碼、與 SQL 相容的查詢語言，已擴充以使用 Ion。使用 PartiQL，您可以使用熟悉的 SQL 運算子插入、查詢和管理資料。Amazon Ion 是 JSON 的超集合。Ion 是一種開放原始碼、以文件為基礎的資料格式，可讓您靈活地儲存和處理結構化、半結構化和巢狀資料。
在此步驟中，您會使用`SELECT`陳述式從`vehicle-registration`分類帳中的資料表讀取資料。
**警告**
當您在沒有索引查詢的情況下在 QLDB 中執行查詢時，它會叫用完整資料表掃描。PartiQL 支援此類查詢，因為它與 SQL 相容。不過，*請勿*在 QLDB 中執行生產使用案例的資料表掃描。資料表掃描可能會導致大型資料表的效能問題，包括並行衝突和交易逾時。
若要避免資料表掃描，您必須在索引欄位或文件 ID 上使用*等式*運算子，以`WHERE`述詞子句執行陳述式；例如， `WHERE indexedField = 123`或 `WHERE indexedField IN (456, 789)`。如需詳細資訊，請參閱[最佳化查詢效能](working.optimize.md)。
**查詢資料表**
1. 使用下列程式 (`find_vehicles.py`) 來查詢您分類帳中人員下註冊的所有車輛。
------
#### [ 3.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.model.sample_data import get_document_ids, print_result, SampleData
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_driver
logger = getLogger(__name__)
basicConfig(level=INFO)
def find_vehicles_for_owner(driver, gov_id):
"""
Find vehicles registered under a driver using their government ID.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type gov_id: str
:param gov_id: The owner's government ID.
"""
document_ids = driver.execute_lambda(lambda executor: get_document_ids(executor, Constants.PERSON_TABLE_NAME,
'GovId', gov_id))
query = "SELECT Vehicle FROM Vehicle INNER JOIN VehicleRegistration AS r " \
"ON Vehicle.VIN = r.VIN WHERE r.Owners.PrimaryOwner.PersonId = ?"
for ids in document_ids:
cursor = driver.execute_lambda(lambda executor: executor.execute_statement(query, ids))
logger.info('List of Vehicles for owner with GovId: {}...'.format(gov_id))
print_result(cursor)
def main(ledger_name=Constants.LEDGER_NAME):
"""
Find all vehicles registered under a person.
"""
try:
with create_qldb_driver(ledger_name) as driver:
# Find all vehicles registered under a person.
gov_id = SampleData.PERSON[0]['GovId']
find_vehicles_for_owner(driver, gov_id)
except Exception as e:
logger.exception('Error getting vehicles for owner.')
raise e
if __name__ == '__main__':
main()
```
------
#### [ 2.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.model.sample_data import get_document_ids, print_result, SampleData
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_session
logger = getLogger(__name__)
basicConfig(level=INFO)
def find_vehicles_for_owner(transaction_executor, gov_id):
"""
Find vehicles registered under a driver using their government ID.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type gov_id: str
:param gov_id: The owner's government ID.
"""
document_ids = get_document_ids(transaction_executor, Constants.PERSON_TABLE_NAME, 'GovId', gov_id)
query = "SELECT Vehicle FROM Vehicle INNER JOIN VehicleRegistration AS r " \
"ON Vehicle.VIN = r.VIN WHERE r.Owners.PrimaryOwner.PersonId = ?"
for ids in document_ids:
cursor = transaction_executor.execute_statement(query, ids)
logger.info('List of Vehicles for owner with GovId: {}...'.format(gov_id))
print_result(cursor)
if __name__ == '__main__':
"""
Find all vehicles registered under a person.
"""
try:
with create_qldb_session() as session:
# Find all vehicles registered under a person.
gov_id = SampleData.PERSON[0]['GovId']
session.execute_lambda(lambda executor: find_vehicles_for_owner(executor, gov_id),
lambda retry_attempt: logger.info('Retrying due to OCC conflict...'))
except Exception:
logger.exception('Error getting vehicles for owner.')
```
------
**注意**
首先，此程式會使用 查詢文件的`Person`資料表`GovId LEWISR261LL`，以取得其`id`中繼資料欄位。
然後，它會使用本文件`id`做為外部索引鍵，透過 查詢`VehicleRegistration`資料表`PrimaryOwner.PersonId`。它也會`VehicleRegistration`與 `VIN` 欄位上的 `Vehicle` 資料表聯結。
1. 若要執行程式，請輸入下列命令。
```
python find_vehicles.py
```
若要了解如何修改`vehicle-registration`分類帳中資料表中的文件，請參閱 [步驟 5：修改分類帳中的文件](getting-started.python.step-5.md)。
# 步驟 5：修改分類帳中的文件
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
既然您擁有要使用的資料，您就可以開始變更 Amazon QLDB `vehicle-registration` 中分類帳中的文件。在此步驟中，下列程式碼範例示範如何執行資料處理語言 (DML) 陳述式。這些陳述式會更新一輛車的主要擁有者，並將次要擁有者新增至另一輛車。
**修改文件**
1. 使用下列程式 (`transfer_vehicle_ownership.py`) 來更新您分類帳`1N4AL11D75C109151`中具有 VIN 的車輛主要擁有者。
------
#### [ 3.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.add_secondary_owner import get_document_ids, print_result, SampleData
from pyqldbsamples.constants import Constants
from pyqldbsamples.model.sample_data import convert_object_to_ion
from pyqldbsamples.connect_to_ledger import create_qldb_driver
logger = getLogger(__name__)
basicConfig(level=INFO)
def find_person_from_document_id(transaction_executor, document_id):
"""
Query a driver's information using the given ID.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type document_id: :py:class:`amazon.ion.simple_types.IonPyText`
:param document_id: The document ID required to query for the person.
:rtype: :py:class:`amazon.ion.simple_types.IonPyDict`
:return: The resulting document from the query.
"""
query = 'SELECT p.* FROM Person AS p BY pid WHERE pid = ?'
cursor = transaction_executor.execute_statement(query, document_id)
return next(cursor)
def find_primary_owner_for_vehicle(driver, vin):
"""
Find the primary owner of a vehicle given its VIN.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type vin: str
:param vin: The VIN to find primary owner for.
:rtype: :py:class:`amazon.ion.simple_types.IonPyDict`
:return: The resulting document from the query.
"""
logger.info('Finding primary owner for vehicle with VIN: {}.'.format(vin))
query = "SELECT Owners.PrimaryOwner.PersonId FROM VehicleRegistration AS v WHERE v.VIN = ?"
cursor = driver.execute_lambda(lambda executor: executor.execute_statement(query, convert_object_to_ion(vin)))
try:
return driver.execute_lambda(lambda executor: find_person_from_document_id(executor,
next(cursor).get('PersonId')))
except StopIteration:
logger.error('No primary owner registered for this vehicle.')
return None
def update_vehicle_registration(driver, vin, document_id):
"""
Update the primary owner for a vehicle using the given VIN.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type vin: str
:param vin: The VIN for the vehicle to operate on.
:type document_id: :py:class:`amazon.ion.simple_types.IonPyText`
:param document_id: New PersonId for the primary owner.
:raises RuntimeError: If no vehicle registration was found using the given document ID and VIN.
"""
logger.info('Updating the primary owner for vehicle with Vin: {}...'.format(vin))
statement = "UPDATE VehicleRegistration AS r SET r.Owners.PrimaryOwner.PersonId = ? WHERE r.VIN = ?"
cursor = driver.execute_lambda(lambda executor: executor.execute_statement(statement, document_id,
convert_object_to_ion(vin)))
try:
print_result(cursor)
logger.info('Successfully transferred vehicle with VIN: {} to new owner.'.format(vin))
except StopIteration:
raise RuntimeError('Unable to transfer vehicle, could not find registration.')
def validate_and_update_registration(driver, vin, current_owner, new_owner):
"""
Validate the current owner of the given vehicle and transfer its ownership to a new owner.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type vin: str
:param vin: The VIN of the vehicle to transfer ownership of.
:type current_owner: str
:param current_owner: The GovId of the current owner of the vehicle.
:type new_owner: str
:param new_owner: The GovId of the new owner of the vehicle.
:raises RuntimeError: If unable to verify primary owner.
"""
primary_owner = find_primary_owner_for_vehicle(driver, vin)
if primary_owner is None or primary_owner['GovId'] != current_owner:
raise RuntimeError('Incorrect primary owner identified for vehicle, unable to transfer.')
document_ids = driver.execute_lambda(lambda executor: get_document_ids(executor, Constants.PERSON_TABLE_NAME,
'GovId', new_owner))
update_vehicle_registration(driver, vin, document_ids[0])
def main(ledger_name=Constants.LEDGER_NAME):
"""
Find primary owner for a particular vehicle's VIN.
Transfer to another primary owner for a particular vehicle's VIN.
"""
vehicle_vin = SampleData.VEHICLE[0]['VIN']
previous_owner = SampleData.PERSON[0]['GovId']
new_owner = SampleData.PERSON[1]['GovId']
try:
with create_qldb_driver(ledger_name) as driver:
validate_and_update_registration(driver, vehicle_vin, previous_owner, new_owner)
except Exception as e:
logger.exception('Error updating VehicleRegistration.')
raise e
if __name__ == '__main__':
main()
```
------
#### [ 2.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.add_secondary_owner import get_document_ids, print_result, SampleData
from pyqldbsamples.constants import Constants
from pyqldbsamples.model.sample_data import convert_object_to_ion
from pyqldbsamples.connect_to_ledger import create_qldb_session
logger = getLogger(__name__)
basicConfig(level=INFO)
def find_person_from_document_id(transaction_executor, document_id):
"""
Query a driver's information using the given ID.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type document_id: :py:class:`amazon.ion.simple_types.IonPyText`
:param document_id: The document ID required to query for the person.
:rtype: :py:class:`amazon.ion.simple_types.IonPyDict`
:return: The resulting document from the query.
"""
query = 'SELECT p.* FROM Person AS p BY pid WHERE pid = ?'
cursor = transaction_executor.execute_statement(query, document_id)
return next(cursor)
def find_primary_owner_for_vehicle(transaction_executor, vin):
"""
Find the primary owner of a vehicle given its VIN.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type vin: str
:param vin: The VIN to find primary owner for.
:rtype: :py:class:`amazon.ion.simple_types.IonPyDict`
:return: The resulting document from the query.
"""
logger.info('Finding primary owner for vehicle with VIN: {}.'.format(vin))
query = "SELECT Owners.PrimaryOwner.PersonId FROM VehicleRegistration AS v WHERE v.VIN = ?"
cursor = transaction_executor.execute_statement(query, convert_object_to_ion(vin))
try:
return find_person_from_document_id(transaction_executor, next(cursor).get('PersonId'))
except StopIteration:
logger.error('No primary owner registered for this vehicle.')
return None
def update_vehicle_registration(transaction_executor, vin, document_id):
"""
Update the primary owner for a vehicle using the given VIN.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type vin: str
:param vin: The VIN for the vehicle to operate on.
:type document_id: :py:class:`amazon.ion.simple_types.IonPyText`
:param document_id: New PersonId for the primary owner.
:raises RuntimeError: If no vehicle registration was found using the given document ID and VIN.
"""
logger.info('Updating the primary owner for vehicle with Vin: {}...'.format(vin))
statement = "UPDATE VehicleRegistration AS r SET r.Owners.PrimaryOwner.PersonId = ? WHERE r.VIN = ?"
cursor = transaction_executor.execute_statement(statement, document_id, convert_object_to_ion(vin))
try:
print_result(cursor)
logger.info('Successfully transferred vehicle with VIN: {} to new owner.'.format(vin))
except StopIteration:
raise RuntimeError('Unable to transfer vehicle, could not find registration.')
def validate_and_update_registration(transaction_executor, vin, current_owner, new_owner):
"""
Validate the current owner of the given vehicle and transfer its ownership to a new owner in a single transaction.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type vin: str
:param vin: The VIN of the vehicle to transfer ownership of.
:type current_owner: str
:param current_owner: The GovId of the current owner of the vehicle.
:type new_owner: str
:param new_owner: The GovId of the new owner of the vehicle.
:raises RuntimeError: If unable to verify primary owner.
"""
primary_owner = find_primary_owner_for_vehicle(transaction_executor, vin)
if primary_owner is None or primary_owner['GovId'] != current_owner:
raise RuntimeError('Incorrect primary owner identified for vehicle, unable to transfer.')
document_id = next(get_document_ids(transaction_executor, Constants.PERSON_TABLE_NAME, 'GovId', new_owner))
update_vehicle_registration(transaction_executor, vin, document_id)
if __name__ == '__main__':
"""
Find primary owner for a particular vehicle's VIN.
Transfer to another primary owner for a particular vehicle's VIN.
"""
vehicle_vin = SampleData.VEHICLE[0]['VIN']
previous_owner = SampleData.PERSON[0]['GovId']
new_owner = SampleData.PERSON[1]['GovId']
try:
with create_qldb_session() as session:
session.execute_lambda(lambda executor: validate_and_update_registration(executor, vehicle_vin,
previous_owner, new_owner),
retry_indicator=lambda retry_attempt: logger.info('Retrying due to OCC conflict...'))
except Exception:
logger.exception('Error updating VehicleRegistration.')
```
------
1. 若要執行程式，請輸入下列命令。
```
python transfer_vehicle_ownership.py
```
1. 使用下列程式 (`add_secondary_owner.py`) 將次要擁有者新增至您分類帳`KM8SRDHF6EU074761`中具有 VIN 的車輛。
------
#### [ 3.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.model.sample_data import to_ion_struct, get_document_ids, print_result, SampleData, \
convert_object_to_ion
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_driver
logger = getLogger(__name__)
basicConfig(level=INFO)
def get_document_id_by_gov_id(driver, government_id):
"""
Find a driver's person ID using the given government ID.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type government_id: str
:param government_id: A driver's government ID.
:rtype: list
:return: A list of document IDs.
"""
logger.info("Finding secondary owner's person ID using given government ID: {}.".format(government_id))
return driver.execute_lambda(lambda executor: get_document_ids(executor, Constants.PERSON_TABLE_NAME, 'GovId',
government_id))
def is_secondary_owner_for_vehicle(driver, vin, secondary_owner_id):
"""
Check whether a secondary owner has already been registered for the given VIN.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type vin: str
:param vin: VIN of the vehicle to query.
:type secondary_owner_id: str
:param secondary_owner_id: The secondary owner's person ID.
:rtype: bool
:return: If the driver has already been registered.
"""
logger.info('Finding secondary owners for vehicle with VIN: {}...'.format(vin))
query = 'SELECT Owners.SecondaryOwners FROM VehicleRegistration AS v WHERE v.VIN = ?'
rows = driver.execute_lambda(lambda executor: executor.execute_statement(query, convert_object_to_ion(vin)))
for row in rows:
secondary_owners = row.get('SecondaryOwners')
person_ids = map(lambda owner: owner.get('PersonId').text, secondary_owners)
if secondary_owner_id in person_ids:
return True
return False
def add_secondary_owner_for_vin(driver, vin, parameter):
"""
Add a secondary owner into `VehicleRegistration` table for a particular VIN.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type vin: str
:param vin: VIN of the vehicle to add a secondary owner for.
:type parameter: :py:class:`amazon.ion.simple_types.IonPyValue`
:param parameter: The Ion value or Python native type that is convertible to Ion for filling in parameters of the
statement.
"""
logger.info('Inserting secondary owner for vehicle with VIN: {}...'.format(vin))
statement = "FROM VehicleRegistration AS v WHERE v.VIN = ? INSERT INTO v.Owners.SecondaryOwners VALUE ?"
cursor = driver.execute_lambda(lambda executor: executor.execute_statement(statement, convert_object_to_ion(vin),
parameter))
logger.info('VehicleRegistration Document IDs which had secondary owners added: ')
print_result(cursor)
def register_secondary_owner(driver, vin, gov_id):
"""
Register a secondary owner for a vehicle if they are not already registered.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type vin: str
:param vin: VIN of the vehicle to register a secondary owner for.
:type gov_id: str
:param gov_id: The government ID of the owner.
"""
logger.info('Finding the secondary owners for vehicle with VIN: {}.'.format(vin))
document_ids = get_document_id_by_gov_id(driver, gov_id)
for document_id in document_ids:
if is_secondary_owner_for_vehicle(driver, vin, document_id):
logger.info('Person with ID {} has already been added as a secondary owner of this vehicle.'.format(gov_id))
else:
add_secondary_owner_for_vin(driver, vin, to_ion_struct('PersonId', document_id))
def main(ledger_name=Constants.LEDGER_NAME):
"""
Finds and adds secondary owners for a vehicle.
"""
vin = SampleData.VEHICLE[1]['VIN']
gov_id = SampleData.PERSON[0]['GovId']
try:
with create_qldb_driver(ledger_name) as driver:
register_secondary_owner(driver, vin, gov_id)
logger.info('Secondary owners successfully updated.')
except Exception as e:
logger.exception('Error adding secondary owner.')
raise e
if __name__ == '__main__':
main()
```
------
#### [ 2.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.model.sample_data import to_ion_struct, get_document_ids, print_result, SampleData, \
convert_object_to_ion
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_session
logger = getLogger(__name__)
basicConfig(level=INFO)
def get_document_id_by_gov_id(transaction_executor, government_id):
"""
Find a driver's person ID using the given government ID.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type government_id: str
:param government_id: A driver's government ID.
:rtype: list
:return: A list of document IDs.
"""
logger.info("Finding secondary owner's person ID using given government ID: {}.".format(government_id))
return get_document_ids(transaction_executor, Constants.PERSON_TABLE_NAME, 'GovId', government_id)
def is_secondary_owner_for_vehicle(transaction_executor, vin, secondary_owner_id):
"""
Check whether a secondary owner has already been registered for the given VIN.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type vin: str
:param vin: VIN of the vehicle to query.
:type secondary_owner_id: str
:param secondary_owner_id: The secondary owner's person ID.
:rtype: bool
:return: If the driver has already been registered.
"""
logger.info('Finding secondary owners for vehicle with VIN: {}...'.format(vin))
query = 'SELECT Owners.SecondaryOwners FROM VehicleRegistration AS v WHERE v.VIN = ?'
rows = transaction_executor.execute_statement(query, convert_object_to_ion(vin))
for row in rows:
secondary_owners = row.get('SecondaryOwners')
person_ids = map(lambda owner: owner.get('PersonId').text, secondary_owners)
if secondary_owner_id in person_ids:
return True
return False
def add_secondary_owner_for_vin(transaction_executor, vin, parameter):
"""
Add a secondary owner into `VehicleRegistration` table for a particular VIN.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type vin: str
:param vin: VIN of the vehicle to add a secondary owner for.
:type parameter: :py:class:`amazon.ion.simple_types.IonPyValue`
:param parameter: The Ion value or Python native type that is convertible to Ion for filling in parameters of the
statement.
"""
logger.info('Inserting secondary owner for vehicle with VIN: {}...'.format(vin))
statement = "FROM VehicleRegistration AS v WHERE v.VIN = '{}' INSERT INTO v.Owners.SecondaryOwners VALUE ?"\
.format(vin)
cursor = transaction_executor.execute_statement(statement, parameter)
logger.info('VehicleRegistration Document IDs which had secondary owners added: ')
print_result(cursor)
def register_secondary_owner(transaction_executor, vin, gov_id):
"""
Register a secondary owner for a vehicle if they are not already registered.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type vin: str
:param vin: VIN of the vehicle to register a secondary owner for.
:type gov_id: str
:param gov_id: The government ID of the owner.
"""
logger.info('Finding the secondary owners for vehicle with VIN: {}.'.format(vin))
document_ids = get_document_id_by_gov_id(transaction_executor, gov_id)
for document_id in document_ids:
if is_secondary_owner_for_vehicle(transaction_executor, vin, document_id):
logger.info('Person with ID {} has already been added as a secondary owner of this vehicle.'.format(gov_id))
else:
add_secondary_owner_for_vin(transaction_executor, vin, to_ion_struct('PersonId', document_id))
if __name__ == '__main__':
"""
Finds and adds secondary owners for a vehicle.
"""
vin = SampleData.VEHICLE[1]['VIN']
gov_id = SampleData.PERSON[0]['GovId']
try:
with create_qldb_session() as session:
session.execute_lambda(lambda executor: register_secondary_owner(executor, vin, gov_id),
lambda retry_attempt: logger.info('Retrying due to OCC conflict...'))
logger.info('Secondary owners successfully updated.')
except Exception:
logger.exception('Error adding secondary owner.')
```
------
1. 若要執行程式，請輸入下列命令。
```
python add_secondary_owner.py
```
若要檢閱`vehicle-registration`分類帳中的這些變更，請參閱 [步驟 6：檢視文件的修訂歷史記錄](getting-started.python.step-6.md)。
# 步驟 6：檢視文件的修訂歷史記錄
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在上一個步驟中修改車輛的註冊資料後，您可以查詢其所有已註冊擁有者的歷史記錄，以及任何其他更新的欄位。在此步驟中，您會查詢 `vehicle-registration` 分類帳中`VehicleRegistration`資料表中文件的修訂歷史記錄。
**檢視修訂歷史記錄**
1. 使用下列程式 (`query_history.py`) 查詢具有 VIN `VehicleRegistration`的文件修訂歷史記錄`1N4AL11D75C109151`。
------
#### [ 3.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from datetime import datetime, timedelta
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.model.sample_data import print_result, get_document_ids, SampleData
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_driver
logger = getLogger(__name__)
basicConfig(level=INFO)
def format_date_time(date_time):
"""
Format the given date time to a string.
:type date_time: :py:class:`datetime.datetime`
:param date_time: The date time to format.
:rtype: str
:return: The formatted date time.
"""
return date_time.strftime('`%Y-%m-%dT%H:%M:%S.%fZ`')
def previous_primary_owners(driver, vin):
"""
Find previous primary owners for the given VIN in a single transaction.
In this example, query the `VehicleRegistration` history table to find all previous primary owners for a VIN.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type vin: str
:param vin: VIN to find previous primary owners for.
"""
person_ids = driver.execute_lambda(lambda executor: get_document_ids(executor,
Constants.VEHICLE_REGISTRATION_TABLE_NAME,
'VIN', vin))
todays_date = datetime.utcnow() - timedelta(seconds=1)
three_months_ago = todays_date - timedelta(days=90)
query = 'SELECT data.Owners.PrimaryOwner, metadata.version FROM history({}, {}, {}) AS h WHERE h.metadata.id = ?'.\
format(Constants.VEHICLE_REGISTRATION_TABLE_NAME, format_date_time(three_months_ago),
format_date_time(todays_date))
for ids in person_ids:
logger.info("Querying the 'VehicleRegistration' table's history using VIN: {}.".format(vin))
cursor = driver.execute_lambda(lambda executor: executor.execute_statement(query, ids))
if not (print_result(cursor)) > 0:
logger.info('No modification history found within the given time frame for document ID: {}'.format(ids))
def main(ledger_name=Constants.LEDGER_NAME):
"""
Query a table's history for a particular set of documents.
"""
try:
with create_qldb_driver(ledger_name) as driver:
vin = SampleData.VEHICLE_REGISTRATION[0]['VIN']
previous_primary_owners(driver, vin)
logger.info('Successfully queried history.')
except Exception as e:
logger.exception('Unable to query history to find previous owners.')
raise e
if __name__ == '__main__':
main()
```
------
#### [ 2.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from datetime import datetime, timedelta
from logging import basicConfig, getLogger, INFO
from pyqldbsamples.model.sample_data import print_result, get_document_ids, SampleData
from pyqldbsamples.constants import Constants
from pyqldbsamples.connect_to_ledger import create_qldb_session
logger = getLogger(__name__)
basicConfig(level=INFO)
def format_date_time(date_time):
"""
Format the given date time to a string.
:type date_time: :py:class:`datetime.datetime`
:param date_time: The date time to format.
:rtype: str
:return: The formatted date time.
"""
return date_time.strftime('`%Y-%m-%dT%H:%M:%S.%fZ`')
def previous_primary_owners(transaction_executor, vin):
"""
Find previous primary owners for the given VIN in a single transaction.
In this example, query the `VehicleRegistration` history table to find all previous primary owners for a VIN.
:type transaction_executor: :py:class:`pyqldb.execution.executor.Executor`
:param transaction_executor: An Executor object allowing for execution of statements within a transaction.
:type vin: str
:param vin: VIN to find previous primary owners for.
"""
person_ids = get_document_ids(transaction_executor, Constants.VEHICLE_REGISTRATION_TABLE_NAME, 'VIN', vin)
todays_date = datetime.utcnow() - timedelta(seconds=1)
three_months_ago = todays_date - timedelta(days=90)
query = 'SELECT data.Owners.PrimaryOwner, metadata.version FROM history({}, {}, {}) AS h WHERE h.metadata.id = ?'.\
format(Constants.VEHICLE_REGISTRATION_TABLE_NAME, format_date_time(three_months_ago),
format_date_time(todays_date))
for ids in person_ids:
logger.info("Querying the 'VehicleRegistration' table's history using VIN: {}.".format(vin))
cursor = transaction_executor.execute_statement(query, ids)
if not (print_result(cursor)) > 0:
logger.info('No modification history found within the given time frame for document ID: {}'.format(ids))
if __name__ == '__main__':
"""
Query a table's history for a particular set of documents.
"""
try:
with create_qldb_session() as session:
vin = SampleData.VEHICLE_REGISTRATION[0]['VIN']
session.execute_lambda(lambda lambda_executor: previous_primary_owners(lambda_executor, vin),
lambda retry_attempt: logger.info('Retrying due to OCC conflict...'))
logger.info('Successfully queried history.')
except Exception:
logger.exception('Unable to query history to find previous owners.')
```
------
**注意**
您可以在下列語法[歷史記錄函數](working.history.md#working.history.function)中查詢內建 來檢視文件的修訂歷史記錄。
```
SELECT * FROM history( table_name [, `start-time` [, `end-time` ] ] ) AS h
[ WHERE h.metadata.id = 'id' ]
```
*開始時間*和*結束時間*皆為選用。它們是 Amazon Ion 常值，可以用反引號表示 (``...``)。如需進一步了解，請參閱 [在 Amazon QLDB 中使用 PartiQL 查詢離子](ql-reference.query.md)。
最佳實務是，使用日期範圍 *（開始時間*和*結束時間*) 和文件 ID () 來限定歷史記錄查詢`metadata.id`。QLDB 會在交易中處理`SELECT`查詢，這些查詢受到[交易逾時限制](limits.md#limits.fixed)的限制。
QLDB 歷史記錄會依文件 ID 編製索引，此時您無法建立其他歷史記錄索引。包含開始時間和結束時間的歷史記錄查詢可受益於日期範圍資格。
1. 若要執行程式，請輸入下列命令。
```
python query_history.py
```
若要以密碼編譯方式驗證 `vehicle-registration` 分類帳中的文件修訂，請繼續 [步驟 7：驗證分類帳中的文件](getting-started.python.step-7.md)。
# 步驟 7：驗證分類帳中的文件
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
使用 Amazon QLDB，您可以搭配 SHA-256 使用密碼編譯雜湊，有效率地驗證分類帳日誌中文件的完整性。若要進一步了解驗證和密碼編譯雜湊如何在 QLDB 中運作，請參閱 [Amazon QLDB 中的資料驗證](verification.md)。
在此步驟中，您要驗證 `vehicle-registration` 分類帳中`VehicleRegistration`資料表中的文件修訂。首先，您請求摘要，該摘要會傳回為輸出檔案，並做為您分類帳整個變更歷史記錄的簽章。然後，您請求與該摘要相關的修訂證明。如果所有驗證檢查都通過，則會使用此驗證，驗證修訂的完整性。
**驗證文件修訂**
1. 檢閱下列`.py`檔案，其代表驗證所需的 QLDB 物件，以及具有協助程式函數的公用程式模組，以將 QLDB 回應類型轉換為字串。
1. `block_address.py`
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
def block_address_to_dictionary(ion_dict):
"""
Convert a block address from IonPyDict into a dictionary.
Shape of the dictionary must be: {'IonText': "{strandId: <"strandId">, sequenceNo: }"}
:type ion_dict: :py:class:`amazon.ion.simple_types.IonPyDict`/str
:param ion_dict: The block address value to convert.
:rtype: dict
:return: The converted dict.
"""
block_address = {'IonText': {}}
if not isinstance(ion_dict, str):
py_dict = '{{strandId: "{}", sequenceNo:{}}}'.format(ion_dict['strandId'], ion_dict['sequenceNo'])
ion_dict = py_dict
block_address['IonText'] = ion_dict
return block_address
```
1. `verifier.py`
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from array import array
from base64 import b64encode
from functools import reduce
from hashlib import sha256
from random import randrange
from amazon.ion.simpleion import loads
HASH_LENGTH = 32
UPPER_BOUND = 8
def parse_proof(value_holder):
"""
Parse the Proof object returned by QLDB into an iterator.
The Proof object returned by QLDB is a dictionary like the following:
{'IonText': '[{{}},{{}}]'}
:type value_holder: dict
:param value_holder: A structure containing an Ion string value.
:rtype: :py:class:`amazon.ion.simple_types.IonPyList`
:return: A list of hash values.
"""
value_holder = value_holder.get('IonText')
proof_list = loads(value_holder)
return proof_list
def parse_block(value_holder):
"""
Parse the Block object returned by QLDB and retrieve block hash.
:type value_holder: dict
:param value_holder: A structure containing an Ion string value.
:rtype: :py:class:`amazon.ion.simple_types.IonPyBytes`
:return: The block hash.
"""
value_holder = value_holder.get('IonText')
block = loads(value_holder)
block_hash = block.get('blockHash')
return block_hash
def flip_random_bit(original):
"""
Flip a single random bit in the given hash value.
This method is used to demonstrate QLDB's verification features.
:type original: bytes
:param original: The hash value to alter.
:rtype: bytes
:return: The altered hash with a single random bit changed.
"""
assert len(original) != 0, 'Invalid bytes.'
altered_position = randrange(len(original))
bit_shift = randrange(UPPER_BOUND)
altered_hash = bytearray(original).copy()
altered_hash[altered_position] = altered_hash[altered_position] ^ (1 << bit_shift)
return bytes(altered_hash)
def compare_hash_values(hash1, hash2):
"""
Compare two hash values by converting them into byte arrays, assuming they are little endian.
:type hash1: bytes
:param hash1: The hash value to compare.
:type hash2: bytes
:param hash2: The hash value to compare.
:rtype: int
:return: Zero if the hash values are equal, otherwise return the difference of the first pair of non-matching bytes.
"""
assert len(hash1) == HASH_LENGTH
assert len(hash2) == HASH_LENGTH
hash_array1 = array('b', hash1)
hash_array2 = array('b', hash2)
for i in range(len(hash_array1) - 1, -1, -1):
difference = hash_array1[i] - hash_array2[i]
if difference != 0:
return difference
return 0
def join_hash_pairwise(hash1, hash2):
"""
Take two hash values, sort them, concatenate them, and generate a new hash value from the concatenated values.
:type hash1: bytes
:param hash1: Hash value to concatenate.
:type hash2: bytes
:param hash2: Hash value to concatenate.
:rtype: bytes
:return: The new hash value generated from concatenated hash values.
"""
if len(hash1) == 0:
return hash2
if len(hash2) == 0:
return hash1
concatenated = hash1 + hash2 if compare_hash_values(hash1, hash2) < 0 else hash2 + hash1
new_hash_lib = sha256()
new_hash_lib.update(concatenated)
new_digest = new_hash_lib.digest()
return new_digest
def calculate_root_hash_from_internal_hashes(internal_hashes, leaf_hash):
"""
Combine the internal hashes and the leaf hash until only one root hash remains.
:type internal_hashes: map
:param internal_hashes: An iterable over a list of hash values.
:type leaf_hash: bytes
:param leaf_hash: The revision hash to pair with the first hash in the Proof hashes list.
:rtype: bytes
:return: The root hash constructed by combining internal hashes.
"""
root_hash = reduce(join_hash_pairwise, internal_hashes, leaf_hash)
return root_hash
def build_candidate_digest(proof, leaf_hash):
"""
Build the candidate digest representing the entire ledger from the Proof hashes.
:type proof: dict
:param proof: The Proof object.
:type leaf_hash: bytes
:param leaf_hash: The revision hash to pair with the first hash in the Proof hashes list.
:rtype: bytes
:return: The calculated root hash.
"""
parsed_proof = parse_proof(proof)
root_hash = calculate_root_hash_from_internal_hashes(parsed_proof, leaf_hash)
return root_hash
def verify_document(document_hash, digest, proof):
"""
Verify document revision against the provided digest.
:type document_hash: bytes
:param document_hash: The SHA-256 value representing the document revision to be verified.
:type digest: bytes
:param digest: The SHA-256 hash value representing the ledger digest.
:type proof: dict
:param proof: The Proof object retrieved from :func:`pyqldbsamples.get_revision.get_revision`.
:rtype: bool
:return: If the document revision verify against the ledger digest.
"""
candidate_digest = build_candidate_digest(proof, document_hash)
return digest == candidate_digest
def to_base_64(input):
"""
Encode input in base64.
:type input: bytes
:param input: Input to be encoded.
:rtype: string
:return: Return input that has been encoded in base64.
"""
encoded_value = b64encode(input)
return str(encoded_value, 'UTF-8')
```
1. `qldb_string_utils.py`
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
from amazon.ion.simpleion import dumps, loads
def value_holder_to_string(value_holder):
"""
Returns the string representation of a given `value_holder`.
:type value_holder: dict
:param value_holder: The `value_holder` to convert to string.
:rtype: str
:return: The string representation of the supplied `value_holder`.
"""
ret_val = dumps(loads(value_holder), binary=False, indent=' ', omit_version_marker=True)
val = '{{ IonText: {}}}'.format(ret_val)
return val
def block_response_to_string(block_response):
"""
Returns the string representation of a given `block_response`.
:type block_response: dict
:param block_response: The `block_response` to convert to string.
:rtype: str
:return: The string representation of the supplied `block_response`.
"""
string = ''
if block_response.get('Block', {}).get('IonText') is not None:
string += 'Block: ' + value_holder_to_string(block_response['Block']['IonText']) + ', '
if block_response.get('Proof', {}).get('IonText') is not None:
string += 'Proof: ' + value_holder_to_string(block_response['Proof']['IonText'])
return '{' + string + '}'
def digest_response_to_string(digest_response):
"""
Returns the string representation of a given `digest_response`.
:type digest_response: dict
:param digest_response: The `digest_response` to convert to string.
:rtype: str
:return: The string representation of the supplied `digest_response`.
"""
string = ''
if digest_response.get('Digest') is not None:
string += 'Digest: ' + str(digest_response['Digest']) + ', '
if digest_response.get('DigestTipAddress', {}).get('IonText') is not None:
string += 'DigestTipAddress: ' + value_holder_to_string(digest_response['DigestTipAddress']['IonText'])
return '{' + string + '}'
```
1. 使用兩個`.py`程式 (`get_digest.py` 和 `get_revision.py`) 來執行下列步驟：
+ 從`vehicle-registration`分類帳請求新的摘要。
+ 從 `1N4AL11D75C109151` `VehicleRegistration` 資料表請求每個具有 VIN 文件修訂的證明。
+ 透過重新計算摘要，使用傳回的摘要和驗證來驗證修訂。
`get_digest.py` 程式包含下列程式碼。
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from boto3 import client
from pyqldbsamples.constants import Constants
from pyqldbsamples.qldb.qldb_string_utils import digest_response_to_string
logger = getLogger(__name__)
basicConfig(level=INFO)
qldb_client = client('qldb')
def get_digest_result(name):
"""
Get the digest of a ledger's journal.
:type name: str
:param name: Name of the ledger to operate on.
:rtype: dict
:return: The digest in a 256-bit hash value and a block address.
"""
logger.info("Let's get the current digest of the ledger named {}".format(name))
result = qldb_client.get_digest(Name=name)
logger.info('Success. LedgerDigest: {}.'.format(digest_response_to_string(result)))
return result
def main(ledger_name=Constants.LEDGER_NAME):
"""
This is an example for retrieving the digest of a particular ledger.
"""
try:
get_digest_result(ledger_name)
except Exception as e:
logger.exception('Unable to get a ledger digest!')
raise e
if __name__ == '__main__':
main()
```
**注意**
使用 `get_digest_result`函數來請求摘要，涵蓋您分類帳中日誌的目前*提示*。日誌的提示是指截至 QLDB 收到您的請求時的最新遞交區塊。
`get_revision.py` 程式包含下列程式碼。
------
#### [ 3.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from amazon.ion.simpleion import loads
from boto3 import client
from pyqldbsamples.constants import Constants
from pyqldbsamples.get_digest import get_digest_result
from pyqldbsamples.model.sample_data import SampleData, convert_object_to_ion
from pyqldbsamples.qldb.block_address import block_address_to_dictionary
from pyqldbsamples.verifier import verify_document, flip_random_bit, to_base_64
from pyqldbsamples.connect_to_ledger import create_qldb_driver
from pyqldbsamples.qldb.qldb_string_utils import value_holder_to_string
logger = getLogger(__name__)
basicConfig(level=INFO)
qldb_client = client('qldb')
def get_revision(ledger_name, document_id, block_address, digest_tip_address):
"""
Get the revision data object for a specified document ID and block address.
Also returns a proof of the specified revision for verification.
:type ledger_name: str
:param ledger_name: Name of the ledger containing the document to query.
:type document_id: str
:param document_id: Unique ID for the document to be verified, contained in the committed view of the document.
:type block_address: dict
:param block_address: The location of the block to request.
:type digest_tip_address: dict
:param digest_tip_address: The latest block location covered by the digest.
:rtype: dict
:return: The response of the request.
"""
result = qldb_client.get_revision(Name=ledger_name, BlockAddress=block_address, DocumentId=document_id,
DigestTipAddress=digest_tip_address)
return result
def lookup_registration_for_vin(driver, vin):
"""
Query revision history for a particular vehicle for verification.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type vin: str
:param vin: VIN to query the revision history of a specific registration with.
:rtype: :py:class:`pyqldb.cursor.buffered_cursor.BufferedCursor`
:return: Cursor on the result set of the statement query.
"""
logger.info("Querying the 'VehicleRegistration' table for VIN: {}...".format(vin))
query = 'SELECT * FROM _ql_committed_VehicleRegistration WHERE data.VIN = ?'
return driver.execute_lambda(lambda txn: txn.execute_statement(query, convert_object_to_ion(vin)))
def verify_registration(driver, ledger_name, vin):
"""
Verify each version of the registration for the given VIN.
:type driver: :py:class:`pyqldb.driver.qldb_driver.QldbDriver`
:param driver: An instance of the QldbDriver class.
:type ledger_name: str
:param ledger_name: The ledger to get digest from.
:type vin: str
:param vin: VIN to query the revision history of a specific registration with.
:raises AssertionError: When verification failed.
"""
logger.info("Let's verify the registration with VIN = {}, in ledger = {}.".format(vin, ledger_name))
digest = get_digest_result(ledger_name)
digest_bytes = digest.get('Digest')
digest_tip_address = digest.get('DigestTipAddress')
logger.info('Got a ledger digest: digest tip address = {}, digest = {}.'.format(
value_holder_to_string(digest_tip_address.get('IonText')), to_base_64(digest_bytes)))
logger.info('Querying the registration with VIN = {} to verify each version of the registration...'.format(vin))
cursor = lookup_registration_for_vin(driver, vin)
logger.info('Getting a proof for the document.')
for row in cursor:
block_address = row.get('blockAddress')
document_id = row.get('metadata').get('id')
result = get_revision(ledger_name, document_id, block_address_to_dictionary(block_address), digest_tip_address)
revision = result.get('Revision').get('IonText')
document_hash = loads(revision).get('hash')
proof = result.get('Proof')
logger.info('Got back a proof: {}.'.format(proof))
verified = verify_document(document_hash, digest_bytes, proof)
if not verified:
raise AssertionError('Document revision is not verified.')
else:
logger.info('Success! The document is verified.')
altered_document_hash = flip_random_bit(document_hash)
logger.info("Flipping one bit in the document's hash and assert that the document is NOT verified. "
"The altered document hash is: {}.".format(to_base_64(altered_document_hash)))
verified = verify_document(altered_document_hash, digest_bytes, proof)
if verified:
raise AssertionError('Expected altered document hash to not be verified against digest.')
else:
logger.info('Success! As expected flipping a bit in the document hash causes verification to fail.')
logger.info('Finished verifying the registration with VIN = {} in ledger = {}.'.format(vin, ledger_name))
def main(ledger_name=Constants.LEDGER_NAME):
"""
Verify the integrity of a document revision in a QLDB ledger.
"""
registration = SampleData.VEHICLE_REGISTRATION[0]
vin = registration['VIN']
try:
with create_qldb_driver(ledger_name) as driver:
verify_registration(driver, ledger_name, vin)
except Exception as e:
logger.exception('Unable to verify revision.')
raise e
if __name__ == '__main__':
main()
```
------
#### [ 2.x ]
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from amazon.ion.simpleion import loads
from boto3 import client
from pyqldbsamples.constants import Constants
from pyqldbsamples.get_digest import get_digest_result
from pyqldbsamples.model.sample_data import SampleData, convert_object_to_ion
from pyqldbsamples.qldb.block_address import block_address_to_dictionary
from pyqldbsamples.verifier import verify_document, flip_random_bit, to_base_64
from pyqldbsamples.connect_to_ledger import create_qldb_session
from pyqldbsamples.qldb.qldb_string_utils import value_holder_to_string
logger = getLogger(__name__)
basicConfig(level=INFO)
qldb_client = client('qldb')
def get_revision(ledger_name, document_id, block_address, digest_tip_address):
"""
Get the revision data object for a specified document ID and block address.
Also returns a proof of the specified revision for verification.
:type ledger_name: str
:param ledger_name: Name of the ledger containing the document to query.
:type document_id: str
:param document_id: Unique ID for the document to be verified, contained in the committed view of the document.
:type block_address: dict
:param block_address: The location of the block to request.
:type digest_tip_address: dict
:param digest_tip_address: The latest block location covered by the digest.
:rtype: dict
:return: The response of the request.
"""
result = qldb_client.get_revision(Name=ledger_name, BlockAddress=block_address, DocumentId=document_id,
DigestTipAddress=digest_tip_address)
return result
def lookup_registration_for_vin(qldb_session, vin):
"""
Query revision history for a particular vehicle for verification.
:type qldb_session: :py:class:`pyqldb.session.qldb_session.QldbSession`
:param qldb_session: An instance of the QldbSession class.
:type vin: str
:param vin: VIN to query the revision history of a specific registration with.
:rtype: :py:class:`pyqldb.cursor.buffered_cursor.BufferedCursor`
:return: Cursor on the result set of the statement query.
"""
logger.info("Querying the 'VehicleRegistration' table for VIN: {}...".format(vin))
query = 'SELECT * FROM _ql_committed_VehicleRegistration WHERE data.VIN = ?'
parameters = [convert_object_to_ion(vin)]
cursor = qldb_session.execute_statement(query, parameters)
return cursor
def verify_registration(qldb_session, ledger_name, vin):
"""
Verify each version of the registration for the given VIN.
:type qldb_session: :py:class:`pyqldb.session.qldb_session.QldbSession`
:param qldb_session: An instance of the QldbSession class.
:type ledger_name: str
:param ledger_name: The ledger to get digest from.
:type vin: str
:param vin: VIN to query the revision history of a specific registration with.
:raises AssertionError: When verification failed.
"""
logger.info("Let's verify the registration with VIN = {}, in ledger = {}.".format(vin, ledger_name))
digest = get_digest_result(ledger_name)
digest_bytes = digest.get('Digest')
digest_tip_address = digest.get('DigestTipAddress')
logger.info('Got a ledger digest: digest tip address = {}, digest = {}.'.format(
value_holder_to_string(digest_tip_address.get('IonText')), to_base_64(digest_bytes)))
logger.info('Querying the registration with VIN = {} to verify each version of the registration...'.format(vin))
cursor = lookup_registration_for_vin(qldb_session, vin)
logger.info('Getting a proof for the document.')
for row in cursor:
block_address = row.get('blockAddress')
document_id = row.get('metadata').get('id')
result = get_revision(ledger_name, document_id, block_address_to_dictionary(block_address), digest_tip_address)
revision = result.get('Revision').get('IonText')
document_hash = loads(revision).get('hash')
proof = result.get('Proof')
logger.info('Got back a proof: {}.'.format(proof))
verified = verify_document(document_hash, digest_bytes, proof)
if not verified:
raise AssertionError('Document revision is not verified.')
else:
logger.info('Success! The document is verified.')
altered_document_hash = flip_random_bit(document_hash)
logger.info("Flipping one bit in the document's hash and assert that the document is NOT verified. "
"The altered document hash is: {}.".format(to_base_64(altered_document_hash)))
verified = verify_document(altered_document_hash, digest_bytes, proof)
if verified:
raise AssertionError('Expected altered document hash to not be verified against digest.')
else:
logger.info('Success! As expected flipping a bit in the document hash causes verification to fail.')
logger.info('Finished verifying the registration with VIN = {} in ledger = {}.'.format(vin, ledger_name))
if __name__ == '__main__':
"""
Verify the integrity of a document revision in a QLDB ledger.
"""
registration = SampleData.VEHICLE_REGISTRATION[0]
vin = registration['VIN']
try:
with create_qldb_session() as session:
verify_registration(session, Constants.LEDGER_NAME, vin)
except Exception:
logger.exception('Unable to verify revision.')
```
------
**注意**
`get_revision` 函數傳回指定文件修訂的證明後，此程式會使用用戶端 API 來驗證該修訂。
1. 若要執行程式，請輸入下列命令。
```
python get_revision.py
```
如果您不再需要使用`vehicle-registration`分類帳，請繼續 [步驟 8 （選用）：清除資源](getting-started.python.step-8.md)。
# 步驟 8 （選用）：清除資源
**重要**
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
您可以繼續使用`vehicle-registration`分類帳。不過，如果您不再需要它，您應該將其刪除。
**刪除分類帳**
1. 使用下列程式 `vehicle-registration` (`delete_ledger.py`) 刪除您的分類帳及其所有內容。
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from time import sleep
from boto3 import client
from pyqldbsamples.constants import Constants
from pyqldbsamples.describe_ledger import describe_ledger
logger = getLogger(__name__)
basicConfig(level=INFO)
qldb_client = client('qldb')
LEDGER_DELETION_POLL_PERIOD_SEC = 20
def delete_ledger(ledger_name):
"""
Send a request to QLDB to delete the specified ledger.
:type ledger_name: str
:param ledger_name: Name for the ledger to be deleted.
:rtype: dict
:return: Result from the request.
"""
logger.info('Attempting to delete the ledger with name: {}...'.format(ledger_name))
result = qldb_client.delete_ledger(Name=ledger_name)
logger.info('Success.')
return result
def wait_for_deleted(ledger_name):
"""
Wait for the ledger to be deleted.
:type ledger_name: str
:param ledger_name: The ledger to check on.
"""
logger.info('Waiting for the ledger to be deleted...')
while True:
try:
describe_ledger(ledger_name)
logger.info('The ledger is still being deleted. Please wait...')
sleep(LEDGER_DELETION_POLL_PERIOD_SEC)
except qldb_client.exceptions.ResourceNotFoundException:
logger.info('Success. The ledger is deleted.')
break
def set_deletion_protection(ledger_name, deletion_protection):
"""
Update an existing ledger's deletion protection.
:type ledger_name: str
:param ledger_name: Name of the ledger to update.
:type deletion_protection: bool
:param deletion_protection: Enable or disable the deletion protection.
:rtype: dict
:return: Result from the request.
"""
logger.info("Let's set deletion protection to {} for the ledger with name {}.".format(deletion_protection,
ledger_name))
result = qldb_client.update_ledger(Name=ledger_name, DeletionProtection=deletion_protection)
logger.info('Success. Ledger updated: {}'.format(result))
def main(ledger_name=Constants.LEDGER_NAME):
"""
Delete a ledger.
"""
try:
set_deletion_protection(ledger_name, False)
delete_ledger(ledger_name)
wait_for_deleted(ledger_name)
except Exception as e:
logger.exception('Unable to delete the ledger.')
raise e
if __name__ == '__main__':
main()
```
**注意**
如果您的分類帳已啟用刪除保護，您必須先停用它，才能使用 QLDB API 刪除分類帳。
`delete_ledger.py` 檔案也依賴於下列程式 (`describe_ledger.py`)。
```
# Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this
# software and associated documentation files (the "Software"), to deal in the Software
# without restriction, including without limitation the rights to use, copy, modify,
# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# This code expects that you have AWS credentials setup per:
# https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html
from logging import basicConfig, getLogger, INFO
from boto3 import client
from pyqldbsamples.constants import Constants
logger = getLogger(__name__)
basicConfig(level=INFO)
qldb_client = client('qldb')
def describe_ledger(ledger_name):
"""
Describe a ledger.
:type ledger_name: str
:param ledger_name: Name of the ledger to describe.
"""
logger.info('describe ledger with name: {}.'.format(ledger_name))
result = qldb_client.describe_ledger(Name=ledger_name)
result.pop('ResponseMetadata')
logger.info('Success. Ledger description: {}.'.format(result))
return result
def main(ledger_name=Constants.LEDGER_NAME):
"""
Describe a QLDB ledger.
"""
try:
describe_ledger(ledger_name)
except Exception as e:
logger.exception('Unable to describe a ledger.')
raise e
if __name__ == '__main__':
main()
```
1. 若要執行程式，請輸入下列命令。
```
python delete_ledger.py
```