Criando e preenchendo um banco de dados
Este tutorial mostra como usar a linguagem de programação Python para criar um banco de dados IBM® Cloudant® for IBM Cloud® em sua instância de serviço IBM Cloud. Você também aprende a preencher o banco de dados com uma coleção simples de dados.
Este tutorial não usa o código Python mais eficiente. A intenção é mostrar um código de trabalho simples e fácil de entender que pode ser aprendido e aplicado em seus próprios aplicativos. Você deve aplicar as práticas recomendadas normais para verificar e tratar todas as condições de aviso ou erro em seus próprios aplicativos.
Objetivos
Este tutorial fornece uma série de instruções de linguagem Python, adequadas para as seguintes tarefas:
- Conectando-se a uma instância de serviço do IBM Cloudant na IBM Cloud®.
- Criando um banco de dados na instância de serviço.
- Armazenando uma pequena coleção de dados como documentos no banco de dados.
- Recuperando dados.
- Excluindo o banco de dados.
Antes de Iniciar
Preparar uma instância de serviço IBM Cloudant
-
Configure os requisitos de credencial de serviço
a. Crie uma instância de serviço e credenciais seguindo o tutorial Introdução.
b. Obtenha suas credenciais seguindo o tutorial Localizar suas credenciais de serviço.
O tutorial usa o tipo de credenciais IAM para autenticação.
Instale o Python e prepare o ambiente
-
Instale a versão necessária do Python
Você deve ter uma versão atual da Python instalada em seu sistema.
a. Execute o seguinte comando em um prompt para verificar se o Python está instalado:
python3 --version
b. Verifique se você obtém um resultado semelhante ao exemplo a seguir:
Python 3.12.5
-
Criar e ativar um ambiente virtual
a. Crie o ambiente virtual:
python3 -m venv cloudantdemo
Isso cria um subdiretório chamado
cloudantdemo
no diretório de trabalho atual. Você pode escolher outro caminho.b. Ative o ambiente virtual:
source cloudantdemo/bin/activate
Para obter mais informações sobre ambientes virtuais Python e instruções para sistemas operacionais sistemas operacionais alternativos, consulte a Python documentação do venv.
-
Instale o IBM Cloudant SDK para Python
pip install ibmcloudant
-
Verifique a instalação do IBM Cloudant SDK para Python.
a. Verifique se a biblioteca do cliente foi instalada com sucesso executando o comando a seguir em um prompt:
pip show ibmcloudant
Você obtém um resultado com informações sobre o pacote
ibmcloudant
.b. Inspecione a saída, que deve começar com linhas semelhantes ao exemplo a seguir:
Name: ibmcloudant Version: 0.9.1
-
Inicie o interpretador interativo Python
a. Execute o comando
python
no ambiente virtual para iniciar o interpretadorpython
b. Verifique se você obtém uma saída semelhante ao exemplo a seguir:
Python 3.12.5 Type "help", "copyright", "credits" or "license" for more information. >>>
Normalmente, você não executa comandos individualmente em Python. Normalmente, você cria um script, que é uma lista dos comandos que você deseja executar, armazenados em um arquivo Python, com uma extensão
.py
.
Conectando a uma instância de serviço
-
Execute estas instruções
import
para carregar as classes SDK necessárias.from ibmcloudant.cloudant_v1 import CloudantV1 from ibm_cloud_sdk_core import ApiException from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
-
Localize
host
eapikey
em suas credenciais de serviço e substitua os valores emservice_host
eservice_api_key
no exemplo a seguir.service_host = '{host}' service_api_key = '{apikey}'
Não armazene suas credenciais em arquivos de código-fonte. Para aplicativos reais, considere a possibilidade de configurar seu cliente a partir do ambiente.
-
Crie um cliente configurado com os detalhes da instância do serviço.
client = CloudantV1(IAMAuthenticator(service_api_key)) client.set_service_url(f'https://{service_host}')
Aqui,
https://
é prefixado ao host para criar o URL do serviço. Como alternativa, use ourl
das credenciais de serviço, mas se a sua instância não for somente IAM certifique-se de remover as informações do usuário após o protocolo e antes do nome do host. -
Obtenha as informações do servidor com a
get_server_information
API para validar a conexão.client.get_server_information().get_result()
Valide se a saída é semelhante ao exemplo a seguir:
{'couchdb': 'Welcome', 'version': '3.3.3+cloudant', 'vendor': {'name': 'IBM Cloudant', 'version': '8521', 'variant': 'paas'}, 'features': ['search', 'access-ready', 'iam', 'partitioned', 'pluggable-storage-engines', 'scheduler'], 'features_flags': ['partitioned']}
Agora, seu aplicativo Python pode acessar a instância de serviço no IBM Cloud.
Criando um banco de dados na instância de serviço
Em seguida, crie um banco de dados dentro da instância de serviço chamado databasedemo
.
-
Defina o nome do banco de dados com uma variável no aplicativo Python.
database_name = 'databasedemo'
-
Crie o banco de dados usando a
put_database
API.client.put_database(db=database_name).get_result()
Valide se o banco de dados foi criado com sucesso com a saída:
{'ok': True}
Armazenando uma pequena coleção de dados como documentos no banco de dados
Você deseja armazenar uma coleção pequena e simples de dados no banco de dados. Use esses dados em outros tutoriais, como Usando IBM Cloudant Consulta para localizar dados.
-
Crie dados de amostra.
sample_data = [ [1, 'one', 'boiling', 100], [2, 'two', 'hot', 40], [3, 'three', 'hot', 75], [4, 'four', 'hot', 97], [5, 'five', 'warm', 20], [6, 'six', 'cold', 10], [7, 'seven', 'freezing', 0], [8, 'eight', 'freezing', -5] ]
-
Inicializar uma lista de documentos.
sample_docs = []
-
Iterar os dados de amostra para criar dados de documento
Para cada linha da lista
sample_data
, crie um dicionário que mapeie os nomes dos campos para os valores dos elementos de linha. Anexe cada dicionário à listasample_docs
.for row in sample_data: # Make a dictionary for each row document = { 'numberField': row[0], 'nameField': row[1], 'descriptionField': row[2], 'temperatureField': row[3] } # Append the dictionary to the list of documents sample_docs.append(document)
Os dicionários Python são adequados para criar documentos JSON.
-
Crie documentos usando a
post_document
API.for doc in sample_docs: client.post_document(db=database_name, document=doc).get_result()
Esse uso da API
post_document
gera automaticamente IDs de documentos no servidor. Como alternativa, inclua um ID no corpo do documento ou use a APIput_document
para escolher um ID de documento específico.Para criar ou modificar um grande número de documentos em uma única solicitação, há um
post_bulk_docs
API.Verifique se a saída é semelhante ao exemplo a seguir.
{'ok': True, 'id': '43bb97b841c5b16c5ee44f4768e42efa', 'rev': '1-f998fc7b89d4466c1e7bb204b1b00f74'} {'ok': True, 'id': '480d1073dca0bf7bc9f28c2ad2f1383e', 'rev': '1-08b940a61ee2f4a013ba8f4abb307c70'} {'ok': True, 'id': '06266c9793afac3b5740872bc0f83d52', 'rev': '1-7de3d45186982b76243ce5879ccdbef4'} {'ok': True, 'id': '40867bf98071981da37d266d23b681ca', 'rev': '1-60206efd94ac6434740acd53c4278646'} {'ok': True, 'id': '622a70b1e0e9a0311284cd8bf5c439db', 'rev': '1-6d98db97adc12d2e4b114f96d2383a2d'} {'ok': True, 'id': '8c07fdbbf67d5173adc3b3034cd9202c', 'rev': '1-d97d8d0b6928bc743ccbe12b0621ad58'} {'ok': True, 'id': '4afb0c4e8d0c96d729dbf7081cbbe84c', 'rev': '1-462c5395df71106d903bedd29970ddeb'} {'ok': True, 'id': '33376a6ea0644abeef5462ff394755ef', 'rev': '1-523c33f6c5f82a2ae51a8df6366ee92b'}
Recuperando dados
-
Recupere uma lista de documentos no banco de dados usando a
post_all_docs
API.all_docs_result = client.post_all_docs(db=database_name).get_result()
-
Itere as linhas retornadas para visualizar os metadados do documento.
for row in all_docs_result['rows']: print(row['id'])
Verifique se a saída é semelhante ao exemplo a seguir.
43bb97b841c5b16c5ee44f4768e42efa 480d1073dca0bf7bc9f28c2ad2f1383e 06266c9793afac3b5740872bc0f83d52 40867bf98071981da37d266d23b681ca 622a70b1e0e9a0311284cd8bf5c439db 8c07fdbbf67d5173adc3b3034cd9202c 4afb0c4e8d0c96d729dbf7081cbbe84c 33376a6ea0644abeef5462ff394755ef
Essas IDs corresponderão àquelas da etapa de criação anterior.
Em um banco de dados relacional, o primeiro documento armazenado em um banco de dados é sempre o primeiro documento retornado em uma lista de resultados. Essa noção não se aplica necessariamente a bancos de dados orientados a documentos, como IBM Cloudant.
Recuperação completa de um documento
-
Obtém o ID do primeiro documento no banco de dados.
first_doc_id = all_docs_result['rows'][0]['id']
Isso usa o ID da listagem de documentos anterior. Você também pode armazenar o ID da resposta depois de criar o documento.
-
Recupere o conteúdo do documento usando o
get_document
API.client.get_document(db=database_name, doc_id=first_doc_id).get_result()
Verifique se a saída é semelhante ao exemplo a seguir.
{'_id': '43bb97b841c5b16c5ee44f4768e42efa', '_rev': '1-f998fc7b89d4466c1e7bb204b1b00f74', 'numberField': 1, 'nameField': 'one', 'descriptionField': 'boiling', 'temperatureField': 100}
Excluindo o banco de dados
-
Exclua o banco de dados usando a
delete_database
API.try: client.delete_database(db=database_name).get_result() except ApiException as ae: print(f'There was a problem deleting database {database_name}. HTTP status code {ae.status_code}. Error message {ae.message}.')
Valide se o banco de dados foi excluído com êxito com a saída:
{'ok': True}
-
Revisar o tratamento básico de erros, demonstrando uma maneira de lidar com problemas.
Concluindo
-
Encerre a sessão interativa do interpretador Python emitindo um
EOF
, por exemplo, comCtrl+D
. -
Opcionalmente, desative e exclua o ambiente virtual Python.
a. Desativar o ambiente virtual
deactivate
b. Exclua o ambiente virtual.
rm -r cloudantdemo