ラーニング・センター

IBM® Cloudant® for IBM Cloud® ラーニング・センターでは、IBM Cloudant の使用方法の学習に役立つビデオ・シリーズを提供しています。ビデオは、 IBM Cloudantを使用する基本から始まります。これらのビデオでは、文書構造、API、索引付け、および照会について順を追って説明します。また、サービスを強化するアーキテクチャーを中心に説明している 「フードの下」 トピックも含まれています。

再生リストを使用してコースを学習したり、選択したトピックに直接ナビゲートしたりすることができます。

『IBM Cloudant の概要』ビデオ

IBM Cloudant IBM Cloudant の概要を説明する全17回のビデオシリーズについて学んでください。

『IBM Cloudant の概要』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 1 の『IBM Cloudant とは何か?』です。

IBM Cloudant はデータベースであり、IBM Cloud® 内のサービスとして実行されます。その目的は、アプリケーションのデータを安全に保管し、迅速かつ効率的に取得できるようにすることです。 IBM Cloudantの主要機能を以下のリストに示します。

データベース: データの保管と取得を行います。具体的には、JSON 文書ストアです。 JSON は JavaScript から来ていて、普遍的なファイル・フォーマットで単純なオブジェクトを表します。
「ドキュメント」: IBM Cloudant における保管の単位です。文書は文書全体として追加、更新、削除されます。
HTTP API: IBM Cloudantの操作はすべて HTTPS を使用することで実現できます。 HTTP はワールド・ワイド・ウェブを支援するプロトコルであり、IBM Cloudant は Web 向けに構築されたデータベースです。ほとんどのデータベースは、プライベート・ネットワーク内に隠されていて数台のマシンを除いてアクセスできません。 IBM Cloudantは（主に）パブリックインターネット上に存在し、インターネット接続（およびその許可）があれば誰でもアクセスできます。

IBM Cloudant は完全に IBM によって作成されたわけではありません。これは、Apache Foundation が運営するオープン・ソース・プロジェクトである Apache CouchDB に基づいています。 IBM Cloudant は、いくつかの CouchDB コントリビューターを採用していますが、Apache の規則により、その開発を独占することはできません。

このコースの内容の大部分は、IBM Cloudant と同様に Apache CouchDB にも当てはまります。両者の API の 99 % は同じです。相違点については後で指摘します。

IBM Cloudant はサービスとして実行される CouchDB と考えることができます。 IBM Cloudant サービスは、簡単にデプロイすることができ、IBM エンジニアによって 24 時間 365 日管理されます。このサービスには、インストールするソフトウェアも、管理するサーバーも、理解する設定もありません。ユーザーは、CouchDB の専門家でなくてもこれを使用して管理できます。

IBM Cloudant は真にオープン・ソースの基盤上に構築されているため、データ層が特定のプラットフォーム、クラウド、またはベンダーにロックされていないことを確認できます。 IBM Cloudant を CouchDB と組み合わせて使用すると、ご覧のように、複製によってデータを共有するハイブリッド・アプリケーションを作成できます。

コースの後のほうでは IBM Cloudant の内部的な仕組みについて説明しますが、初めのうちは「ブラックボックス」として IBM Cloudant を扱います。

要約すると、Cloudant はオープン・ソース・プロジェクトである Apache CouchDB をベースにしています。 JSON 文書を保管します。 HTTP API を使用してアクセスされるため、HTTP を使用するインターネット上の任意のデバイス（アプリケーション・コード、Web ブラウザー、IoT デバイス、または携帯電話）からアクセスできます。 IBM Cloudant は、複数のハードウェア障害が発生しても運用を継続できる、可用性の高いマネージド・サービスです。

このパートはこれで終わりです。次のパートは『文書』です。

『文書』ビデオ

IBM Cloudant データベースおよび文書がどのように機能するのかについて説明します。

『文書』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

この動画はパート2です IBM Cloudant。

前のセクションでは、IBM Cloudant が JSON 文書ストアであると説明しました。ここでは、それが実際にはどういう意味なのかと、他のタイプのデータベースと比べてどうなのかについて説明します。

ほとんどのデータベースはデータを表と呼ばれる集合で保管します。表では、データの各ユニットが 1 つの行であり、どの行も同じ固定の列を持ちます。各表のスキーマは事前定義されています。これは、列の名前、データ・タイプ、値制約、および他の表との関係が注意深く定義された列のリストです。新規レコードごとに 1 つの行が表内に形成されます。

IBM Cloudant は異なります。

IBM Cloudant サービスでは、(表ではなく) データベースと呼ばれる集合が組み込まれており、各データベースが任意の数の文書を含みます。

このスライドの例では、従来の表形式のデータベースで表現された同じデータと、同じデータがJSONドキュメントとして IBM Cloudantにどのように保存されるかを示しています。

したがって、リレーショナル・データベースのバックグラウンドを持つユーザーにとっては、表は IBM Cloudant では「データベース」であり、行は「文書」です。

IBM Cloudant 文書は、先頭と末尾が中括弧で、いくつかのキーと値属性を含んでいる、JSON オブジェクトでなければなりません。

JSON オブジェクトは 1 メガバイト未満のサイズでなければならず、任意の数のストリング、数値、ブール値、配列、およびオブジェクトを含みます。オブジェクト内のオブジェクトのネストを任意の深さまで続けることができます。

使用されるキーは、好きなように簡潔にも冗長にもできます。

次のリストに示すのは、各データ・タイプがどのように使用されるのかを示すいくつかの単純な文書例です。

最初の例は、個人オブジェクトを示していて、これには、ストリング、ブール値、および、タグの配列が保管されています。
2 番目の例は、ストレージの節約のために短い属性名を使用していて、Web サイトでのクリックなどの Web イベントを表しています。
最後の例は、文書自体にサブジェクトが含まれる場合の例です。

日付についてのメモ。 JSON にはネイティブな日付タイプはないため、日付は 30-October-2018 または類似のフォーマットで保管されるのが一般的です。日付については後でまた説明します。

ここで、最初の実際的な演習のために、www.ibm.com/cloud にアクセスします。まだアカウントをお持ちでない場合は IBM Cloud にアカウントを登録してください。

登録されたら、**「サービス」**をクリックし、Cloudant データベースを検索し、新しいサービスをプロビジョンできます。

IBM Cloudant Lite・サービスは、ユーザーが開発中に限られたキャパシティーで IBM Cloudant を試すことができる無料プランを提供します。その兄にあたるStandard Plan は有料サービスであり、アプリケーションの 1 秒当たりの読み取り、書き込み、照会の数を指定すると、それだけのキャパシティーが確保されます。プロビジョンするキャパシティーおよびデータ・ストレージ使用量の分の料金をお支払いいただきます。

ライト・プランも仕組みは同様です。このプランは、プロビジョンされるキャパシティーが小さく、ストレージ・サイズも固定されていますが、IBM Cloudant サービスのテストの目的には十分です。

IBM Cloudant は「スキームレス」なデータベースであると呼ばれることがよくありますが、この用語をどう定義するかについては慎重でなければなりません。

IBM Cloudantでは、事前にスキーマ（フィールド名、タイプ、制約、関係）を定義する必要がないと言っても間違いではありません。単純に、独自の設計の JSON 文書をデータベースに書き込むことができます。

この柔軟性は開発者に好まれています。独自のコードでデータを設計し、それを JSON に変換してデータベースに書き込むことができるためです。

それでも、データの形 について考えること、特に、データの照会と索引付けの方法の観点でそれを考えることは重要です。これについては後で説明します。

データ設計はやはり必要ではありますが、厳密には、ユーザーが使用するスキーマをデータベースが知る必要はありません。

米国の歴代大統領のデータベースを作成したいとしましょう。単純に、アプリ内でデータの「モデル」を考案し、それを JSON に変換し、データベースに書き込むことができます。この例では、一般的な CouchDB の慣例の 1 つを使用し、「type」フィールドで文書のデータ・タイプを示しています。

将来、この「スキーマ」にさらにデータを追加する場合は、単純にデータベースに新しいオブジェクトを書き込めばよく、そのようにしても IBM Cloudant からエラーが出されることはありません。「address」オブジェクトを追加できるのは、次の文書のみです。

今後作成される文書。
アドレスが分かっている文書のみ

言い換えると、同じタイプの文書でも、フィールドがあるものと、ないものがあり得ます。

データベースのスキーマは、時を経てアプリケーションのニーズに合わせて進化させることができます。スキーマの変更をデータベースに (必ずしも) 知らせる必要はありません。新しい文書を新しいフォーマットで作成することができます。

同じデータベースに複数の文書「タイプ」を保管することさえ可能です。この例では、人、本、場所が同じデータベース内に存在します。どれがどれなのかは、「type」フィールド (このフィールドは慣例であり、IBM Cloudant にとって何かを意味するものではありません) で分かります。

