本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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 ```