拡張複製

拡張複製の概念およびタスク (以下のリストのものなど) について学習できます。

複製データベースの保守
複製のスケジューリングとモニタリング
複製中の認証

レプリケーション・プロトコルの詳細を確認することも役に立つだろう。レプリケーション・プロトコルの詳細を確認し、 APIリファレンスドキュメントを見直すことも役に立つでしょう。

複製データベースの保守

複製データベースは、他のデータベースと同様にモニターする必要があります。定期的なデータベースの保守を実行しない場合、複製プロセスの中断が原因で発生した無効な文書が累積する可能性があります。無効な文書が多数あると、IBM® Cloudant® for IBM Cloud® 操作によってレプリケーター・プロセスが再始動したときに、クラスターにかかる負荷が過剰になる可能性があります。

複製データベースを保守するため、古い文書を削除します。古い文書を削除するには、その経過時間を判別し、不要になった場合は削除します。

複製スケジューラー

新規 IBM Cloudant 複製スケジューラーは、以前の IBM Cloudant 複製メカニズムと比較して、多くの改善点および機能拡張を提供します。

特に、複製中のネットワーク使用の効率が上がりました。スケジューラーでは、複製タスクの割り振り決定時に、クラスター内の個別データベース・ノードの現行負荷が考慮されます。

最後に、複製の状態がさらに詳細になり、以下の 7 つの異なる状態で構成されるようになりました。

initializing - 複製がスケジューラーに追加されましたが、まだ初期化も実行のスケジュールもされていません。新規または更新された複製文書が _replicator データベース内に保管されると、この状況が発生します。
error - 複製をジョブに変換できません。このエラーはさまざまなことが原因で発生する可能性があります。例えば、複製をフィルターに掛ける必要がある際に、ソース・データベースからフィルター・コードを取り出すことができなかった場合などです。
pending - 複製ジョブは実行がスケジュールされていますが、まだ実行されていません。
running - 複製ジョブは実行中です。
crashing - 複製ジョブに影響する一時エラーが発生しました。ジョブは後で自動的に再試行されます。
completed - 複製ジョブが完了しました。この状態は、継続的複製には適用されません。
failed- 複製ジョブが失敗しました。失敗は永続的です。この状態は、この複製タスクを使用してこれ以上複製を試行しないことを意味します。この失敗は、例えば、ソース URL またはターゲット URL が無効な場合など、さまざまなことが原因で発生する可能性があります。

これらの状態間の遷移を以下の図に示します。

状態間の遷移は、、、、およびです。 — Replication Scheduler states

スケジューラーには、以下の 2 つの新規エンドポイントが導入されています。

これらのエンドポイントを使用すると、複製状況をより迅速かつ簡単に管理および判別できます。

複製スケジューラーを使用して複製を管理およびモニターするための標準的なプロセスを以下に示します。

必要なレプリケーションを記述したレプリケーション・ドキュメントを作成し、レプリケーター・データベースに格納する。
/_scheduler/docs エンドポイント使用して、複製の状況をモニターします。

複製中の認証

どのような実動アプリケーションでも、ソース・データベースとターゲット・データベースのセキュリティーは不可欠です。複製を続行するには、データベースにアクセスするための認証が必要です。レプリケーションのチェックポイントはデフォルトで有効になっています、つまり、ソース・データベースをレプリケートするには書き込みアクセスが必要です。

複製中の認証を有効にするには、データベース URL にユーザー名とパスワードを含めます。複製プロセスでは、指定された値が HTTP 基本認証に使用されます。

複製中にソース・データベースおよびターゲット・データベースにアクセスするためのユーザー名とパスワードの値を指定する例を以下に示します。

{
  "source": {
    "url": "https://example.com/db",
    "auth": {
      "basic": {
        "username": "$USERNAME",
        "password": "$PASSWORD"
      }
    }
  },
  "target": {
    "url": "https://$ACCOUNT.cloudant.com/db",
    "auth": {
      "basic": {
        "username": "$USERNAME",
        "password": "$PASSWORD"
      }
    }
  }
}

IAM 認証情報については、以下の例を使用して IAM API キーで認証します：