この構成に代わる方法は、3 つのデータベース (人、本、場所) を作成し、各データ・タイプを、そのデータ・タイプ用のデータベースに保持することです。どちらの方法も問題ありません。複数のタイプのデータで照会を実行する必要がある場合や、すべてのデータ・タイプをまとめて複製する必要がある場合は、複数のタイプを同じデータベース内に一緒に保持することを選択できます。それ以外の場合は、別々のデータベースで保持する方法のほうが良いでしょう。

要約すると、IBM Cloudant は「スキーマレス」ではありますが、それでも、最高のパフォーマンスを得るためには詳細なデータ設計が必要であるということに変わりはありません。

リレーショナル・データベースの経験がある場合に特に注意すべき点であるヒントを次に示します。

結合を考えることを避けてください - IBM Cloudant 文書には、1 回の API 呼び出しで取得できるように、そのオブジェクトについて必要なものがすべて含まれている必要があります。
正規化は JSON ストアでは問題になりません。繰り返される値がいくつかあることは、それによってデータ取り出しが効率的になるのであれば許容できます。
文書サイズの制限は 1 MB ですが、実際の文書はそれよりずっと小さくする必要があります。数 KB が標準的です。
データベースにデータが追加されていくだけの「書き込みのみ」の設計パターンをアプリケーションで受け入れることができる場合は、このパターンを採用すると物事が簡単になる可能性があります。短い時間枠内に同じ文書の更新を何度も行うパターンは、例外なく避けるべきです。

このパートはこれで終わりです。次のパートは『文書 ID』です。

『`_id`』ビデオ

IBM Cloudant で _id がどのように機能するのか、リレーショナル・データベースとの違いは何か、独自の _id をどのように定義するのかについて説明します。

『_id』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 3 の『文書 _id』です。

前のセクションでは、IBM Cloudant 文書でデータが保管される仕組みと、アプリケーションが IBM Cloudant データベース内に JSON オブジェクトを保管する方法の柔軟性について説明しました。しかし、いくつかの厳重なルールがあります。

1 つのルールは、すべての文書に固有の識別子が含まれる必要があるということです。これは _id と呼ばれるストリングです。同じデータベース内の2つの文書に、同じ _id フィールドを設定することができます。他のデータベースでは、固有識別子の列を指定しますが、IBM Cloudant では常に _id であり、変更することはできません。

また、リレーショナル・データベースとは異なり、IBM Cloudant には「自動増分 ID」はありません。自動増分 ID とは、1 から始まって文書が追加されるたびに増分していく ID フィールドです。

IBM Cloudant の _id フィールドは、以下のいずれかのストリングです。

IBM Cloudant によって生成される 32 文字のストリング。 ID は固有であることが保証されている、意味のない数字と文字のシーケンスです。
ユーザーが定義するストリングです (データについて何か固有のことを把握している場合)。

以下の例は、独自の文書 _id を提供する方法を示しています。

それを使用して、固有であると分かっている何か、つまり、ユーザーの E メール・アドレスを保管します。登録メカニズムで、1 つの E メール・アドレス当たり 1 人のユーザーというポリシーを適用できます。ユーザーによっては、 _id 内に文書タイプをエンコードすることを選択します。例えば、user:56、book:55 などです。最後の例では、おおよその日時の順にソートするように設計された 32 桁のストリング (アプリで生成されたもの) が使用されています。この方法では、2 次索引なしでデータベースから最新文書を簡単に取り出すことができます。

IBM Cloudant は文書 _ids を取得して索引に保管します (本の目次ページに似ています)。この 1 次索引は _id 順になっていて、IBM Cloudant が文書を文書の _id によって取り出せるようにするために使用されます。つまり、キーと値ストアのように機能します。

_id フィールドを慎重に設計することにより、このフィールドで 1 次索引を使用し、意味があるデータをまとめて 1 次索引で保持することができます。この方法では、後でデータを迅速に取り出すことができます。以上のとおり、時間でソート可能な _ids を使用すると、おおよその日時の順にデータを取り出すことができます。

後ほど、文書 ID の範囲の取得について説明するときに、例を紹介します。

結論として、各文書はデータベース内で固有の _id フィールドを持っていなければなりません。これは IBM Cloudant によって自動生成されるか、または、ユーザーのアプリケーションで提供することができます。後者の場合は、_id フィールドの固有性にユーザーが責任を持つ必要があります。

_id フィールドは、データベースの 1 次索引の基礎であり、後で説明するように、キーと値のルックアップと範囲照会に使用できます。

このパートはこれで終わりです。次のパートは『rev トークン』です。

『rev トークン』ビデオ

文書が追加、編集、削除されたときに IBM Cloudant がリビジョン・トークンを作成する仕組みについて説明します。

『rev トークン』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 4 の『rev トークン』です。

IBM Cloudant の 2 番目の基本的ルールは、文書に改訂があるたびに独自の固有のリビジョン・トークンが付与されることです。これが何を意味するのかを見ていきましょう。

ユーザーがリビジョン・トークンを生成する必要はありません。API を使用して文書の追加、更新、または削除を行うと作成されます。

リビジョン・トークンは、次の 2 つの部分から構成されます。

数字 (1、2、3 など)、および、文書本文の暗号ハッシュ。 (初心者のために説明すると、ハッシュはデータのデジタル「指紋」です。データが変わると、指紋も変わります。同じ指紋は二つとありません。したがって、内容が違う 2 つの文書が同じハッシュを持つことはできません。)

画面上の例から、当社のドキュメントには、 1 に続けてダッシュが付いたリビジョントークン（ _rev で始まるキー）があることがわかります。これは、このリビジョンが文書の最初のリビジョンであることを示しています。 04aa8... で始まる数字は、文書の暗号学的ハッシュ値です。

ドキュメントのライフサイクルに従う場合、ドキュメントは revision 1で始まります。後で変更すると、revision 2などが取得されます。リビジョン番号が増えるたびに、文書の内容も変更されているため、ハッシュが変わります。

1 つの文書が同じ番号で複数のリビジョンを持つことがあります。この例には、revision 3s が 2 つ存在します。このシナリオは競合と呼ばれ、場合によっては「正常」です。その理由はこのコースの後のほうで説明しますが、現時点では、リビジョン番号は文書に更新があるたびに増えると想定しておくことができます。

例として、ある IBM Cloudant 文書のライフサイクルをたどってみましょう。

新規文書が作成されると（自動生成_idまたはユーザー提供 _idのいずれを使用する場合でも）、その文書にはrevision 1が割り振られます。 API 要求に対する応答でトークンが送信されます。通常はこの rev は (その文書を近い将来に変更つもりでなければ) 破棄できます。

_rev がrevision 1 である文書を変更すると、文書は保存され、revision 2 トークンが生成され、API 応答で返されます。文書中の name を Liz から Elizabeth に変更していることに注意してください。

ここまではすべてが十分に単純です。

後でこの文書を削除すると、revision 3 が作成されます。

他のほとんどのデータベースとは異なり、IBM Cloudant は削除された文書の参照を保持します。削除も 1 つの文書改訂にすぎませんが、特別なことが 1 つあり、それは文書本文が _deleted: true に置き換えられるということです。

実際には、文書の最近の改訂履歴 (リビジョンのツリー - 各リビジョン番号が複数ある可能性があることに注意してください) が保持されます。

IBM Cloudant のリビジョン・ツリーを、古いリビジョンを取得するためや、古いリビジョンにロールバック するためのバージョン管理システムとして使用することはできません。リビジョンが上書きされると、古いリビジョンの文書本体は削除され、そのディスクスペースは 「圧縮」 と呼ばれるプロセスで回復されます。圧縮は IBM Cloudant で自動的に発生するため、古いリビジョンを取り出すことができると想定するのは安全ではありません。

要約すると、リビジョン・トークンは、追加、編集、削除が行われるときにデータベースによって生成されます。 (ユーザーが独自にリビジョン・トークンを作成する必要はありません。) 一般的に、リビジョン番号は 1 回に 1 ずつ増分されますが、もっと複雑なシナリオもあり得ます (これらのシナリオについては後で説明します)。古い文書の本文は破棄または圧縮されます (それらを戻すことができることに依存しないでください)。文書を変更するすべての IBM Cloudant 操作では、文書の _id およびその _rev が必要です (このシナリオはほとんどのデータベースとは異なります)。

このパートはこれで終わりです。次のパートは『認証』です。

『認証』ビデオ

レガシー認証および IAM 認証がどのように機能するのかについて説明します。また、IBM Cloudant がどのように資格情報を生成するのか、および、3 つの公式 IBM Cloudant ライブラリーがどのように認証を処理するのかについても説明します。

『認証』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 5 の『認証』です。

既に説明したように、IBM Cloudant は、パブリック・インターネット上の Web ベースのサービスです。自分のデータが安全であり、自身のコードのみがそのデータにアクセスできることを確実にするには、どうすればいいでしょうか? このシナリオでは、認証が関係してきます。

IBM Cloudant は、2 つのタイプの認証をサポートしています。

