説明
ソースクラスターと宛先クラスター間の同期を開始します。
要件
状態
startエンドポイントを使用するには、 mongosyncがIDLE状態である必要があります。
権限
mongosync 接続文字列で指定されたユーザーには、ソースクラスターと宛先クラスターで必要な権限が必要です。 ユーザーに同期を開始するための適切な権限があることを確認するには、 ユーザー権限を参照してください。
複数のmongosync インスタンス
mongosyncを起動するときに、 cluster0またはcluster1設定の接続文字列で構成済みのmongosyncユーザーを使用していることを確認します。
注意
シャーディングされたクラスター間で同期するように複数のmongosyncインスタンスを構成する場合は、各mongosyncインスタンスに同一の API エンドポイント コマンドを送信する必要があります。
リクエスト
POST /api/v1/start
リクエスト ボディ パラメータ
Parameter | タイプ | 必要性 | 説明 | |||||
|---|---|---|---|---|---|---|---|---|
| string | 必須 | ソースクラスターの名前。 | |||||
| string | 必須 | 宛先クラスターの名前。 | |||||
| string | 任意 | 同期中のインデックスビルドを構成します。 サポートされているオプション:
バージョン 1.3.0 の新機能。 | |||||
| string またはブール値 | 任意 | 重要: このパラメーターはMongoDB6.0 以降を実行中ソースクラスターでのみサポートされています。 サポートされているオプション:
逆同期するには、 デフォルト値は | |||||
| 配列 | 任意 | 同期に含めるデータベースまたはコレクションをフィルタリングします。 複数のデータベースを持つソースクラスターでフィルターを構成する場合、 フィルターを変更して新しいデータベースを追加する場合は、フィルタリングされた同期を最初から再開する必要があります。 詳しくは、「フィルタリングされた同期 」を参照してください。 現在の制限については、「フィルタリングされた同期 」を参照してください。 バージョン 1.1 の新機能。 | |||||
| 配列 | 任意 | 同期から除外するデータベースまたはコレクションをフィルタリングします。 複数のデータベースを持つソースクラスターでフィルターを構成する場合、 フィルターを変更して新しいデータベースを追加する場合は、フィルタリングされた同期を最初から再開する必要があります。 詳しくは、「フィルタリングされた同期 」を参照してください。 現在の制限については、「フィルタリングされた同期 」を参照してください。 バージョン 1.6 の新機能. | |||||
| ドキュメントの配列 | 任意 | データベースとコレクションのリストを自然な順序で宛先クラスターにコピーします。自然な順序とは、過去にデータベースにドキュメントを挿入した順序です。それぞれがデータベースとそのコレクションを表すドキュメントの配列を渡す必要があります。構文の例については、Natural Scan 機能を参照してください。 重要: ランダムな 警告: サイズが 500 GBを超えるコレクションで | |||||
| ブール値 | 任意 | 重要: この機能は現在、パブリックプレビュー段階です。この機能を本番環境で使用するには、このセクションの 「動作と制限」 を確認してください。 デフォルト値は
「 フィルタリングされた同期の制限 」を参照してください。 | |||||
| ブール値 | 任意 |
逆同期するには、 このオプションは、次の構成ではサポートされていません。
重要: 詳細については、「逆のエンドポイント 」を参照してください。 デフォルト値は | |||||
| ドキュメント | 任意 | レプリカセットとシャーディングされたクラスターとの間の同期を構成します。 レプリカセットからシャーディングされたクラスターへの同期にはこのオプションが必要です。 詳細については、「 シャーディング パラメータ 」を参照してください。 バージョン 1.1 の新機能。 | |||||
| ドキュメント | 任意 | ||||||
| ブール | 任意 | 埋め込み検証子を有効にします。 検証ツールは、宛先クラスターでサポートされているコレクションに対して一連の検証チェックを実行し、移行が成功したことを確認します。 検証子でエラーが検出されない場合、 検証子はデフォルトで有効になっています。 警告 : 検証子は、すべてのコレクションまたはデータをチェックするわけではありません。詳細については、「 埋め込み検証子 」を参照してください。 バージョン 1.9 の新機能。 |
シャーディング パラメータ
バージョン 1.1 の新機能。
レプリカセットからシャーディングされたクラスターに同期するには、 shardingオプションを設定して、宛先クラスターのコレクションをシャードします。
mongosync レプリカセットからシャーディングされたクラスターに同期するときにshardingオプションが設定されていない場合、 はエラーをスローします。 また、 shardingオプションが他の構成で設定されている場合、 mongosyncではエラーがスローされます。
shardingオプションには次のパラメーターがあります。
Parameter | タイプ | 説明 |
|---|---|---|
| ブール値 | 任意。 同期がシャードキーのサポートインデックスを作成するかどうかを設定します（存在しない場合）。 デフォルトは の値が このパラメータを 詳細と制限については、「 インデックスのサポート 」を参照してください。 |
| ドキュメントの配列 | 必須。 同期中にシャードするコレクションの名前空間とキーを設定します。 この配列に含まれていないコレクションは、宛先クラスター上のシャーディングされていないコレクションに同期されます。 空の配列に設定されている場合、コレクションはシャーディングされません。 |
shardingEntries.collection | string | コレクションをシャードに設定します。 |
shardingEntries.database | string | コレクションのデータベースをシャードに設定します。 |
shardingEntries.shardCollection | ドキュメント | 宛先クラスターで生成するシャードキーを設定します。 |
shardingEntries.shardCollection.key | 配列 | シャードキーに使用するフィールドを設定します。 詳しくは、「シャードキー 」を参照してください。 |
応答
フィールド | タイプ | 説明 |
|---|---|---|
| ブール値 | リクエストが成功した場合、この値は |
| string | エラーが発生した場合、 はエラーの名前を示します。 このフィールドは、 |
| string | 発生したエラーの詳細な説明。 このフィールドは、 |
例
同期ジョブの開始
次の例では、ソースクラスターcluster0 と宛先クラスター cluster1 の間で同期ジョブを開始します。
リクエスト:
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1" } '
応答:
{"success":true}
可用性同期ジョブの開始
次の例では、ソースクラスターcluster0 と宛先クラスター cluster1 の間で同期ジョブを開始します。
reversibleとenableUserWriteBlockingフィールドでは同期を元に戻すことができます。 同期方向を逆にするには、「逆 」を参照してください。
リクエスト:
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1", "reversible": true, "enableUserWriteBlocking": "sourceAndDestination" } '
応答:
{"success":true}
フィルタリングされた同期ジョブの開始
次の例では、ソースクラスターcluster0 と宛先クラスター cluster1 の間で同期ジョブを開始します。
cluster0 には、 sales 、 marketing 、およびengineeringデータベースが含まれています。
salesデータベースには、 EMEA 、 APAC 、 AMERのコレクションが含まれています。
この例のincludeNamespaces配列は、 salesとmarketingの 2 つのデータベースに対するフィルターを定義しています。
salesEMEAデータベースは、APAC コレクションと コレクションでもフィルタリングします。
"includeNamespaces" : [ { "database" : "sales", "collections": [ "EMEA", "APAC" ] }, { "database" : "marketing" } ]
/startこのフィルターを使用して API を呼び出すと、mongosync は次のようになります。
marketingデータベース内のすべてのコレクションを同期しますengineeringデータベースをフィルタリング除外しますEMEAAPACデータベースからsalesコレクションと コレクションを同期しますAMERコレクションをフィルタリングで除外します
includeNamespacesオプションはフィルターを作成します。 同期をフィルタリングするには、「 フィルタリングされた同期」を参照してください。
リクエスト:
curl -X POST "http://localhost:27182/api/v1/start" --data ' { "source": "cluster0", "destination": "cluster1", "includeNamespaces": [ { "database": "sales", "collectionsRegex": { "pattern": "^accounts_.+$", "options": "i" } }, { "database": "marketing" } ] } '
応答:
{"success":true}
レプリカセットからシャーシャードクラスタへの同期の開始
次の例では、ソースレプリカセットcluster0 と宛先のシャーディングされたクラスターcluster1 の間で同期ジョブを開始します。この例の key 配列は、シャードキー{"location": 1, "region": 1 } を定義しています。
リクエスト:
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1", "sharding": { "createSupportingIndexes": true, "shardingEntries": [ { "database": "accounts", "collection": "us_east", "shardCollection": { "key": [ { "location": 1 }, { "region": 1 } ] } } ] } } '
応答:
{"success":true}
検証子を無効にして を開始する
1.9 以降では、移行を開始すると 埋め込み検証子がデフォルトで実行されます。 無効にする必要がある場合は、verification.enabled を false に設定します。
リクエスト:
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1", "verification": { "enabled": false } } '
応答:
{"success":true}
アプリケーションの負荷を宛先クラスターに転送する前に、移行が成功したことを確認する必要があります。 何らかの理由で検証子を無効にする必要がある場合は、別の方法を使用して同期を検証してください。
動作
埋め込み検証子
1.9 以降、mongosync は、ソースクラスターから宛先へのデータ転送が成功したかどうかを判断するための埋め込み検証子を提供します。
有効にすると、検証ツールは宛先クラスターに対して一連の検証チェックを実行します。 これらのチェックのいずれかでエラーが返された場合、検証子は移行を失敗します 。 すべてのチェックが成功すると、mongosync は COMMITTED 状態に移行します。
検証子を無効にするには、「 検証子を無効にして起動する 」を参照してください。
ソースクラスターまたは宛先クラスターでサポートされていない検証チェックを有効にした場合、またはメモリが不足している場合、/start エンドポイントはエラーを返します。
状態
startリクエストが成功すると、 mongosyncはRUNNING状態になります。
レプリカセットのシャーディング
レプリカセットからシャーディングされたクラスターへの同期にはshardingオプションが必要です。 このオプションは、 mongosyncがコレクションをシャーディングする方法を構成します。
sharding.shardingEntries配列は、シャーディングするコレクションを指定します。 この配列にリストされていないコレクションは、シャーディングされていないコレクションとして複製されます。
サポートインデックス
mongosync は、ソースクラスターから宛先クラスターにインデックスを同期します。 レプリカセットからシャーディングされたクラスターに同期する場合、mongosync はシャードキー をサポートするために追加のインデックスが必要になる場合があります。このインデックスはソースクラスターに存在しない場合があります。
mongosync は、同期中にシャーディングされたコレクション用のサポート インデックスを作成できます。 そのためには、 sharding.createSupportingIndexesオプションを設定します。
sharding.createSupportingIndexesがfalse （デフォルト）の場合
sharding.shardingEntriesオプションに指定する各シャードキーには、ソースクラスターに既存のインデックスが必要です。コレクションで他の照合を使用する場合、シャードキーに使用されるインデックスの 1 つは単純照合が必要です。
シャードキーで一意のインデックスを使用するには、ソースクラスターでインデックスを作成するときに、その一意性を指定する必要があります。
宛先クラスターのリクエストされたシャードキーと互換性のないソースクラスターのユニークインデックス（宛先のプレフィックスとして、リクエストされたシャードキーを含まないソースクラスターのユニークインデックスなど）では、
mongosyncが失敗する可能性があります。の値が
buildIndexes"afterDataCopy"または"excludeHashedAfterCopy"falseで、シャーディングされたクラスターへの移行中に createSupportingIndexes を に設定すると、mongosyncはシャードキーをサポートするためのダミーのインデックスを作成します。mongosynccommitが呼び出された後に、 はこのダミーインデックスを削除しようとします。シャードキーをサポートするユーザーが構築したインデックスが存在しない場合、ダミーインデックスの削除は失敗します。ユーザーは、移行が完了した後にダミーインデックスを削除し、独自のインデックスを作成することをお勧めします。
sharding.createSupportingIndexesがtrueの場合:
サポートするインデックスがソースクラスターに存在する場合、
mongosyncはインデックスを宛先クラスターに同期し、シャードキーとして使用します。サポート インデックスが存在しない場合、
mongosyncは宛先クラスターにそれらを作成します。
sharding.createSupportingIndexesオプションは、すべてのシャーディングされたコレクションに影響します。
同期中の名前変更
レプリカセットからシャーディングされたクラスターに同期されたときにsharding.shardingEntries配列にリストされているコレクションは、宛先クラスターでシャーディングされたコレクションになります。
startを呼び出した後、 mongosyncがコレクションのコピーを開始する前に、ソースクラスターでコレクションの名前を変更すると（ renameCollectionコマンドなど）、宛先でコレクションがシャーディングできなくなる可能性があります。
注意
レプリカセットからシャーディングされたクラスターへの同期中に別のデータベースを使用するようにコレクションの名前を変更することはサポートされていません。
コレクションの名前を変更しても安全かどうかを確認するには、 progressエンドポイントを呼び出し、返されたドキュメントのcollectionCopy.estimatedCopiedBytesフィールドの値を確認します。
値が 0 の場合、
mongosyncによるコレクションのコピーが開始されていないことを示します。この時点でコレクションの名前を変更すると、ソースで名前変更が有効になる前にコピーへの移行が行われる可能性があるため、宛先クラスターでシャーディングされないコレクションが作成される可能性があります。
値が 0 より大きい場合は、
mongosyncがコピーを開始したことを示します。 この時点からコレクションの名前を変更しても、クラッシュが発生した場合でも、宛先クラスターでのシャーディングはブロックされません。
必要なインデックス
buildIndexesオプションをneverに設定して/startを呼び出すと、 mongosyncは不要なインデックスの構築をスキップします。
常に構築されるインデックスには、次のものが含まれます。
mongosyncは、コピーしたすべてのコレクションの_idフィールドにインデックスを構築します。mongosyncは、宛先クラスターでシャードキーをサポートするためのインデックスがない各シャーディングされたコレクションに対してダミーのインデックスを構築します。buildIndexesがneverに設定されている場合、mongosyncはコミット後にこのインデックスを保持します。
エンドポイント保護
mongosync は、 startエンドポイントを保護しません。 ただし、デフォルトでは、API は localhost のみにバインドされ、他のソースからの呼び出しは受け入れません。 さらに、 start呼び出しでは接続認証情報やユーザー データは公開されません。
自然なスキャン機能
copyInNaturalOrder オプションを使用して /start を呼び出す場合は、次の例のようなドキュメントを使用してデータベースとコレクションを指定する必要があります。
リクエスト:
curl -X POST "http://localhost:27182/api/v1/start" --data ' { "source": "cluster0", "destination": "cluster1", "copyInNaturalOrder": [ { "database": "sales", "collections": [ "accounts", "orders", ] }, { "database": "marketing", "collections": [ "offers", ] }, ] }'
応答:
{"success":true}
警告: ランダム以外の フィールドを持つコレクションの移行を有効にする場合、_id を指定するとコレクションコピー copyInNaturalOrderフェーズが完了するまでの時間が長くなる可能性があります。
copyInNaturalOrder を使用して、複数のデータベース内のすべてのコレクションを自然な順序でコピーできます。これは次の例のようになります。
リクエスト:
curl -X POST "http://localhost:27182/api/v1/start" --data ' { "source": "cluster0", "destination": "cluster1", "copyInNaturalOrder": [ { "database": "sales", }, { "database": "marketing", }, ] }'
応答:
{"success":true}
copyInNaturalOrder を使用して、すべてのデータベースとそのコレクションを自然な順序でコピーできます。
リクエスト:
curl -X POST "http://localhost:27182/api/v1/start" --data ' { "source": "cluster0", "destination": "cluster1", "copyInNaturalOrder": [ { "database": ".", }, ] }'
応答:
{"success":true}