{
  "source": {
    "url": "https://example.com/db",
    "auth": {
      "iam": {
        "apikey": "$APIKEY"
      }
    }
  },
  "target": {
    "url": "https://$ACCOUNT.cloudant.com/db",
    "auth": {
      "iam": {
        "apikey": "$APIKEY"
      }
    }
  }
}

フィルターされた複製

すべての文書をソースからターゲットに転送しない場合があります。転送する文書を選択するには、ソース上の設計文書に 1 つ以上のフィルター関数を含めます。その後、これらのフィルター関数を使用するようにレプリケーターに指示できます。

複製中の文書のフィルタリングは、_changes フィードのフィルタリングのプロセスと似ています。

フィルター関数は、以下の 2 つの引数を取ります。

複製される文書。
複製要求。

フィルター関数は、true または false の値を返します。結果が true の場合、文書は複製されます。

フィルタリングをセットアップするには、可能な限り selector フィールドを使用します。 selector フィールドを使用すると、フィルターを指定でき、データベース全体を複製する必要がなくなります。この方法によって、フィルタリングがより高速になり、IBM Cloudant の負荷が軽減されます。詳しくは、'selector フィールドのドキュメントを参照のこと。

フィルター関数の例を以下に示します。

function(doc, req) {
	return !!(doc.type && doc.type == "foo");
}

フィルターは、設計文書の最上位の filters キーの下に保管されます。

設計文書にフィルター関数を保管する例を以下に示します。

{
	"_id": "_design/myddoc",
	"filters": {
		"myfilter": "function goes here"
	}
}

フィルターに掛ける複製は、以下の項目を識別する JSON ステートメントを使用して開始されます。

ソース・データベース。
ターゲット・データベース。
設計文書の filters キーの下に保管されているフィルターの名前。

フィルターに掛ける複製を開始するための JSON の例を以下に示します。

{
  "source": {
    "url": "https://example.org/example-database",
    "auth": {
      "basic": {
        "username": "$USERNAME",
        "password": "$PASSWORD"
      }
    }
  },
  "target": {
    "url": "https://$ACCOUNT.cloudant.com/example-database",
    "auth": {
      "basic": {
        "username": "$USERNAME",
        "password": "$PASSWORD"
      }
    }
  },
  "filter": "myddoc/myfilter"
}

呼び出しの query_params フィールドに key: value ペアを組み込むことにより、フィルター関数に引数を提供できます。

指定されたパラメーターを使用してフィルターに掛ける複製を開始するための JSON の例を以下に示します。

{
  "source": {
    "url": "https://example.org/example-database",
    "auth": {
      "basic": {
        "username": "$USERNAME",
        "password": "$PASSWORD"
      }
    }
  },
  "target": {
    "url": "https://$ACCOUNT.cloudant.com/example-database",
    "auth": {
      "basic": {
        "username": "$USERNAME",
        "password": "$PASSWORD"
      }
    }
  },
  "filter": "myddoc/myfilter",
  "query_params": {
    "key": "value"
  }
}

selector オプションを使用すると、filter オプションを使用する場合と比較して、パフォーマンスが向上します。可能な限り、selector オプションを使用してください。詳しくは、「selectorドキュメントを参照のこと。

複製を使用する競合の除去

winning_revs_only: true オプションは、勝利文書リビジョンのみを複製する場合に使用します。これらのリビジョンは、デフォルトで GET $ACCOUNT/$DATABASE/$DOCID API エンドポイントによって返されるか、以下の場所に表示されるリビジョンです。デフォルト・パラメーターを使用した _changes フィード。

{
	"source": {
	  "url": "https://example.org/example-database",
	  "auth": {
	    "basic": {
	      "username": "$USERNAME",
	      "password": "$PASSWORD"
	    }
	  }
	},
	"target": {
	  "url": "https://$ACCOUNT.cloudant.com/example-database",
	  "auth": {
	    "basic": {
	      "username": "$USERNAME",
	      "password": "$PASSWORD"
	    }
	  }
	},
	"winning_revs_only": true
}

このモードの複製では、競合するリビジョンが破棄されるため、複製によって競合を削除する 1 つの方法になる可能性があります。