レガシー認証では、 HTTPを使用する各リクエストにユーザー名またはAPIキーとパスワードが提供されるか、または1回限りのセッションAPIコールを使用するクッキーと交換されます。 1 つのセッション Cookie が定期的に循環されるため、クライアント・コードはリフレッシュされた Cookie を取得して、後続の要求用にそれを保管する必要があります。 IAM 認証は、すべての IBM Cloud サービスを支えるアクセス管理システムです。 IAMで認証するには、IAM APIキーと IBM Cloudantのホスト名が必要です。 IAM API を使用して API キーがベアラー・トークン用に交換され、そのベアラー・トークンが各要求と共に IBM Cloudant に渡されます。ベアラー・トークンが存続するのは 1 時間だけであるため、IAM サービスで定期的に更新される必要があります。 IBM Cloudantがプロビジョニングされた場合、IAMのみの認証情報、またはIAMとレガシーの認証情報の両方を生成できます。どちらにするかはお客様が決定します。

資格情報はどのように生成されるのでしょうか?

IBM Cloud ダッシュボードで、IBM Cloudant サービスの下の**「サービス資格情報」タブにある「新規資格情報」**をクリックします。 IAMキー、基本認証のユーザー名とパスワード、 IBM Cloudantを含むJSONドキュメントが作成されます。

資格情報のセットの例を参照してください。

IAM の場合、API キーとホストが必要です。レガシー認証、ベーシック認証、またはその両方の場合、 URL URLユーザー名とパスワードを含む）が必要です。

IBM Cloudantには、公式のクライアントライブラリとして Java™ Node.js、 Python の3つがあります。

3 つすべてが、認証を自動的に処理します。セッション・トークン用に API キーがどのように交換されるのかや、IAM 認証がどのように機能するのかをユーザーが心配する必要はありません。それは処理されます。

文書の中で API について説明するときは、利便性のために基本認証を使用します。しかし、可能な場合は IAM 認証を使用することをお勧めします。そのほうが、IBM Cloud プラットフォームとの統合がより良くなり、きめ細かい許可が可能になるためです。

次の実際的な演習の時間です。

IBM Cloudにログインし、前回作成した IBM Cloudantを見つけます。「サービス資格情報」タブで「新規資格情報」ボタンをクリックして、「IAM+Legacy」資格情報のセットを生成します。返されるJSONをメモしてください。次の演習で必要になります。

次に、資格情報 JSON に指定されている URL にアクセスします。何が表示されますか?

要約すると、資格情報は IBM Cloud ダッシュボードから生成されます。 IAM のみ、または、IAM とレガシー両方の資格情報を持つことができます。どちらの認証方式でも、時間制限付きトークンの資格情報の交換 (認証) があり、その後、ユーザーがサービスを使用するのに応じてトークンは定期的に更新されます。公式ライブラリーがこれらのタスクをすべて処理してくれます。

このパートはこれで終わりです。次のパートは『ダッシュボード』です。

『ダッシュボード』ビデオ

IBM Cloudant ダッシュボードと、そこで何が提供されるのかについて説明し、使用方法を紹介します。

『ダッシュボード』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 6 の『ダッシュボード』です。

開始して、データベースを作成し、文書を追加するための最も簡単な方法は、IBM Cloudant ダッシュボードを使用することです。

IBM Cloudant ダッシュボードは、サービスに組み込まれている Web アプリです。これを使用すると、グラフィカル・ユーザー・インターフェースを介して、基本的なデータ操作を実行できます。データベースの作成と削除を行うことができます。文書の追加、更新、削除、および複製ジョブの管理を行うこともできます。また、一度限りのクエリを実行したり、2次インデックスを設定したりするのにも便利な場所です（後述）。

要求レートを視覚化するシンプルなモニター・ツールもいくつか含まれています。

IBM Cloudant ダッシュボードで実行可能なすべての作業は IBM Cloudant HTTP API でも実行できることに注意することは重要です。実際、IBM Cloudant ダッシュボード自体そのものは、標準 API 呼び出しを実行するだけです。

IBM Cloudant サービスのダッシュボードを開くには、IBM Cloud にログインし、IBM Cloudant サービスを見つけて、**「IBM Cloudant ダッシュボードの起動」**ボタンをクリックします。新しいウィンドウが開き、IBM Cloudant ダッシュボードにログインできます。

何もせずにダッシュボード・ウィンドウを一定時間放置すると、(セキュリティー上の目的で) ログアウトされ、もう一度**「起動」**をクリックしなければなりません。

ダッシュボードにはいくつかのタブがあります。そのデフォルトのタブである**「データベース」**には、作成済みのデータベースが、20 個ずつのグループでリストされます。各データベースには、保存されている文書数と使用中のディスク容量が表示されます。データベース名をクリックすると、そのデータベースの内容を調べることができます。

データベースを作成するには、**「データベースの作成」**をクリックし、作成するデータベースの名前を指定します。

そうすると、新しい空のデータベースが作成されます。データベースの文書があれば ID 順に表示されます。しかし、これは新しいデータベースであるため、文書は存在しません。文書を追加するには、**「文書の作成」**をクリックします。

事前生成された _id が含まれているテンプレート文書が IBM Cloudant ダッシュボードによって作成されました。残りの属性を自分で入力して JSON 文書を完成させ、**「文書の作成」**をクリックして保存します。

次の実際的な演習の時間です。 books という名前のデータベースを作成し、そのデータベース内に 3 つまたはそれ以上の文書を作成します。文書には、title、author、date、publisher、および ISBN というフィールドがあり、各文書が任意の 1 つの本を表します。

作成が終わったら、いずれかの文書を編集して発行日を変更します。

次に、いずれかの文書を削除します。

要約すると、IBM Cloudant ダッシュボードは、IBM Cloudant サービスに組み込まれている Web アプリであり、CouchDB オープン・ソース・オファリングの一部です。これは、データベース、文書、索引、照会、および複製ジョブの管理に使用されます。サービス・スループットをモニターするためにも使用できます。ダッシュボードは単なる API クライアントです。ダッシュボードで実行できるすべてのことは、HTTP API を使用してスクリプト化できます。

このパートはこれで終わりです。次のパートは『HTTP API の基礎』です。

『HTTP API の基礎』ビデオ

コマンド・ラインを使用して HTTP 要求を行い、文書を追加、編集、および削除する方法について説明します。

『HTTP API の基礎』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 7 の『HTTP API の基礎』です。

前のパートでは、IBM Cloudant の API へ HTTP 呼び出しを行う Web アプリである IBM Cloudant ダッシュボードについて説明しました。このステップでは、コマンド・ラインを使用して HTTP 要求を行い、いくつかの文書の追加、編集、削除を試行します。

もっと高水準のクライアント・ライブラリーを使用する予定であっても、HTTP API を最初の基本的原則から理解することには価値があります。

HTTP API を持つデータベースの利点は、必要であれば、インターネット上の任意のデバイスからデータを読み書きできることです。特別なソフトウェアは必要ありません。カスタム・プロトコルを使用するドライバーはありません。標準 HTTP ライブラリーのみです。例えば、以下のすべてが HTTP を使用します。

Web ブラウザー
任意のプログラミング言語
コマンド行から curl などのスクリプトを作成するために使用できるツール
モバイル・デバイス

HTTP 要求をディスパッチできる、オープン・ソースの無料のコマンド・ライン・ツールである curl を使用して、この API について学習していきます。 curl は、ほとんどの Mac および Unix 系のオペレーティング・システムにプリインストールされています。ご使用のコンピューター上に存在しない場合は、curl を Google 検索し、インストール手順に従ってください。

まず、curl を使用して、Web ページ (Google のホーム・ページ) をフェッチしてみましょう。

コマンド・ライン端末で「curl https://www.google.com」と入力します。

応答でページいっぱいの HTML が返されます。
この方法がうまくいけば、curl はインストール済みであり、次の作業に進むことができます。 IBM Cloudant URL毎回入力するのは面倒なので IBM Cloudant URL URLに保存しましょう。
export URL コマンドを実行して、URL という変数を作成します。後でこの変数にアクセスします。

export URL=https://username:password@host
alias を作成します。

alias acurl="curl -sgH 'Content-type: application/json'"

この alias は、追加の入力を省略するための acurl というショートカットです。このacurl コマンドは、curl の別名ですが、JSON content-type ヘッダーと、いくつかの便利なコマンド・ライン・スイッチがあります。
alias をフェッチすることでこのacurl $URL/ をテストします。 IBM Cloudant から何らかの JSON が返されます。

最初の IBM Cloudant API 呼び出しが完了しました。これで acurl 別名がセットアップされました。 API の探索を開始できます。データベースのリストを返す _all_dbs エンドポイントから始めましょう。
データベースの配列を表示するため、acurl $URL/_all_dbs と入力します。

コマンド・ラインでの JSON のフォーマットについてここで簡単に注意点を説明します。 acurl コマンドの出力を別のツールに送信することができ、そのツールが端末でデータを見やすくフォーマットします。次のツールを利用できます。

JqはページURL から利用可能で、単なるJSONフォーマッタ以上の機能があります。JSONの解析、クエリ、操作も可能です。
ご使用のコンピューターに Python がインストールされている場合は、シンプルな JSON フォーマッターである python -m json.tool を使用できます。

