创建和填充数据库

本教程说明如何使用 Python 编程语言在 IBM Cloud 服务实例中创建 IBM® Cloudant® for IBM Cloud® 数据库。您还将学习如何使用简单的数据集合来填充数据库。

本教程未使用最高效的 Python 代码。目的是展示简单易懂的工作代码，您可以从中学习并应用于自己的应用程序。您可以从中学习并应用到自己的应用程序中。您必须在自己的应用程序中采用正常的最佳实践来检查和处理所有警告或错误条件。

目标

本教程提供了一系列 Python语言指令、适用于以下任务：

连接到 IBM Cloudant 上的 IBM Cloud® 服务实例。
Creating a database within the service instance.
将一个小型数据集合存储为数据库中的文档。
正在检索数据。
删除数据库。

准备工作

准备 IBM Cloudant 服务实例

设置服务凭证需求。

a. 通过遵循入门教程来创建服务实例和凭证。

b. 按照查找服务凭证教程获取凭证。

本教程使用 IAM 凭据类型进行身份验证。

安装 Python 并准备环境

安装所需版本的 Python。

您的系统必须安装当前版本的 Python 编程语言。

a. 在提示符下运行以下命令，检查 Python 是否已安装：
```
python3 --version
```
b. 验证您是否获得类似于以下示例的结果:
```
Python 3.12.5
```
创建并激活虚拟环境

a. 创建虚拟环境：
```
python3 -m venv cloudantdemo
```
这会在当前工作目录下创建一个名为 cloudantdemo 的子目录。你可以选择另一条路。

b. 激活虚拟环境：
```
source cloudantdemo/bin/activate
```
For more information about Python virtual environments and instructions for alternative operating systems see the Python standard library venv 文档.
为 Python 安装 IBM Cloudant SDK
```
pip install ibmcloudant
```
验证 IBM Cloudant SDK 的 Python 安装。

a. 通过在提示符处运行以下命令来检查是否已成功安装客户机库:
```
pip show ibmcloudant
```
您将获得有关 ibmcloudant 软件包信息的输出。

b. 检查输出结果，其开头几行应与下面的示例类似：
```
Name: ibmcloudant
Version: 0.9.1
```
启动交互式 Python 解释器

a. 在虚拟环境中运行 python 命令，启动解释器
```
python
```
b. 验证您是否获得了与下例类似的输出结果：
```
Python 3.12.5
Type "help", "copyright", "credits" or "license" for more information.
>>>
```
通常，您不会在 Python中单独运行命令。您通常会创建一个脚本，该脚本是要运行的命令的列表，存储在 Python 文件中，扩展名为 .py。

连接到服务实例

运行这些 import 语句加载必要的 SDK 类。

from ibmcloudant.cloudant_v1 import CloudantV1
from ibm_cloud_sdk_core import ApiException
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

在服务证书中找到 host 和 apikey 并替换下面示例中 service_host 和 service_api_key 中的值。
```
service_host = '{host}'
service_api_key = '{apikey}'
```
不要在源代码文件中存储凭据。对于实际应用，可考虑从环境中配置客户端。
创建一个配置了服务实例详细信息的客户端。
```
client = CloudantV1(IAMAuthenticator(service_api_key))
client.set_service_url(f'https://{service_host}')
```
这里，https:// 是主机的前缀，用于生成服务 URL。或者使用服务凭证中的 url，但如果您的实例不是仅限 IAM 的请确保删除协议之后、主机名之前的用户信息。

使用 get_server_information API 获取服务器信息，以验证连接。

client.get_server_information().get_result()

验证输出类似于下面的示例：

{'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']}

现在，Python 应用程序可以访问 IBM Cloud上的服务实例。

在服务实例中创建数据库

接下来，在服务实例中创建名为 databasedemo 的数据库。

在 Python 应用程序中使用变量定义数据库名称。
```
database_name = 'databasedemo'
```
使用 put_database API 创建数据库。
```
client.put_database(db=database_name).get_result()
```
通过输出验证数据库创建成功：
```
{'ok': True}
```

将一个小型数据集合存储为数据库中的文档

您想在数据库中存储一个小的简单的数据集合。在其他教程中使用这些数据，如使用 IBM Cloudant 查询查找数据。

创建样本数据。

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]
]

初始化文件列表。
```
sample_docs = []
```

迭代样本数据，生成文档数据

为 sample_data 列表中的每一行创建一个字典，将字段名与各行元素的值进行映射。将每个字典添加到 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)

Python字典适用于制作 JSON 文档。

使用 post_document API 创建文档。

for doc in sample_docs:
    client.post_document(db=database_name, document=doc).get_result()

使用 post_document API 可在服务器上自动生成文档 ID。或者在文档正文中包含一个 ID，或者使用 put_document API 来选择特定的文档 ID。

对于在一次请求中创建或修改大量文件，有一个 post_bulk_docs API。

验证输出是否与下面的示例相似。

{'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'}

检索数据

使用 post_all_docs API 读取数据库中的文档列表。

all_docs_result = client.post_all_docs(db=database_name).get_result()

遍历返回的行以查看文档元数据。

for row in all_docs_result['rows']:
    print(row['id'])

验证输出是否与下面的示例相似。

43bb97b841c5b16c5ee44f4768e42efa
480d1073dca0bf7bc9f28c2ad2f1383e
06266c9793afac3b5740872bc0f83d52
40867bf98071981da37d266d23b681ca
622a70b1e0e9a0311284cd8bf5c439db
8c07fdbbf67d5173adc3b3034cd9202c
4afb0c4e8d0c96d729dbf7081cbbe84c
33376a6ea0644abeef5462ff394755ef

这些 ID 将与上一个创建步骤中的 ID 一致。

在关系数据库中，数据库中存储的第一个文档总是结果列表中返回的第一个文档。这一概念并不一定适用于面向文档的数据库，例如 IBM Cloudant。

文档完整检索

获取数据库中第一个文档的 ID。
```
first_doc_id = all_docs_result['rows'][0]['id']
```
这使用的是之前列出文件的 ID。您也可以在创建文档后从响应中存储 ID。

使用 get_document API 读取文档内容。

client.get_document(db=database_name, doc_id=first_doc_id).get_result()

验证输出是否与下面的示例相似。

{'_id': '43bb97b841c5b16c5ee44f4768e42efa', '_rev': '1-f998fc7b89d4466c1e7bb204b1b00f74', 'numberField': 1, 'nameField': 'one', 'descriptionField': 'boiling', 'temperatureField': 100}

删除数据库

使用 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}.')

通过输出验证数据库已成功删除：

{'ok': True}

复习基本的错误处理，演示处理问题的一种方法。

正在完成

发出 EOF 结束交互式 Python 解释器会话，例如 Ctrl+D。
可选择停用并删除 Python 虚拟环境。

a. 停用虚拟环境
```
deactivate
```
b. 删除虚拟环境。
```
rm -r cloudantdemo
```