winning_revs_only: true によって生成される複製 ID とチェックポイント ID 複製は、デフォルトで生成される複製とは異なるため、最初にウィニング・リビジョンを複製し、次にウィニング・リビジョンを後で複製することができます。残りのリビジョンを通常の複製ジョブで バックフィル します。

winning_revs_only: true オプションは、フィルターや、 continuous: true や create_target: true などの他のオプションと組み合わせることができます。

指定文書の複製

必要に応じて、文書を複製しない場合もあります。単純な複製の場合、フィルター関数を作成する必要はありません。代わりに、特定の文書を複製するために、 doc_ids フィールドにキーのリストを配列として追加します。

特定の文書を複製する例を以下に示します。

{
	"source": {
	  "url": "https://example.org/example-database",
	  "auth": {
	    "basic": {
	      "username": "$USERNAME",
	      "password": "$PASSWORD"
	    }
	  }
	},
	"target": {
	  "url": "https://127.0.0.1:5984/example-database",
	  "auth": {
	    "basic": {
	      "username": "$USERNAME",
	      "password": "$PASSWORD"
	    }
	  }
	},
	"doc_ids": ["foo", "bar", "baz"]
}

`user_ctx` プロパティーおよび委任

複製文書には、カスタム user_ctx プロパティーを指定できます。このプロパティーは、複製が実行されるユーザー・コンテキストを定義します。

POST エンドポイントへの /_replicate/ を行うことにより複製をトリガーする古い方法では、user_ctx プロパティーは必要ありませんでした。これは、複製をトリガーした時点で、認証済みユーザーに関するすべての必要な情報が使用可能であるためです。

これに対して、レプリケーター・データベースは通常のデータベースです。認証されたユーザーに関する情報は、レプリケーション文書がデータベースに書き込まれた瞬間にのみ存在する。認証されたユーザーに関する情報は、レプリケーションドキュメントがデータベースに書き込まれた瞬間にのみ存在します。つまり、レプリケーター・データベースの実装は、 _changes が設定された ?include_docs=true フィードを使用するアプリケーションに似ています。

レプリケーションの場合、この実装の違いは、管理者以外のユーザに対して、以下のことを意味します、ユーザ名とロールのサブセットを含む' user_ctx プロパティをレプリケーションドキュメントで定義しなければなりません。をレプリケーションドキュメントで定義しなければなりません。この要件は、レプリケーター・データベースのデフォルト設計文書にある検証関数によって対処されます。この関数は、各文書の更新を検証します。この検証関数は、管理者でないユーザが 'user_ctx プロパティに正しいユーザ名と一致しない username プロパティを設定できないようにします。プロパティに設定できないようにします。同じ原則が役割にも適用されます。

委任された複製文書の例を以下に示します。

{
	"_id": "my_rep",
	"source": {
	  "url": "https://$SERVER.com:5984/foo",
	  "auth": {
	    "basic": {
	      "username": "$USERNAME",
	      "password": "$PASSWORD"
	    }
	  }
	},
	"target": {
	  "url": "https://$ACCOUNT.cloudant.com/bar",
	  "auth": {
	    "basic": {
	      "username": "$USERNAME",
	      "password": "$PASSWORD"
	    }
	  }
	},
	"continuous":  true,
	"user_ctx": {
		"name": "joe",
		"roles": ["erlanger", "researcher"]
	}
}

管理者の場合、user_ctx プロパティーはオプションです。このプロパティーが欠落している場合、値はデフォルトで null という名前のユーザー・コンテキストと、役割の空リストになります。

役割の空リストは、複製中に設計文書がローカル・ターゲットに書き込まれないことを意味します。設計文書をローカル・ターゲットに書き込む場合は、 _admin 役割を持つユーザー・コンテキストを明示的に設定する必要があります。

また、管理者の場合、user_ctx プロパティーを使用して、別のユーザーの複製をトリガーすることもできます。このユーザー・コンテキストは、ローカル・ターゲット・データベース文書の検証関数に渡されます。

user_ctx プロパティーは、ローカル・エンドポイントにのみ適用されます。