したがって、acurl $URL/_all_dbs | jq は、「acurl の出力を jq にパイプする」という意味であり、見やすくフォーマットされて色分けされた出力が表示されます。

IBM Cloudant API のパスは階層型であり、第 1 レベルがサービスについての情報を提供し、その下のレベルに各データベースが位置しています。

acurl $URL/books は、以前に作成した書籍データベースに関する情報を提供します。

いくつの文書があるのか、いくつの文書が削除されたのか、占有しているディスク・スペースはどのくらいなのかについての情報が表示されます。

整った出力を得るために、出力を jq または Python にパイプすることを忘れないでください。

データベースに含まれている文書を確認したい場合は、_all_docs エンドポイントを使用できます。

したがって、acurl $URL/books/_all_docs は、指定した URL にある IBM Cloudant サービスから、books データベースのすべての文書を取得することを意味します。

このコマンドによって、各文書の _id 値と _rev 値のリストが返されます。文書の本文も取得したい場合は、?include_docs=true を API 呼び出しに追加します。

単一の文書をデータベースからフェッチする場合、文書は URL の階層内でデータベースの 1 つ下のレベルに位置しています。

したがって、acurl $URL/books/id は、「指定した URL にある IBM Cloudant サービスから、books データベースの文書 ID を取得する」ことを意味します。

階層に注意してください。サービス、データベース、および文書です。

ここまでは、GET HTTP メソッドのみを使用しました。これは、curl のデフォルトであり、Web ブラウザーに URL を入力するときに使用されるものです。

IBM Cloudant の API は、しばしば HTTP メソッドをverb として使用して、データベースに依頼するアクションを記述します。データのフェッチには GET が使用されます。

curl では、使用するメソッドを -X コマンド・ライン・オプションで指定できます。

したがって、API を使用して新しい文書を books データベースに書き込むには、POST メソッドを使用し、HTTP 要求の本体として文書を渡します。

acurl -X POST は、 POSTHTTP メソッドを使用することを指定します。-dは、書き込む文書を指定します。これは、要求の本体として送信され、最後に、書き込み先の URL$URL/books（books データベース）を指定します。

代わりの方法として、書き込まれる文書の ID を指定する場合は、PUT メソッドを使用できます。 URL は、$URL/books/ の後に書き込みたい ID が続いたものになります。

どちらの書き込み方式でも、応答は同じです。 OK: 書き込みが成功したことを示す。 ID は、書き込まれた文書の ID であり、rev はデータベースによって生成されたリビジョン・トークンです。

文書を変更するには、 PUT メソッドを使用して、上書きする文書 ID を指す URL に新しい本文を書き込むことができます。-d は、新しい文書本文を提供します。 URL には、文書のデータベースと ID だけでなく、 rev（変更する文書のリビジョン）も含まれます。

rev パラメーターを忘れて省略してしまうと、エラー応答が返されます。

要求が成功したかどうかは HTTP 応答コードで分かります。 200 代の範囲にある応答は成功です。 400 代の範囲にある応答はユーザー・エラー (例えば、無効なパラメーター)、500 代の範囲にある応答はサーバー・サイドのエラーです。さらに、-v コマンド・ライン・オプションを curl/acurl に指定することによって、HTTP 要求および応答の全体を確認できます。

また、文書に対する更新は、文書全体で起こるか、まったく起こらないかのどちらかです。ドキュメントの一部を変更するAPI構造は存在しません。前のリビジョンを上書きするには、文書全体を指定する必要があります。

最後に、文書を削除するには、DELETE メソッドを使用します。つまり、-X DELETE です。データベース名および削除する文書が含まれている URL に要求を送信します。また、rev の指定も不可欠です。これは、削除する文書のリビジョンです。

リビジョン・トークンを省略すると、エラーが返され、要求は失敗します。

要約すると、HTTP API を理解することは、ユーザーのコードと IBM Cloudant サービスの間の関係を把握するのに役立ちます。

URL は階層型です。service/database/document、または、service/database/endpointです。

HTTP メソッドは、実行するアクションを定義するverbs として機能します。

すべてのアクションは、単純な HTTP API 呼び出しを使用して、コマンド・ラインから、または、ユーザーのコードからトリガーすることができ、したがって、簡単にスクリプト化できます。

このパートはこれで終わりです。次のパートは『一括 API』です。

『一括 API』ビデオ

2 つの API 呼び出しの使用方法について説明します。これらは、基本的なすべての IBM Cloudant 操作を実行するためのものですが、複数の文書を 1 回の API 呼び出しで操作することもできます。

『一括 API』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 8 の『一括 API』です。

前のパートでは、IBM Cloudant HTTP API を使用して、1 個単位で文書を簡単に追加、更新、削除する方法を確認しました。このパートでは、2 つの API 呼び出しを使用して基本的なすべての IBM Cloudant 操作を実行する方法を説明します。この方法のプラスの利点としては、1 回の API 呼び出しで複数の文書を操作できるということがあります。

_all_docs エンドポイントについては既に説明しました。 1 つのデータベース内のすべての文書のリストをフェッチするためにこのエンドポイントを使用しましたが、このエンドポイントにはそれ以外にも機能があります。

key パラメーターを使用して、フェッチする単一の文書を指定できます。これは、GET /db/id API 呼び出しと等価です。同様に、keys パラメーターは文書 ID の配列を指定し、それらすべてが返されることになります。 startkey パラメーターと endkey パラメーターは、指定された限度範囲にある 1 次索引をフェッチします。 include_docs=true を追加することで、IBM Cloudant に文書本文も提供するように指示できます。また limit は、1 回の API 呼び出しで返される文書の数を指定します。

_bulk_docs エンドポイントを使用すると、1 回の API 呼び出しで、複数の挿入、更新、および削除の操作を実行できます。 docs 配列を含んでいるオブジェクトが予期されていて、その配列の各要素が、単一の文書に対して実行する操作です。要求本体が IBM Cloudant に送信され、多くの操作を 1 つの API 呼び出しにまとめることができます。

この例では、最初の文書は挿入です。リビジョン・トークンが指定されていないからです。 2 番目の文書は、新しい文書本文と共にリビジョン・トークンが指定されているため、文書に対する更新です。 3 番目の文書は削除です。リビジョン・トークンが指定されていますが、本文は単に _deleted: true です。これは、この文書を削除済みとマークするよう IBM Cloudant に指示します。

このシナリオはリレーショナル・データベースのトランザクションのようなものではないことに注意することは重要です。これらの操作のすべてが個々に成功または失敗する可能性があります。この要求に対する応答データでは、各操作に対する応答が順に示されます。

要約すると、2 つの API 呼び出し_bulk_docsおよび_all_docsを使用すると、 IBM Cloudant 文書に対してすべての作成、読み取り、更新、および削除の操作を実行でき、一括で実行することもできます。_all_docsは、_idまたは ID の範囲によって文書を取得します。_bulk_docsは、文書を一括して作成、更新、および削除します。一般的には、一括書き込みは 500 個ずつのバッチで実行することをお勧めします。ただし、文書が小さければもっと多く、文書が大きければもっと少なくすることができます。

コマンドラインターミナルから IBM Cloudant を使用している画面キャプチャをご覧ください

このパートはこれで終わりです。次のパートは『IBM Cloudant へのプログラムでのアクセス』です。

『IBM Cloudant へのプログラムでのアクセス』ビデオ

IBM Cloudant にプログラマチックにアクセスする方法について説明します。

『IBM Cloudant へのプログラムでのアクセス』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 9 の『IBM Cloudant へのプログラムでのアクセス』です。

ここまでは、API 対話は、ダッシュボードによってトリガーされるか、コマンド・ラインから curl を使用してトリガーされました。以下のセクションでは、プログラマチックに IBM Cloudant にアクセスする方法について説明します。

例では Node.js が使用されるため、コードを実際に試してみたい場合は、node と npm を nodejs.org からインストールする必要があります。

その後、npm install @cloudant/cloudant によって、公式 IBM Cloudant Node.js ライブラリーをインストールできます。 (npm は Node.js に同梱されているパッケージ・マネージャーであり、何千ものオープン・ソース・プロジェクトにアクセスしてそれらをユーザーのアプリケーションに無料で組み込むことを可能にします)。

IBM Cloudant ライブラリーがインストールされたら、ソース・コードを作成できます。このコード・スニペットを行ごとに見ていきましょう。

IBM Cloudant サービスの URLは、先に作成した環境変数から取得します。

組み込みの必須関数を使用して、@cloudant/cloudant ライブラリーを Node.js アプリにロードします。次に、最初の行で保管した資格情報を使用して構成された、ライブラリーのインスタンスを作成します。この IBM Cloudant オブジェクトを使用して、books データベースへの参照を取得し、それを変数データベースに保管します。 APIコールは一切行っていません。認証情報を格納するデータ構造を作成し、作業対象のデータベースを指定しただけです。 main 関数が db.list を呼び出します。これは、前に説明した _all_docs エンドポイントと 1 対 1 で対応します。 db.list に渡されるパラメーターは、_all_docs で結果セットを制限することと ID ごとの文書本文を返すことを指定するオプションとして、なじみがあるものです。

