目標

このチュートリアルでは、Python言語の一連の説明を提供します、 以下のタスクに適しています：

1. IBM Cloudant 上の IBM Cloud® サービス・インスタンスへの接続。
2. サービス・インスタンス内でのデータベースの作成。
3. 小さなデータ・コレクションをデータベース内の文書として保管。
4. データの取得。
5. データベースの削除。

開始前に

サービス・インスタンスへの接続

1. 以下の import ステートメントを実行して、必要なSDKクラスをロードします。

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

2. サービス資格情報の中から host と apikey を探し、次の例の service_host と service_api_key の値を置き換えてください。

   service_host = '{host}'
   service_api_key = '{apikey}'
   

   認証情報をソースコード・ファイルに保存しないこと。 実際のアプリケーションでは、環境からクライアントを設定することを検討してください。

3. サービスインスタンスの詳細で構成されたクライアントを作成します。

   client = CloudantV1(IAMAuthenticator(service_api_key))
   client.set_service_url(f'https://{service_host}')
   

   ここでは、https:// をホストの前につけて、サービスのURLとしています。 あるいは、サービスのクレデンシャルから url を使います。 ただし、インスタンスがIAMのみでない場合は、プロトコルの後とホスト名の前にあるユーザー情報を必ず削除してください。

4. 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 というデータベースを作成します。

1. Python アプリケーションの変数でデータベース名を定義します。

   database_name = 'databasedemo'
   

2. put_database API を使ってデータベースを作成する。

   client.put_database(db=database_name).get_result()
   

   データベースが正常に作成されたことを出力で確認する：

   {'ok': True}
   

小さなデータ・コレクションをデータベース内の文書として保管

小さくて単純なデータ・コレクションをデータベースに保管します。 これらのデータは、IBM Cloudant クエリを使用してデータを検索する のように、他のチュートリアルで使用してください。

1. サンプル・データを作成します。

   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. 文書のリストを初期化する。

   sample_docs = []
   

3. サンプルデータを反復して文書データにする

   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ドキュメントを作るのに適しています。

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

データの取得

1. post_all_docs API を使ってデータベース内の文書のリストを取得します。

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

2. 返された行を繰り返し、ドキュメントのメタデータを表示します。

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

   出力が以下の例と同様であることを確認する。

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

   これらのIDは、前の作成ステップのものと一致する。

リレーショナル・データベースでは、データベースに格納された最初の文書が、常に結果のリストで返される最初の文書となる。 この考え方は、IBM Cloudantのようなドキュメント指向のデータベースには必ずしも当てはまりません。

データベースの削除

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

2. 基本的なエラー処理を復習し、問題を処理する一つの方法を示す。

終了

1. 例えば Ctrl+D のように EOF を発行して、インタラクティブなPythonインタープリター・セッションを終了する。

2. オプションで、Python仮想環境を非アクティブにして削除します。

   a. 仮想環境を無効にする

   deactivate
   

   b. 仮想環境を削除します。

   rm -r cloudantdemo