要約すると管理者の場合、' user_ctx プロパティはオプションです。通常の (非管理者) ユーザーの場合は必須です。 user_ctx の役割プロパティーが欠落している場合、デフォルトで空のリスト [ ] になります。

複製に対していくつかのパフォーマンス関連オプションを設定できます。これを行うには、複製文書にそれらを組み込みます。

use_bulk_get: 複製ジョブのパフォーマンスを向上させるには、 true に設定します。複製は、ソースから文書をバッチでフェッチします。複製速度の向上により、ソース・アカウントとターゲット・アカウントの容量をより短時間で消費することができ、その結果、それらのアカウントに対する同時非複製要求で 429 件の HTTP エラーが発生することになります。
connection_timeout: 接続の非アクティブの最大期間 (ミリ秒)。接続がこの期間中アイドルの場合は、現行の要求が再試行されます。デフォルト値は 30000 ミリ秒 (30 秒) です。
http_connections: 複製ごとの HTTP 接続の最大数。プッシュ複製の場合、使用される HTTP 接続の有効数は min(worker_processes + 1, http_connections) です。プル複製の場合、使用される接続の有効数は、このパラメーターの値に対応します。デフォルト値は 20 です。
retries_per_request: 要求ごとの再試行の最大数。再試行の前に、レプリケーターは短時間待機してから要求を繰り返します。この期間は、連続する再試行ごとに 2 倍になり、5 分を超えることはありません。最初の再試行までの最小値は 0.25 秒です。デフォルト値は 10 回です。
socket_options: 接続ソケットに渡すオプションのリスト。使えるオプションは inet モジュールのErlang関数 'setopts のドキュメントにあります。デフォルト値は [{keepalive, true},{nodelay, false}] です。
worker_batch_size: ワーカー・プロセスは複製タスクのバッチを実行し、バッチ・サイズはこのパラメーターによって定義されます。このサイズは、_changes フィードの行数に対応します。バッチ・サイズの値を大きくすると、パフォーマンスが向上する場合があります。値が小さいほど、チェックポイント処理の実行頻度が高くなります。デフォルト値は 500 です。
worker_processes: レプリケーターが各複製タスクでソースからターゲット・データベースに文書を転送するために使用するプロセスの数。値を大きくすると、ネットワークおよびディスク入出力のアクティビティーの並列処理が大きくなるため、スループットが向上する可能性がありますが、この改善には、より多くのメモリーと潜在的な CPU 時間が必要になるという代償が伴います。デフォルト値は 4 です。

複製文書のパフォーマンス・オプションを含む例を以下に示します。

{
	"source": {
	  "url": "https://example.com/example-database",
	  "auth": {
	    "basic": {
	      "username": "$ACCOUNT1",
	      "password": "$PASSWORD"
	    }
	  }
	},
	"target": {
	  "url": "https://example.org/example-database",
	  "auth": {
	    "basic": {
	      "username": "$ACCOUNT2",
	      "password": "$PASSWORD"
	    }
	  }
	},
	"connection_timeout": 60000,
	"retries_per_request": 20,
	"http_connections": 30
}

大きな添付ファイルの影響

文書に多数の添付ファイルがあると、複製のパフォーマンスに悪影響を与える可能性があります。

添付ファイルが複製のパフォーマンスに与える影響について詳しくは、パフォーマンスに関する考慮事項を参照してください。

`/_replicate` エンドポイントの回避

エンドポイントではなく _replicator スケジューラー/_replicateを使用してください。

複製中に、停止、タイムアウト、またはアプリケーション異常終了などの問題が発生した場合、_replicator データベース内で定義されている複製はシステムによって自動的に再始動します。ただし、/_replicate エンドポイントに要求を送信して複製を定義した場合、複製要求が持続しないため、問題が発生しても、システムによって複製を再始動することはできません。 _replicator データベースで定義されている複製は、モニターが容易になります。

拡張複製

複製データベースの保守

複製スケジューラー

複製中の認証

フィルターされた複製

複製を使用する競合の除去

指定文書の複製

user_ctx プロパティーおよび委任

パフォーマンス関連のオプション

大きな添付ファイルの影響

/_replicate エンドポイントの回避

`user_ctx` プロパティーおよび委任

`/_replicate` エンドポイントの回避