ドキュメントを書き込む別のコードスニペットをご覧ください。

最初の行から分かるように、コードでは標準 JavaScript オブジェクトを使用でき、それらは JavaScript でネイティブに JSON になるため、変換なしで IBM Cloudant に送信できます。

文書の書き込みは、単に db.insert を呼び出すことであり、これが PUT/POST API 呼び出しまたは _bulk_docs に対応します。

まとめると IBM Cloudantの公式ライブラリは Java™ Python、Nodejsです。これらは、IBM Cloudant HTTP API のシン・ラッパーであるため、基礎となっている API を理解して、すべてのパラメーターを理解する価値があります。

これらのライブラリーは、ユーザーに代わって次の 2 つのことを処理します。これは便利です。

認証: レガシー認証か IAM かに関係なく、トークン用に鍵を交換します。
再試行ロジック: プロビジョン済みキャパシティーを超えた API 呼び出しを再試行するようにライブラリーを構成できます。このように構成されている場合、指数関数的バックオフによって複数回にわたって API 呼び出しが一時停止され再試行されます。

こういった API 呼び出しの再試行は、一時的かつ予期しないトラフィックの上昇の場合には妥当なことです。プロビジョンされたキャパシティーを毎度のように超える場合は、再試行を重ねてもデータベースの作業は終わりません。もっとキャパシティーが必要です。

このパートはこれで終わりです。次のパートは『照会』です。

『照会』ビデオ

IBM Cloudant でデータを照会するためのさまざまな方法について説明します。

『照会』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 10 の『照会』です。

これまでは、コマンドライン、ダッシュボード、コードから、CRUD（作成、取得、更新、削除）操作を行いました。これらの操作では、文書の _id を使用します。

_id で文書をフェッチします。
_id が「x」の文書を更新します。
_id が「x」の文書を削除します。
_id 範囲が「a」から「z」の文書を取得します。

これらの操作はデータベースのビルディング・ブロックですが、これらだけでは、できることに限界があります。文書内のフィールドでの一致に基づいて文書のサブセットを返す必要がある場合は、どうすればいいでしょうか。個人の誕生日？本のタイトル? 注文の値?

ここに照会が表示されます。

IBM Cloudant にはデータ照会の方法がいくつか存在します。まず、IBM Cloudant 照会 と呼ばれるものを見ていきましょう。

IBM Cloudant 照会の言語は、MongoDB 照会言語から着想を得ています。照会は JSON で表現され、返されるデータのサブセットを selector 属性で記述します。照会実行のためにデータベースの _find エンドポイントに照会 JSON が送信されます。

最も単純な形式の照会は、ある属性にある固定値が設定されている文書を見つけるというものです。例えば、where author == J Smith です。

2 番目の例は、照会に 2 つの節が含まれるものです。文書が検索結果に入るためには両方の節が満たされる必要があります。例えば、where isbn === 6725252 AND date = 2018-01-01 です。

3 番目の例は、論理演算子の追加方法を示しています。 $gt の演算は greater than を意味します（また、 gte を「以上」または「以上等しい」に、 lt/lte を「以下」または「以下等価」に用いることもできます）。 $or 演算子は OR 演算であるため、一致する文書は、date がこの照会に指定されているものより大きく、かつ、author が J Smith であるか、または、title が Murder! であるものでなければなりません。

文書内のオブジェクトにアクセスする必要がある場合、標準のドット表記を使用できます。例えば、address オブジェクト内部の郵便番号ストリングにアクセスするには、address.zipcode とします。

以下のパラメーターも追加できます。

フィールド: 返されるようにする文書属性を指定します (デフォルトは文書全体です)。
Sort: データのソート方法を定義します。 sort は配列であり、複数の属性でソートが計算されるようにできます。
制限: 返される文書の数。

リレーショナル・データベースのバックグラウンドをお持ちの場合、この照会は最後の IBM Cloudant 照会例と等価の SQL 照会です。

WHERE 節は、 IBM Cloudant Query. ORDER およびLIMITのSELECTORに相当します。 IBM Cloudant Query FIELDS リストは、SELECTキーワードの後の属性のコンマ区切りリストと同等です。

JSON 構文に慣れるまでに少し時間がかかるかもしれませんが、MongoDB ユーザーにはなじみがあるかもしれません。

IBM Cloudant ダッシュボードで IBM Cloudant 照会を実行できます。処理するデータベース (例: books) を選択し、「照会」タブを選択します。

提供されるボックスに IBM Cloudant 照会 JSON を入力し、準備ができたら**「照会の実行」**をクリックします。結果セットがページに表示されます。

「説明」ボタンは、指定された照会をデータベースがどのように解釈するのかについての説明を提供するために使用されます。この説明は、次のパートの『索引付け』で、もっと重要になります。

curl からも照会をトリガーできます。この場合、照会 JSON はファイルに保管され、POST 構文を使用して _find エンドポイントに -d@ command-line されます。

Node.js コードは似ています。照会は標準 JavaScript オブジェクトであり、それが db.find 関数に渡され、POSTs エンドポイントに _find されます。

ここからは、実際の演習の時間です。 20 世紀に書かれた本のタイトルを見つける IBM Cloudant 照会を考えてください。必要であれば、IBM Cloudant 照会の資料は画面上に示されている URL にあります。

解答を知りたくない場合は、このプレゼンテーションをここで一時停止してください。

1 つのソリューションをご覧ください。

$and 演算子を使用して、date 属性に関する 2 つの節を結合します。一方の節は日付が >= 1900の文書を検索し、もう一方の節は日付が < the year 2000の文書を検索します。文書が選択されるには、どちらの節も true でなければなりません。一致する本のタイトルのみが必要なため、文書全体を返すのではなく、fields 属性を指定します。

要約すると、IBM Cloudant Query は、構文が JSON 形式で表現される MongoDB から着想を得た照会言語です。

照会は、文書の _id だけに限らず、文書内部のデータに対して作用する節を使用して、データベースから文書のサブセットを選択します。

照会は、プログラムによってか、curl を使用してか、またはダッシュボードを使用して、データベースの _find エンドポイントに送信されます。

データのどの部分が必要なのかを照会の selector が決定します。

このパートはこれで終わりです。次のパートは『索引付け』です。

『索引付け』ビデオ

索引付けが照会処理を高速化できる仕組みについて説明します。

『索引付け』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 11 の『索引付け』です。

前のパートで実行した照会は最適ではありませんでした。回答を得るために、IBM Cloudant はデータベース内のすべての文書を順にスプールして、検索基準を満たしているかどうかを確認しなければなりませんでした。

パフォーマンスが良くスケーラブルな方法で照会を実行するには、索引付け が必要です。

IBM Cloudant を使用すると、任意の数の索引を指定できます。

索引は、文書リストから作成される 2 次データ構造です。これには、指定するフィールドでソートされたデータが含まれます (例えば、date と title でソートされた本)。文書の date と title が一致するデータを求める照会を実行する場合、索引付けされたデータ構造の使用によって照会プロセスを速めることができます。すべての文書を順にスキャンする代わりに、IBM Cloudant は索引の関連する部分 (例えば、20 世紀の本のセクション) にジャンプし、データを迅速に取り出すことができます。

IBM Cloudant 照会索引には、type=json と type=text の 2 つのタイプの索引が含まれます。これらのインデックスは、このコースの後の部分で説明する2つの基本的なインデックス技術によって支えられています。

索引は、JSON をデータベースの POST エンドポイントに _index するときに定義されます。

index オブジェクトに含まれている fields 配列が、索引付けする文書属性を指定します。通常、索引付けが必要なフィールドは、データを取り出すために使用する照会の selector で使用される属性と等価です。つまり、date フィールドでの照会が必要な場合は、date フィールドを索引付けする必要があります。

索引の name はオプションですが、これは良い慣例であり、ここではそれに従うことにします。 IBM Cloudant に質問をするときに、使用したい索引の名前を指定することは良いことです。そのようにすれば、IBM Cloudant は使用する索引を使用可能な索引の中から選択せずに済み、ユーザーにとってはどの索引がどれなのかを覚えるのが容易になります。

ダッシュボードから、books データベースに索引を作成しましょう。データベースを選択し、「文書の設計」タブを選択し、メニューから**「索引の照会」**を選択します。

既存のインデックスはすべてサイドにリスト表示されます。ドキュメントの _id に基づいて、プライマリインデックスを表す special インデックスが存在しなければなりません。

JSON で索引定義を完成させます。

終わったら、「索引の作成」をクリックします。

このボタンをクリックすると、POST エンドポイントに _index 要求が送信されます (既存の索引を更新および削除するために使用できる、他の API 呼び出しもあります)。

索引は IBM Cloudant によってバックグラウンドで非同期に作成されます。大規模なデータベースの場合、IBM Cloudant による初回の索引生成には時間がかかることがあります。この初期ビルドが使用可能になるまでは、索引でデータベースを使用することはできません。

