As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Tutorial do Python do Amazon QLDB
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Nesta implementação do aplicativo de amostra do tutorial, você usa o driver Amazon QLDB com o para criar um livro contábil QLDB e preenchê-lo com AWS SDK para Python (Boto3) dados de amostra.
Ao trabalhar com este tutorial, é possível consultar o cliente de [baixo nível QLDB](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/qldb.html) na AWS Referência da API do *SDK for Python (Boto3)* para operações de API de gerenciamento. Para operações de dados transacionais, você pode consultar a Referência de API [QLDB Driver](https://amazon-qldb-driver-python.readthedocs.io/en/stable/) for Python.
**nota**
Quando aplicável, algumas etapas do tutorial têm comandos ou exemplos de código diferentes para cada versão principal compatível do driver QLDB para Python.
**Topics**
+ [Como instalar o aplicativo de amostra Python do Amazon QLDB](sample-app.python.md)
+ [Etapa 1: criar um novo ledger](getting-started.python.step-1.md)
+ [Etapa 2: Testar a conectividade com o ledger](getting-started.python.step-2.md)
+ [Etapa 3: criar tabelas, índices e dados de amostra](getting-started.python.step-3.md)
+ [Etapa 4: consultar as tabelas em um ledger](getting-started.python.step-4.md)
+ [Etapa 5: Modificar documentos em um ledger](getting-started.python.step-5.md)
+ [Etapa 6: Visualizar o histórico de revisão de um documento](getting-started.python.step-6.md)
+ [Etapa 7: verificar um documento em um ledger](getting-started.python.step-7.md)
+ [Etapa 8 (opcional): Limpar os recursos](getting-started.python.step-8.md)
# Como instalar o aplicativo de amostra Python do Amazon QLDB
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Esta seção descreve como instalar e executar o aplicativo de amostra Amazon QLDB fornecido para o tutorial do step-by-step Python. O caso de uso para este aplicativo de exemplo é um banco de dados para um aplicativo do departamento de veículos motorizados (DMV) que rastreia as informações históricas completas sobre registros de veículos.
[O aplicativo de amostra DMV para Python é de código aberto no repositório aws-samples/ -python. GitHub amazon-qldb-dmv-sample](https://github.com/aws-samples/amazon-qldb-dmv-sample-python)
## Pré-requisitos
Antes de começar, conclua o driver QLDB para Python [Pré-requisitos](getting-started.python.md#getting-started.python.prereqs). Isso inclui instalar o Python e fazer o seguinte:
1. Inscreva-se em AWS.
1. Crie um usuário com as permissões adequadas para QLDB.
1. Conceda acesso programático para desenvolvimento.
Para concluir todas as etapas neste tutorial, você precisa de acesso administrativo total aos recursos do seu ledger por meio do QLDB API.
## Instalação
**Para instalar o aplicativo de exemplo.**
1. Digite o `pip` comando a seguir para clonar e instalar o aplicativo de GitHub amostra.
------
#### [ 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
```
------
O aplicativo de amostra empacota o código-fonte completo deste tutorial e suas dependências, incluindo o driver Python e o [AWS SDK para Python (Boto3)](https://aws.amazon.com/sdk-for-python).
1. Antes de começar a executar o código na linha de comando, alterne seu diretório de trabalho atual para o local em que o `pyqldbsamples` pacote está instalado. Insira o comando da a seguir.
```
cd $(python -c "import pyqldbsamples; print(pyqldbsamples.__path__[0])")
```
1. Continue para [Etapa 1: criar um novo ledger](getting-started.python.step-1.md) para iniciar o tutorial e criar um ledger.
# Etapa 1: criar um novo ledger
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Nesta etapa, você cria um novo ledger do Amazon QLDB chamado `vehicle-registration`.
**Para criar um novo ledger**
1. Examine o arquivo a seguir (`constants.py`), que contém valores constantes usados por todos os outros programas deste tutorial.
```
# 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. Use o programa a seguir (`create_ledger.py`) para criar um ledger chamado `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()
```
**nota**
Na chamada `create_ledger`, você deve especificar um nome de ledger e um modo de permissões. Recomendamos o uso do modo de permissões `STANDARD` para maximizar a segurança dos dados do seu ledger.
Ao criar um ledger, a *proteção contra exclusão* é habilitada, por padrão. Esse é um atributo que impede que um ledger seja excluído por qualquer usuário. Você tem a opção de desativar a proteção contra exclusão na criação do livro contábil usando a API QLDB ou o (). AWS Command Line Interface AWS CLI
Se preferir, especifique também tags para anexar ao ledger.
1. Para executar o programa, digite o comando a seguir.
```
python create_ledger.py
```
Para verificar sua conexão com o novo ledger, vá para [Etapa 2: Testar a conectividade com o ledger](getting-started.python.step-2.md).
# Etapa 2: Testar a conectividade com o ledger
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Nesta etapa, você verifica se pode se conectar ao ledger `vehicle-registration` no Amazon QLDB usando o endpoint de API de dados transacionais.
**Para testar a conexão com o ledger**
1. Use o programa a seguir (`connect_to_ledger.py`) para criar uma conexão de sessão de dados com o ledger `vehicle-registration`.
------
#### [ 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()
```
**nota**
Para executar transações de dados em seu ledger, você deve criar um objeto de driver QLDB para se conectar a um ledger específico. Esse é um objeto cliente diferente do objeto `qldb_client` que você usou na etapa anterior para criar o ledger. Esse cliente anterior só é usado para executar as operações da API de gerenciamento listadas no [Referência da API do Amazon QLDB](api-reference.md).
Você deve especificar um nome de ledger ao criar esse objeto de driver.
------
#### [ 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.')
```
**nota**
Para executar transações de dados em seu ledger, você deve criar um objeto de driver QLDB para se conectar a um ledger específico. Esse é um objeto cliente diferente do objeto `qldb_client` que você usou na etapa anterior para criar o ledger. Esse cliente anterior só é usado para executar as operações da API de gerenciamento listadas no [Referência da API do Amazon QLDB](api-reference.md).
Primeiro, crie um objeto de driver QLDB em pool. Você deve especificar um nome de ledger ao criar esse objeto de driver.
Em seguida, você pode criar sessões a partir desse objeto de driver agrupado.
------
1. Para executar o programa, digite o comando a seguir.
```
python connect_to_ledger.py
```
Para criar tabelas no ledger `vehicle-registration`, vá para [Etapa 3: criar tabelas, índices e dados de amostra](getting-started.python.step-3.md).
# Etapa 3: criar tabelas, índices e dados de amostra
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Quando seu ledger do Amazon QLDB está ativo e aceita conexão, você pode começar a criar tabelas para dados sobre veículos, seus proprietários e suas informações de registro. Depois de criar as tabelas e os índices, você pode carregá-los com dados.
Nesta etapa, você cria quatro tabelas no ledger `vehicle-registration`:
+ `VehicleRegistration`
+ `Vehicle`
+ `Person`
+ `DriversLicense`
Você também cria os índices a seguir.
****
| Nome da tabela | Campo |
| --- | --- |
| VehicleRegistration | VIN |
| VehicleRegistration | LicensePlateNumber |
| Vehicle | VIN |
| Person | GovId |
| DriversLicense | LicenseNumber |
| DriversLicense | PersonId |
Ao inserir dados de amostra, primeiro você insere documentos na tabela `Person`. Em seguida, você usa o sistema atribuído `id` a partir de cada documento `Person` para preencher os campos correspondentes nos documentos `VehicleRegistration` e `DriversLicense` apropriados.
**dica**
Como prática recomendada, use o `id` de um documento atribuído pelo sistema como uma chave estrangeira. Embora você possa definir campos destinados a serem identificadores exclusivos (por exemplo, o VIN de um veículo), o verdadeiro identificador exclusivo de um documento é seu `id`. Esse campo está incluído nos metadados do documento, que você pode consultar na *visualização confirmada* (a visualização definida pelo sistema de uma tabela).
Para obter mais informações sobre visualizações no QLDB, consulte [Conceitos principais](ledger-structure.md). Para saber mais sobre metadados, consulte [Consultar metadados do documento](working.metadata.md).
**Para criar tabelas e índices**
1. Use o programa a seguir (`create_table.py`) para criar as tabelas mencionadas anteriormente.
------
#### [ 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.')
```
------
**nota**
Este programa demonstra como usar a função `execute_lambda`. Neste exemplo, você executa várias instruções PartiQL `CREATE TABLE` com uma única expressão lambda.
Essa função de execução inicia implicitamente uma transação, executa todas as instruções no lambda e, em seguida, confirma automaticamente a transação.
1. Para executar o programa, digite o comando a seguir.
```
python create_table.py
```
1. Use o programa a seguir (`create_index.py`) para criar índices nas tabelas, conforme descrito anteriormente.
------
#### [ 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. Para executar o programa, digite o comando a seguir.
```
python create_index.py
```
**Para carregar os dados de exemplo em tabelas**
1. Examine o arquivo (`sample_data.py`) a seguir, que representa os dados de amostra que você insere nas tabelas `vehicle-registration`. Esse arquivo também é importado do pacote `amazon.ion` para fornecer funções auxiliares que convertem, analisam e imprimem dados do [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))
```
**nota**
A `get_document_ids` função executa uma consulta que retorna um documento atribuído pelo sistema a IDs partir de uma tabela. Para saber mais, consulte [Usar a cláusula BY para consultar o ID do documento](working.metadata.by-clause.md).
1. Use o programa a seguir (`insert_document.py`) para inserir os dados de amostra em suas tabelas.
------
#### [ 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.')
```
------
**nota**
Este programa demonstra como chamar a função `execute_statement` com valores parametrizados. Você pode passar parâmetros de dados além da instrução partiQL que deseja executar. Use um ponto de interrogação (`?`) como um marcador variável em sua string de instrução.
Se uma instrução `INSERT` for bem-sucedida, ela retornará a `id` de cada documento inserido.
1. Para executar o programa, digite o comando a seguir.
```
python insert_document.py
```
Em seguida, você pode usar instruções `SELECT` para ler os dados das tabelas no ledger `vehicle-registration`. Vá para [Etapa 4: consultar as tabelas em um ledger](getting-started.python.step-4.md).
# Etapa 4: consultar as tabelas em um ledger
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Depois de criar tabelas em um ledger do Amazon QLDB e carregá-las com dados, você pode executar consultas para revisar os dados de registro do veículo que você acabou de inserir. O QLDB usa o [PartiQL](ql-reference.md) como sua linguagem de consulta e o [Amazon Ion](ion.md) como seu modelo de dados orientado a documentos.
O partiQL é uma linguagem de consulta de código aberto compatível com SQL que foi estendida para funcionar com o Ion. Com o partiQL, você pode inserir, consultar e gerenciar seus dados com operadores SQL conhecidos. O Amazon Ion é um superconjunto do JSON. O Ion é um formato de dados de código aberto baseado em documentos que oferece a flexibilidade de armazenar e processar dados estruturados, semiestruturados e aninhados.
Nesta etapa, você pode usar instruções `SELECT` para ler os dados das tabelas no ledger `vehicle-registration`.
**Atenção**
Quando você executa uma consulta no QLDB sem uma pesquisa indexada, ela invoca uma verificação completa da tabela. O partiQL suporta essas consultas porque é compatível com SQL. No entanto, *não* execute varreduras de tabela para casos de uso de produção no QLDB. Verificações de tabela podem causar problemas de performance em tabelas grandes, incluindo conflitos de simultaneidade e tempos limite de transação.
Para evitar verificações de tabelas, você deve executar instruções com uma cláusula de predicado `WHERE` usando um operador de *igualdade* em um campo indexado ou em um ID de documento, por exemplo, `WHERE indexedField = 123` ou `WHERE indexedField IN (456, 789)`. Para obter mais informações, consulte [Otimizar a performance da consulta](working.optimize.md).
**Para consultar as tabelas**
1. Use o seguinte programa (`find_vehicles.py`) para consultar todos os veículos registrados sob uma pessoa em seu ledger.
------
#### [ 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.')
```
------
**nota**
Primeiro, esse programa consulta a tabela `Person` para o documento `GovId LEWISR261LL` para obter seu campo de metadados `id`.
Em seguida, usa esse documento `id` como uma chave externa para consultar a tabela `VehicleRegistration`, `PrimaryOwner.PersonId`. Ele também junta `VehicleRegistration` à tabela `Vehicle` no campo `VIN`.
1. Para executar o programa, digite o comando a seguir.
```
python find_vehicles.py
```
Para saber mais sobre a modificação de documentos nas tabelas do ledger `vehicle-registration`, consulte [Etapa 5: Modificar documentos em um ledger](getting-started.python.step-5.md).
# Etapa 5: Modificar documentos em um ledger
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Agora que você tem dados com os quais trabalhar, pode começar a fazer alterações nos documentos no ledger `vehicle-registration` no Amazon QLDB. Nesta etapa, os exemplos de código a seguir demonstram como executar instruções de linguagem de manipulação de dados (DML). Essas declarações atualizam o proprietário principal de um veículo e adicionam um proprietário secundário a outro veículo.
**Para modificar documentos**
1. Use o programa a seguir (`transfer_vehicle_ownership.py`) para atualizar o proprietário principal do veículo com o VIN `1N4AL11D75C109151` em seu ledger.
------
#### [ 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. Para executar o programa, digite o comando a seguir.
```
python transfer_vehicle_ownership.py
```
1. Use o programa a seguir (`add_secondary_owner.py`) para adicionar o proprietário secundário do veículo com o VIN `KM8SRDHF6EU074761` em seu ledger.
------
#### [ 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. Para executar o programa, digite o comando a seguir.
```
python add_secondary_owner.py
```
Para revisar essas alterações no ledger `vehicle-registration`, consulte [Etapa 6: Visualizar o histórico de revisão de um documento](getting-started.python.step-6.md).
# Etapa 6: Visualizar o histórico de revisão de um documento
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Depois de modificar os dados de registro para um veículo na etapa anterior, você pode consultar o histórico de todos os proprietários registrados e quaisquer outros campos atualizados. Nesta etapa, você consulta o histórico de revisão de um documento na tabela `VehicleRegistration` do ledger `vehicle-registration`.
**Visualizar o histórico de revisão**
1. Use o programa a seguir (`query_history.py`) para consultar o histórico de revisão do `VehicleRegistration` documento com o VIN `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.')
```
------
**nota**
Você pode visualizar o histórico de revisões de um documento consultando a sintaxe [Função de histórico](working.history.md#working.history.function) incorporada a seguir.
```
SELECT * FROM history( table_name [, `start-time` [, `end-time` ] ] ) AS h
[ WHERE h.metadata.id = 'id' ]
```
A *hora de início* e a *hora de término* são opcionais. São valores literais do Amazon Ion que podem ser indicados com acentos graves (``...``). Para saber mais, consulte [Consultar o Ion com o PartiQL no Amazon QLDB](ql-reference.query.md).
Como prática recomendada, qualifique uma consulta de histórico com um intervalo de datas (*hora de início* e *hora de término*) e um ID de documentos (`metadata.id`). O QLDB processa consultas `SELECT` em transações, que estão sujeitas a um [limite de tempo de transação](limits.md#limits.fixed).
O histórico do QLDB é indexado por ID do documento, e você não pode criar índices de histórico adicionais no momento. As consultas de histórico que incluem uma hora de início e uma hora de término ganham o benefício da qualificação por intervalo de datas.
1. Para executar o programa, digite o comando a seguir.
```
python query_history.py
```
Para verificar uma revisão de documento criptograficamente no ledger `vehicle-registration`, vá para [Etapa 7: verificar um documento em um ledger](getting-started.python.step-7.md).
# Etapa 7: verificar um documento em um ledger
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Com o Amazon QLDB, você pode verificar com eficiência a integridade de um documento no diário do seu ledger usando hashing criptográfico com SHA-256. Para saber mais sobre como a verificação e o hashing criptográfico funcionam no QLDB, consulte [Verificação de dados no Amazon QLDB](verification.md).
Nesta etapa, você verifica uma revisão do documento na tabela `VehicleRegistration` do seu ledger `vehicle-registration`. Primeiro, você solicita um resumo, que é retornado como um arquivo de saída e atua como uma assinatura de todo o histórico de alterações do seu ledger. Em seguida, você solicita uma prova da revisão em relação a esse resumo. Usando essa prova, a integridade da sua revisão é verificada se todas as verificações de validação forem aprovadas.
**Para verificar a revisão de um documento**
1. Examine os arquivos `.py` a seguir, que representam objetos do QLDB necessários para verificação e um módulo utilitário com funções auxiliares para converter os tipos de resposta do QLDB em cadeias de caracteres.
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. Use dois programas `.py` (`get_digest.py` e `get_revision.py`) para realizar as seguintes etapas:
+ Solicite um novo resumo do ledger `vehicle-registration`.
+ Solicite uma prova para cada revisão do documento com VIN `1N4AL11D75C109151` da tabela `VehicleRegistration`.
+ Verifique as revisões usando o resumo e a prova retornados, recalculando o resumo.
O programa `get_digest.py` contém o código a seguir.
```
# 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()
```
**nota**
Use a função `get_digest_result` para solicitar um resumo que cubra a *ponta* atual do diário em seu ledger. A ponta do diário se refere ao último bloco confirmado no momento em que o QLDB recebe sua solicitação.
O programa `get_revision.py` contém o código a seguir.
------
#### [ 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.')
```
------
**nota**
Depois que a função `get_revision` retorna uma prova da revisão do documento especificada, esse programa usa uma API do lado do cliente para verificar essa revisão.
1. Para executar o programa, digite o comando a seguir.
```
python get_revision.py
```
Se você não precisar mais usar o ledger `vehicle-registration`, prossiga para [Etapa 8 (opcional): Limpar os recursos](getting-started.python.step-8.md).
# Etapa 8 (opcional): Limpar os recursos
**Importante**
Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Você pode continuar usando o ledger `vehicle-registration`. No entanto, se não precisar mais dele, deverá excluí-lo.
**Para excluir o ledger**
1. Use o programa (`delete_ledger.py`) a seguir para excluir seu ledger `vehicle-registration` e todo o seu conteúdo.
```
# 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()
```
**nota**
Se a proteção contra exclusão estiver habilitada para o seu ledger, você deverá desabilitá-la antes de excluir o ledger usando a API do QLDB.
O arquivo `delete_ledger.py` também depende do seguinte programa (`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. Para executar o programa, digite o comando a seguir.
```
python delete_ledger.py
```