IBM Cloud Docs
Criando e preenchendo um banco de dados

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:

  1. Conectando-se a uma instância de serviço do IBM Cloudant na IBM Cloud®.
  2. Criando um banco de dados na instância de serviço.
  3. Armazenando uma pequena coleção de dados como documentos no banco de dados.
  4. Recuperando dados.
  5. Excluindo o banco de dados.

Antes de Iniciar

Preparar uma instância de serviço IBM Cloudant

  1. 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

  1. 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
    
  2. 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.

  3. Instale o IBM Cloudant SDK para Python

    pip install ibmcloudant
    
  4. 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
    
  5. Inicie o interpretador interativo Python

    a. Execute o comando python no ambiente virtual para iniciar o interpretador

    python
    

    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

  1. 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
    
  2. Localize host e apikey em suas credenciais de serviço e substitua os valores em service_host e service_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.

  3. 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 o url 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.

  4. 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.

  1. Defina o nome do banco de dados com uma variável no aplicativo Python.

    database_name = 'databasedemo'
    
  2. 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.

  1. 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]
    ]
    
  2. Inicializar uma lista de documentos.

    sample_docs = []
    
  3. 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 à lista sample_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.

  4. 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 API put_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

  1. 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()
    
  2. 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

  1. 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.

  2. 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

  1. 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}
    
  2. Revisar o tratamento básico de erros, demonstrando uma maneira de lidar com problemas.

Concluindo

  1. Encerre a sessão interativa do interpretador Python emitindo um EOF, por exemplo, com Ctrl+D.

  2. Opcionalmente, desative e exclua o ambiente virtual Python.

    a. Desativar o ambiente virtual

    deactivate
    

    b. Exclua o ambiente virtual.

    rm -r cloudantdemo