20 世紀の本の照会を繰り返し使用します。今回は、use_index フィールドで索引名を指定します。回答が返されますが、今回は索引の効果で高速になっています。小さいデータベースの場合はスピードが上がったことに気付かないかもしれませんが、データ・サイズと照会量が増えるのにつれて、きっと利点が感じられます。索引付けは、アプリケーションが大きくなるのに従って、照会のパフォーマンスを維持するのに役立ちます。

2 次索引を作成するよう IBM Cloudant に指示すると、バックグラウンド・タスクが開始されます。すべての文書が順に調べられ、ディスク上に新しいデータ構造である索引が作成されます。インデックスは、キー（インデックス化が必要な属性）と、それらが由来するドキュメント _id とを関連付けたバランスのとれたツリーです。

このインデックスを使用すると、データベース全体を再スキャンすることなく、既知のキーやキーの範囲を効率的に検索することができます。

索引付けを行う際に採用できる別の効果的な手法は、部分フィルターです。オプションで、索引定義に部分フィルターを指定できます。この IBM Cloudant 照会セレクターは、索引付けの際に、どの文書のデータを索引にし、どれを無視するのかを決定するために実行されます。

この例では、週末に該当する日付のみを索引に使用するためのセレクターが採用されています。索引が小規模になるほど、高速になり、効率的になります。データのサブセットのみの索引付けが必要なユース・ケースの場合は、索引作成時の部分フィルター・セレクターが、索引をより小さく、より効率的にするのに役立ちます。例えば、完了した注文のみ、期限が切れたアカウントのみ、または公開されたブログ投稿のみ索引付けすることができます。

要約すると、_index エンドポイントを使用して索引を定義し、オプションの部分フィルターを照会時に適用することで、より小さい、まばらな索引にすることができます。

このパートはこれで終わりです。次のパートは『MapReduce』です。

『MapReduce』ビデオ

2 次索引を構成するためのもう 1 つの方法である MapReduce について説明します。

『MapReduce』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 12 の『MapReduce』です。

JSON 文書の内容に対して照会を実行するために、_find エンドポイントと _index エンドポイントの組み合わせを使用する方法を説明しました。アプリケーションが大きくなるのにつれて増大する照会を 2 次索引が支えます。

このパートでは、MapReduce と呼ばれる、2 次索引を構成するための別の方法を紹介します。

MapReduce は、CouchDB に 2 次索引を構成する唯一の方法でしたが、今でも文書の本文内のデータを照会するための一般的な方法です。

MapReduce 索引を作成するには、設計文書と呼ばれる特殊な文書内にラップされた JavaScript 関数を IBM Cloudant に提供する必要があります。設計文書の _id フィールドは _design/ で始まります。例: _design/mydesigndoc。

IBM Cloudant は、設計文書を受け取ると、索引付けのバックグラウンド・タスクをセットアップし、データベースから各文書を順に JavaScript 関数に渡します。 JavaScript 関数が出力するキーと値が、永続する索引の基礎を形成します。

いくつかの JavaScript 関数の例を見てみましょう。

この関数は 1 つのパラメーター (IBM Cloudant 索引作成機能によって渡される文書) を受け入れます。常に関数呼び出しによって、索引のキーと値をから渡されるパラメーターが出力されます。

最初の例は、キー doc.name を出力します。この例では、これは name フィールドによる検索のための索引です。値はありません (null)。

2 番目の例は、出力の前にデータを事前処理しています。この事前処理は、ストリングの整理、空白のトリミング、テキストの大文字化と小文字化、欠落データへのデフォルト値の適用、特定範囲への値の制約などを行うための便利な方法です。

3 番目の例ではロジックが追加されています。published である文書のみが索引に使用されます。このロジックは IBM Cloudantで見た部分フィルタセレクタと同等です。

索引は非同期でビルドされ、完全にビルドされるまでは使用できません。作成されると、キーによる選択、キーのリスト、キーの範囲、およびデータの集約に使用できます。例えば、 「2 つの日付の間でオーダーを検索し、月別にグループ化されたオーダーの合計値を計算します。」 と入力します。

IBM Cloudant には 4 つの組み込みリデューサーが含まれます (none をカウントすると 5 つあります)。

_count: 物事を数えるために使用します。
_sum: 値を合計するために使用します。
_stats: カウントおよび合計を提供するために使用します。平均、偏差、および標準偏差の計算に適しています。
_approx_count_distinct: キーのユニークな値のおおよそのカウント用。

設計文書のMAP 関数に doc が渡されます - この関数は、データベース内の文書ごとに 1 回呼び出されます。 emit 関数から MAP されたキーと値のペアが索引を作成します。

KEY は、select の基準にしたいもの (例えば日付) です。

VALUE は、報告する必要のあるもの (例えば売上合計) です。

リデューサーは _sum なので、一致するキーのVALUE (例: 同じ日付の注文) が合計されます。

MapReduce の定義は IBM Cloudantで確認できます。

MapReduce ビューがビルドされたら、それを照会して、索引に保管されたKEY-VALUE の各ペアを確認できます。

あるいは、リデューサーがオンになっている場合、結果セットを各キーの値でグループ化できます。このケースでは、毎日の売上を合計します。

個々のキー (例えば、特定の日の売上)、すべてのキー、またはキーの範囲 (例えば、2 つの日付の間) について、このビューを照会できます。

MapReduce ビューは非同期に作成され、大規模なデータ・セットの場合は準備できるまで時間がかかることがあります。

以下のヒントを参照してください。

意味のあるデータのみを含めるようにする (例えば、完了した注文のみを合計する) には、JavaScript 内でロジックを使用します。索引付けされるキーは、ストリングである必要はありません。一般的なパターンは、配列キーを使用することです。例えば、年、月、日の配列です。それらの索引キーを使用すると、照会時に配列の要素でグループ化できるようになります。例えば、年別の注文、年月別の注文、年月日別の注文などです。これは、ユーザーが詳細までドリルダウンできるようになっている要約レポートの場合に便利です。値は、ストリング、数値、ときには文書のサブセットを含む小さなオブジェクトにすることもできます。オブジェクトは、include_docs=true を追加する代わりに使用できます。これも結果セットに文書本文を返します。

要約すると、MapReduce は、データの選択と集約を可能にする索引を定義するための低水準の手段です。

JavaScript ロジックを使用して、どのデータが索引に入れられるのかを決定します。キーと値を出力することによって、索引がどのように形成されるのかを選択します。

組み込みのリデューサーを使用してデータを要約します。多くのデータから簡潔なレポートを効率的に作成します。

MapReduce は、アプリケーションが何度も実行する必要があるボイラープレート照会にとっては素晴らしいものです。データ探索のための 1 回限りの随時照会には向いていません。

このパートはこれで終わりです。次のパートは『日付』です。

『日付』ビデオ

日付または日時の値を保管するためのさまざまなオプションについて説明します。

『日付』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 13 の『日付』です。

このコースの前半で、JSON ネイティブでは、ストリング、数値、ブール値、オブジェクト、および配列のみがモデル化されることを説明しました。一般的なユース・ケースの 1 つが、データベースに日付または日時の値を保管することです。 IBM Cloudantでそれを実現する方法のアイデアをご覧ください。

時刻を表すための ISO-8601 ストリング・フォーマットでは、時刻は、年、月、日、「T」文字、時、分、秒、ミリ秒、タイム・ゾーンから構成されます (y-m-dTh:m:s.msTIMEZONE)。

さまざまな地域からデータを収集する場合でも、UTC タイム・ゾーンの日付を保管することが常に推奨されます。この形式で保管された日付はフロントエンドで簡単にローカル・タイム・ゾーンに変換できます。通常、各ユーザーのデータを「同じユニット」を使用して保管することが重要です。

このストリング・フォーマットは、(最も重要な日付ユニットがストリングの先頭にあるため) 日時の順にソートされ、MapReduce 関数で簡単に構文解析できます。

2 番目のオプションは、01-January-1970 以降の、ミリ秒の数値を保管することです。このオプションも、日付と時刻を表すための標準的で機械可読の方法です。

これも MapReduce 関数で構文解析でき、2 つの日付の比較に便利です。単に一方のタイム・スタンプを他方から引き算するだけです。

まとめると、JSONにはネイティブのデータ形式が存在しないため、日付と時刻を好きなように保存することができます。 ISO-8601 はコンパクトで可読であり、使いやすくソートされています。タイム・スタンプ (1970 年以降はミリ秒) も同様です。

構成要素の 1 つに対して IBM Cloudant 照会を使用する必要がある場合は、それを文書内で明示的に抜き出しておく必要があります。

このパートはこれで終わりです。次のパートは『複製』です。

『複製』ビデオ

IBM Cloudant における複製の意味と、さまざまなタイプの複製とその仕組みについて説明します。

『複製』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 14 の『複製』です。

複製は IBM Cloudant の中核機能の 1 つです。これは、あるデータベース (ソース) から別のデータベース (ターゲット) へのデータ転送です。

ソースデータベースとターゲットデータベースは、 IBM Cloudant上に存在することも、地理的に離れた場所に存在することもできます。例えば、 IBM Cloudantをヨーロッパのデータベースに複製するといった場合です。

IBM Cloudant 複製プロトコルは Apache CouchDB と共有されています。そのため、クラウド・ベースのデータベースから、自社の場所にある CouchDB が実行されているデータベースにデータをコピーする企業が複製を使用することがよくあります。

IBM Cloudant または CouchDB との間 (どちらか一方向) でデータを複製するために、PouchDB (Node.js スタックまたは Web ブラウザー内で実行される JavaScript ベースの CouchDB クローン) も使用できます。

IBM Cloudant 同期ライブラリーは、iOS または Android のネイティブ・アプリであり、IBM Cloudant サービスとの間でデータを同期します。

複製はソースからターゲットへの一方向の操作であり、すべてのデータ（削除、競合、添付ファイル、ドキュメントなど）を移動させます。複製は次の2つの方法のいずれかで実行できます

ソースのすべてのデータがターゲットに到達するまで実行し、その後で停止します。
最初の方法と同じですが、複製の実行を永久に継続して、新しいデータが届いたらソースからターゲットに転送されるようにします。

レプリケーションは、最後に停止した場所から再開することもできます。 IBM Cloudant は、最後に認識された位置から既存の複製を再開できるように、複製元パーティー間でcheckpointsのメモを保持します。

IBM Cloudant ダッシュボードには複製タブが含まれています。複製を開始するには、認証資格情報を含むソース・データベースとターゲット・データベースを指定し、この複製が 1 回限りの操作なのか、継続的操作なのかを指定します。

複製に名前を付けることもできます。これは、複製ジョブを識別して追跡するのに便利です。

実際的な演習の時間です。

IBM Cloudant ダッシュボードに移動します。
books2 という名前のデータベースを作成します。
books から books2 への継続的な複製を開始します。
books2 データベースにアクセスして、books からの文書が books2 内にあることを確認します。
books データベースに文書を追加します。
この変更が books2 データベースに対して行われることを検証します。

複製を使用して、IBM Cloudant データベースからオンプレミス CouchDB インスタンスにデータを移動できます。複製は IBM Cloudant からも CouchDB からも制御できます。例えば、変更を CouchDB に送信するように IBM Cloudant に指示することも、IBM Cloudant から変更をプルするように CouchDB に指示することもできます。複製を制御する側には、両方の HTTP API のネットワーク可視性がなければなりません。

PouchDB も同じ複製プロトコルを使用するため、PouchDB と IBM Cloudant の間でデータを転送するために使用できます。この場合は、複製を制御する側になる可能性が高いのは PouchDB です。

一般的に、PouchDB は、オフライン・ファーストのアプリを作成するために使用されます。そういったアプリは、インターネットに接続されていなくてもデータを収集し、オンラインに戻ったら IBM Cloudant にデータを書き込んで、ユーザーに常にサービスを提供します。

複製は常に必要とは限りません。アプリケーションがデータを保管し、後で IBM Cloudant に書き込む必要がある場合、厳密に言えば複製は必要ありません。必要なのは、データがデバイスに保管され、接続が回復したときに IBM Cloudant に一括で書き込まれることです。

複製は片方向の操作であるため、異なるリージョンにある 2 つの IBM Cloudant インスタンス間でプライマリー - プライマリーのセットアップが必要な場合は、反対方向の 2 つの複製が必要です。

ロンドン側で発生する変更はダラスに送信され、その逆も同様です。

IBM Cloudant サービスのセットを囲む輪のようにデータが流れる、もっと複雑なトポロジーも可能です。

要約すると、IBM Cloudant 複製は、ソース・データベースからターゲット・データベースにデータをコピーするためのメカニズムです。

複製は、1 回限り行うことも継続的に行うこともできます。オプションで、JavaScript 関数または IBM Cloudant 照会セレクターを使用してフィルタリングしたり、前回停止したところから複製を再開したりすることもできます。

このパートはこれで終わりです。次のパートは『パーティション・データベース』です。

『パーティション・データベース』ビデオ

IBM Cloudant においてパーティション・データベースがどのように機能するか、特定のシャードに文書を割り当てるにはどうするか、および、パーティション・データベースによってパフォーマンス、コスト、スケーラビリティーが向上するのはなぜなのかについて説明します。

『パーティション・データベース』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 15 の『パーティション・データベース』です。

後述のように、IBM Cloudant は分散データベースです。 IBM Cloudant サービスは多数のストレージ・ノードで構成されていて、データベースの文書は、shardsと呼ばれるグループに分けられたノードに分散されます。単一のデータベースがsharded されます。つまり、複数の断片に分割されます。

通常の IBM Cloudant データベースでは、1 つの文書に 1 つのシャードが割り振られ、アルゴリズムで効率的に、文書はシャード間でランダムに分散されます。

パーティション・データベースでは、パーティション・キーを指定することによって、どのシャードに文書が保管されるのかを定義します。

パーティション化されたデータベースは、同じ PUT /<database name> APIコールではなく、追加のクエリ文字列パラメータ： partitioned=true を使用して作成されます。

最初の例では、products データベースがパーティション・データベースとして作成され、2 番目の例では、パーティション化されていない標準データベースとして作成されます。

パーティション・データベースに文書を追加する場合は、文書 _ID を指定する必要があります（自動生成された文書 _ID は存在しません）。文書 _id には 2 つの部分があり、それらがコロン文字で区切られています。

パーティション・キー: 文書を保管するパーティションを定義するストリング。
文書キー: パーティション内で文書を一意的に識別するストリング。

最初の例では、1 つの本が products データベースの book パーティションに追加されています。

次に、別の文書が DVD パーティションに追加され、3 番目の文書が household パーティションに追加されています。

これの効果は、同じパーティション・キーを共有する文書が、データベースの同じシャードに存在するということです。同じパーティション内の文書は、文書キーの順序で一緒に保管されます。

データを取得するときに利点が得られます。 IBM Cloudant 照会、MapReduce 要求、および検索を、1 つのパーティションに誘導できます。この例では、IBM Cloudant 照会セレクターが book パーティションに送信されています。このアクションは、IBM Cloudant インフラストラクチャーの一部のみを使用することを意味します (book パーティションをホストするシャードのみが使用され、クラスターの残りの部分はアイドルのままになります)。

このシナリオでは、照会のパフォーマンスが速くなり、照会コストが低くなり、スケーラビリティーが向上します。

パーティション化された照会のパフォーマンスを高めるために重要なのは、パーティション・キーの選択です。

これは、データ・セット内で反復する値である必要があります。例えば、book パーティション内にはいくつかの項目があります。多くのパーティションがある必要があります。少数のカテゴリーしかない場合、カテゴリーはパーティション・キーにはふさわしくありません。例えば、IoT アプリケーションでは deviceId、e-コマース・システムでは orderId など、多くの値があるものである必要があります。アプリケーションが行う照会に一致するものである必要があります。最も一般的なユース・ケースが製品カテゴリー内での検索である場合、カテゴリーでのパーティション化が適切でしょう。ホット・パーティションを避けてください。トラフィックはパーティション間で均等に分散されなければなりません。選択したパーティション・キーによって、少数のパーティションにトラフィックの大幅な増加が生じることになりそうな場合、そのパーティション・キーの選択は適切ではありません。

要約すると、パーティション・データベースは partitioned=true フラグを指定して作成されます。文書の ID は 2 つの部分からなり、パーティション・キーと文書キーがコロン文字で結合されています。

同じパーティション内の文書は、同じデータベース・シャードに文書キーの順序で保管されます。この保管の方式を知っていると、照会を単一のパーティションに誘導して、高速かつ安価に実行することができます。

パーティション・データベース内のパーティションをまたがって照会を行うこともできます。 2 次索引を作成するときに、その目的がパーティション単位なのかグローバル・スコープなのかを選択します。

このパートはこれで終わりです。次のパートは『IBM Cloudant 検索』です。

『IBM Cloudant 検索』ビデオ

IBM Cloudant 検索を使用する方法、および Lucene 照会言語とファセットについて説明します。

『IBM Cloudant 検索』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

このビデオはパート 16 の『IBM Cloudant 検索』です。

IBM Cloudant では、照会と索引付けの別の方式として、IBM Cloudant 検索と呼ばれるものがあります。このパートでは、これを簡単に説明します。

IBM Cloudant 検索は、別のオープン・ソース・プロジェクトである Apache Lucene に基づいて構築されています。Apache Lucene は、Elasticsearch を含む多くの製品で検索機能を強化するために使用されています。

これは主にフリー・テキスト検索用に設計されていて、索引付けの前にテキストのブロックが事前処理されます。大文字小文字の違い、句読点、一般的なノイズ語が除去され、一般的な言語固有の語末がトリミングされます (例えば、farmer が farm に、farms が farm になります)。

このテキスト処理は、照会時、つまり検索時に、選択したアナライザーによって実行されます。この時点より前に、ファセットという技法を使用するいくつかの集約機能を使用することもできます。

IBM Cloudant 検索索引は JavaScript 関数を提供することによって作成されます。これは emit 関数が index 関数に置き換えられることを除くと、MapReduce と似ています。index 関数は、フィールドの名前、データ自体、いくつかのオプションを予期します。

この例では、デフォルト・オプションを使用して文書の name と title が索引付けられています。 category はファセット (集約機能) の候補です。ISBN は索引に保管されますが、検索用にそれ自体が索引付けられてはいません。項目を索引に保管しておくほうが、照会時に include_docs=true を行うよりも効率的な場合があります。

Lucene には、ロジック、ファジー・マッチング、範囲、用語ブースティングを使用して節の組み合わせを突き合わせる照会を作成する、独自の照会言語があります。

以下の例を参照してください。

タイトルが gastby に一致し、著者が fitz で始まる文書を見つけます。アスタリスクのワイルドカードに注意してください。
author が austen to dickens までの範囲にある文書を見つけます。この例は、ストリング・フィールドでの範囲照会を示しています。
価格が 0 - 100 までで、AND、年が 19th century であるか、または、著者が charles dickens に一致する文書を見つけます。この例は、ロジックを照会に組み込む方法を示します。

IBM Cloudant 検索は、フリー・テキスト検索に役立つだけではありません。検索に使う属性は分かっているが、属性の組み合わせが毎回異なり、さまざまな照会があるといった場合にも有用です。固定順序の MapReduce 索引でこの柔軟性を実現するのは困難です。

ファセットは、集約の 1 つの形式です。索引付け時に、索引付けられる個々のフィールドをファセットの候補にし、照会時に、パラメーターで集約をアクティブにします。

2 つの使用法があります。

結果セット内の反復値をカウントします (例えば、結果セット内の各カテゴリーに属している製品の数)。または、数値範囲内の項目数をカウントします (例えば、各価格帯の製品の数)。これらの両方の形のカウントを、既存の検索をさらにフィルタリングして検索のスコープを絞るための手段として、フロントエンド・ユーザーに提示できます。例えば、ある顧客が「Fender」を検索し、**「Amps」**をクリックし、under $500 の価格帯をクリックします。この検索およびフィルタリングのすべてに IBM Cloudant 検索のパワーを利用できます。

要約すると、IBM Cloudant 検索索引は、提供される JavaScript 関数を使用して定義されます。 Apache Lucene に基づいてビルドされ、主にフリー・テキスト検索マッチングに使用されますが、照会言語は、索引付けられたフィールドの固定セットでの柔軟な照会を作成するのに便利です。ドリルダウン用ユーザー・インターフェースに適したいくつかの強力なカウント集約機能もあります。

IBM Cloudant 検索は type=text IBM Cloudant 照会索引も強化するため、その機能の一部は _find API を使用して表面化します。

このパートはこれで終わりです。次のパートは『中身の確認』です。

『中身の確認』ビデオ

IBM Cloudant サービスがどのように編成されているのかを説明します。

『中身の確認』ビデオの台本

IBM Cloudant へようこそ。このコースは、17本のビデオシリーズで構成されており、 IBM Cloudant の概要を説明します。

この動画はパート17 「エンジンルーム」 です。

IBM Cloudant サービスの編成方法を見てみましょう。この概要は、CouchDB 2 および 3 にマップされる IBM Cloudant サービスに適用されます。 CouchDB 4 はさまざまなテクノロジーに基づいて構築されています。

IBM Cloudant は、複数のストレージ・ノードからなるクラスター全体でデータが保管される分散データベースです。 IBM Cloudant サービスをノード (この例では 12 個) のリングとして描いてみてください。すべてのノードが着信 API 呼び出しを処理することができ、すべてのノードがデータの一部 (クラスターに存在するデータベースのシャードおよび関連付けられた 2 次索引) を保管する責任を担っています。

IBM Cloudant にデータが書き込まれると、リング内のノードの 1 つがその要求を処理します。このノードの仕事は、データの 3 つのコピーを 3 つのストレージ・ノードに保管するよう指示することです。データは IBM Cloudant で三重に保管されるため、データベースの各シャードは、多くの場合 1 つのリージョンの複数のアベイラビリティー・ゾーンにまたがって、複数回保管されます。

データを書き込む API 呼び出しを行い、応答が戻されると、3 つのストレージ・ノードのうち少なくとも 2 つにデータが書き込まれています。データはディスクにフラッシュされます。フラッシュされるためにメモリーにキャッシュされることはありません。この技法はリスクが大きすぎ、データ損失が生じやすいと考えられます。

データベースを作成すると、クラスター全体に分散して、いくつかのデータベース・シャードが作成されます (デフォルトでは 16 個)。シャードごとに 3 つのコピーがあるため、48 個のシャード・コピーになります。

ユーザーがこのアクティビティーを見ることはありません。このアクティビティーは、ユーザーがデータベースを作成すると透過的に処理されます。

いずれかのノードがダウンした場合、または保守のためにリブートが必要な場合、どうなるのでしょうか? クラスターの残りの部分は通常どおりに続きます。ほとんどのシャードはデータの 3 つのコピーを持ちますが、一部のシャードは 2 つしか持ちません。 API 呼び出しは通常どおりに機能し続けますが、データの 2 つのコピーのみが書き込まれます。

2 つのノードがダウンした場合でも、ほとんどのシャードにはコピーが 3 つ、一部のシャードには 2 つ、一部のシャードには 1 つ、まだあることになります。書き込みは引き続き機能しますが、 HTTP 応答コードには、クォーラム (定足数) である 2 ノードの確認には至らなかったことが反映されます。

読み取りについても同じです。障害が発生したノードがあってもサービスは続行します。障害が発生したノードが 1 つの場合は大丈夫です...

あるいは、障害が発生したノードがもっと多くても。各ノードのコピーがあれば、API は機能し続けます。

ノードが戻ると、そのノードは仲間のノードから欠落データをすべて取得し、その後でサービスに復帰して、API 呼び出しを処理し、データ照会に応答します。

この構成の性質として、IBM Cloudant は結果整合性を示します。すべてのノードが要求を処理できます。データは、リレーショナルデータベースでよく見られるようなロックをかけずに、ノードの周りに分散されます。

IBM Cloudant は整合性よりも可用性を重視します。整合性の保証を提供できないため、ダウンするよりも、稼働して API 呼び出しに応答します。 (リレーショナル・データベースの構成はこれとは反対であることがよくあります。整合性のある方法で動作するか、まったく動作しないかです。) 開発者にとっての結果整合性の結論は、アプリで短時間に read its writes べきではないということです。更新した文書より古いバージョンの文書が表示される可能性がある小さいウィンドウが存在する場合があります。最終的にデータはクラスター全体を流れるようになります。ほとんどの場合、クォーラム・メカニズムが整合性の幻影を提供しますが、それに依存しないのが最善です。

CouchDB 4 とそのコード・バージョンに基づく IBM Cloudant サービスでは、別の整合性モデルが採用されています。

短い時間枠内で何度も文書を更新することが必要なデータ・モデルの場合、同じリビジョン番号について複数の書き込みが受け入れられる可能性があります。これらの書き込みは、リビジョン・ツリーの枝になる可能性があり、それは競合と呼ばれます。この例では、リビジョン 2 が 2 種類の異なる方法で変更され、リビジョン 3 が 2 つ作成されています。競合をプログラムで整理することは可能ですが、極端な環境ではパフォーマンスの問題につながる可能性があるため、競合は回避しなければなりません。

また、複製を使用していて、文書がさまざまな方法で変更され、競合するリビジョンが複製を使用してマージされた場合にも、競合が発生する可能性があります。このシナリオでは、 IBM Cloudant はデータを破棄しません。 winning の改訂版が選択されますが、非当選の改訂版にアクセスでき、アプリケーションで新しい当選者を決定したり、不要な改訂版を削除したり、必要な操作を行うことで、競合を解決することができます。競合はエラー状態ではありません。これは、ロックせずに変更できるデータの切断されたコピーがあるという副次作用です。 IBM Cloudant は、競合する変更を破棄するのではなく、競合として保管することによって、競合を処理することを選択します。

競合がないか文書をチェックするには、単に ?conflicts=true を単一文書のフェッチに追加します。競合するリビジョンがあれば、すべて _conflicts 配列にリストされます。

削除したいリビジョンの rev トークンを指定して通常の DELETE 操作を使用することによって、不要なリビジョンを削除できます。一括 API は、同じ文書から複数の競合を削除する場合でも競合リビジョンを削除するのに適しています。

要約すると、 IBM Cloudant は、データベースを保管する分散サービスです。データベースは複数のシャードに分割され、各シャードの 3 つのコピーがストレージ・ノードのリングに分散されます。 IBM Cloudant は結果整合性があり、強い整合性よりも高可用性を優先します。

競合を生まないため、同じ文書に何度も書き込むことを避けてください。複製状況では、時には衝突が避けられないこともあるが。

結果整合性を受け入れる - IBM Cloudant を整合性のあるものにしようとしないでください。

CouchDB 4 ベースの IBM Cloudant 製品には、異なる整合性モデルが存在する場合があります。

これでこのコースは終了です。詳しくは、 IBM Cloudant の資料およびブログを参照してください。