Overview
Updates the configuration of a data migration or validation project. It uses partial updates: only fields explicitly provided in the request are updated; omitted fields retain their existing values. Corresponds to CommonProjectController.updateProjectConfig.
API details
Constraints
The caller must have an AccessKey to access the multi-cloud API. For information about how to obtain the AccessKey ID and AccessKey Secret, see Manage AccessKeys.
Request path
PUT /api/v2/oms/project/updateConfig
Request parameters
Header
Parameter |
Type |
Required |
Description |
Example value |
|---|---|---|---|---|
| X-Ob-Project-Id | String | Yes | Project ID. | proj-xxxxxxxx |
| X-Ob-Org-Id | String | Yes | Organization ID. | org-xxxxxxxx |
Body
Parameter |
Type |
Required |
Description |
Example value |
|---|---|---|---|---|
| id | String | Yes | Project ID. | project-xxx |
| commonTransferConfig | Object | No | General transfer settings. | |
| fullTransferConfig | Object | No | Full data transfer settings. | |
| incrTransferConfig | Object | No | Incremental data transfer settings. | |
| countVerifyConfig | Object | No | Row count validation settings. | |
| fullVerifyConfig | Object | No | Full validation settings. | |
| incrVerifyConfig | Object | No | Incremental validation settings. |
Response parameters
Field |
Type |
Description |
Example value |
|---|---|---|---|
| success | Boolean | Whether the request succeeded. | true |
| data | Object | Null on success. | null |
| requestId | String | Request ID. | req-xxx-xxx |
| cost | String | Time taken. | 123ms |
Update behavior
Partial updates change only fields explicitly provided in the request. Omitted fields retain their existing values. Exception: the endCheckpoint field in incrVerifyConfig does not distinguish between an omitted value and an explicit null. Whenever the request includes the incrVerifyConfig object, this field is also updated.
Scenario |
Behavior |
|---|---|
| Configuration object is omitted or null | Skips the entire configuration block and preserves the existing configuration. |
| Configuration object is provided | Updates only non-null fields in the object. Other fields retain their existing values. |
| Field in the object is null | Skips the field and preserves its existing value. |
| Transfer rate limit field is set to -1 | Removes the rate limit. |
incrVerifyConfig.endCheckpoint is omitted or null |
Sets the field to null, clearing the existing end position so that validation continues indefinitely. |
Note
incrVerifyConfig.endCheckpoint does not follow the partial update rules. When you provide the incrVerifyConfig object, you must explicitly include the existing end position to preserve it. Updating other fields in incrVerifyConfig, such as reInspectionThreads, while omitting endCheckpoint clears the existing end position and causes validation to continue indefinitely.
Special rules for rate limits
Setting any of the following fields to -1 removes its rate limit:
fullTransferConfig.throttleRps, fullTransferConfig.throttleIOPS, fullTransferConfig.sinkThrottleRps, fullTransferConfig.sinkThrottleIOPS, incrTransferConfig.throttleRps, incrTransferConfig.throttleIOPS
Value |
Behavior |
|---|---|
| null | Skips the update. |
| -1 | Removes the limit. |
| ≥ 0 | Updates the field normally. |
Note
The preceding -1 rule does not apply to fullVerifyConfig.sourceThrottleBps or fullVerifyConfig.sinkThrottleBps. Both fields accept values in the range [1, 1024]. A value of -1 or 0 fails parameter validation. Null skips the field update; it does not remove the rate limit. This update API does not currently support removing full validation rate limits.
Nested object fields
commonTransferConfig (general transfer settings)
Field |
Type |
Description |
|---|---|---|
| sinkStoreFormat | String | Storage type of destination table objects (OB 4.3+). |
| sourceStoreFormat | String | Storage type of source table objects (OB 4.3+). |
fullTransferConfig (full data transfer settings)
Field |
Type |
Description |
|---|---|---|
| writeWorkerNum | Integer | Write concurrency, in the range [1, 512]. |
| readWorkerNum | Integer | Read concurrency, in the range [1, 512]. |
| indexDDLConcurrencyLimit | Integer | Parallelism for a single index DDL statement, in the range [1, 512]. |
| maxConcurrentIndexDDLs | Integer | Maximum number of concurrent index DDL statements, in the range [1, 512]. |
| throttleRps | Integer | RPS limit, in the range [-1, Integer.MAX_VALUE]. Set to -1 to remove the limit. |
| throttleIOPS | Integer | Traffic limit (bytes), in the range [-1, Integer.MAX_VALUE]. Set to -1 to remove the limit. |
| sinkThrottleRps | Integer | Destination RPS limit, in the range [-1, Integer.MAX_VALUE]. Set to -1 to remove the limit. |
| sinkThrottleIOPS | Integer | Destination traffic limit, in the range [-1, Integer.MAX_VALUE]. Set to -1 to remove the limit. |
incrTransferConfig (incremental data transfer settings)
Field |
Type |
Description |
|---|---|---|
| incrSyncThreadCount | Integer | Number of incremental synchronization threads, in the range [1, 512]. |
| recordTypeWhiteList | List | Allowlist of incremental synchronization data types: HEARTBEAT, INSERT, UPDATE, DELETE, BEGIN, COMMIT, ROLLBACK, DDL, and ROW. |
| supportDDLTypes | List | Supported DDL types. Applies when recordTypeWhiteList includes DDL. Valid values: CREATE_TABLE, DROP_TABLE, TRUNCATE_TABLE, RENAME_TABLE, ALTER_TABLE, CREATE_INDEX, and DROP_INDEX. |
| throttleRps | Integer | RPS limit, in the range [-1, Integer.MAX_VALUE]. Set to -1 to remove the limit. |
| throttleIOPS | Integer | Traffic limit (bytes), in the range [-1, Integer.MAX_VALUE]. Set to -1 to remove the limit. |
| incrOnlineDdlConfig | List | Online DDL rules. Valid values: GH_OST, PT_OSC, and ALIYUN_DMS. |
| conflictPolicy | String | Conflict resolution policy: IGNORE (ignore the conflict and preserve the destination data) or OVERWRITE (overwrite the destination data). |
| sourceHeartbeatIntervalSecond | Integer | MySQL source heartbeat interval in seconds, in the range [0, 60]. Set to 0 to disable heartbeats. |
countVerifyConfig (row count validation settings)
Field |
Type |
Description |
|---|---|---|
| concurrencyTablesNumber | Integer | Number of tables to validate concurrently, in the range [1, 100]. |
| queryTimeout | Integer | Query timeout in seconds, in the range [1, 1440]. |
fullVerifyConfig (full validation settings)
Field |
Type |
Description |
|---|---|---|
| mode | String | Validation mode: AUTO (adaptive, default) or IN. |
| sourceThreads | Integer | Number of source threads, in the range [1, 512]. |
| sourceThrottleBps | Integer | Source BPS limit in MiB/s, in the range [1, 1024]. Values of -1 and 0 fail parameter validation. Null skips the field update; it does not remove the rate limit. |
| sinkThreads | Integer | Number of destination threads, in the range [1, 512]. |
| sinkThrottleBps | Integer | Destination BPS limit in MiB/s, in the range [1, 1024]. Values of -1 and 0 fail parameter validation. Null skips the field update; it does not remove the rate limit. |
incrVerifyConfig (incremental validation settings)
Field |
Type |
Description |
|---|---|---|
| startCheckpoint | String | Incremental validation start position (timestamp), in the range [now-7d, now+7d]. |
| endCheckpoint | String | Incremental validation end position. When the request includes the incrVerifyConfig object, omitting this field is equivalent to explicitly setting it to null: both clear the existing end position so that validation continues indefinitely. To preserve the existing end position, explicitly include its value. |
| initialInspectionCooldownTimeout | Integer | Cooldown period for hot data during initial validation, in seconds, in the range [1, 3600]. |
| initialInspectionDelayTimeout | Integer | Time to detect inconsistent data during initial validation, in seconds, in the range [1, 86400]. |
| reInspectionThreads | Integer | Number of revalidation threads, in the range [1, 512]. |
| reInspectionthrottleBps | Integer | Revalidation rate limit in MiB/s, in the range [1, 1024]. |
| reInspectiontolerateTimeout | Integer | Maximum revalidation duration in minutes, in the range [1, 720]. |
Examples
Request example
Example 1: Update full data transfer settings
{
"id": "project-xxx",
"fullTransferConfig": {
"writeWorkerNum": 128,
"readWorkerNum": 128,
"throttleRps": 5000,
"throttleIOPS": 104857600
}
}
Example 2: Update incremental data transfer settings (including DDL types)
{
"id": "project-xxx",
"incrTransferConfig": {
"incrSyncThreadCount": 128,
"recordTypeWhiteList": ["INSERT", "UPDATE", "DELETE", "DDL"],
"supportDDLTypes": ["CREATE_TABLE", "DROP_TABLE", "ALTER_TABLE", "CREATE_INDEX", "DROP_INDEX"],
"throttleRps": 3000,
"conflictPolicy": "OVERWRITE"
}
}
Example 3: Remove rate limits (set to -1)
{
"id": "project-xxx",
"fullTransferConfig": {
"throttleRps": -1,
"throttleIOPS": -1
}
}
Example 4: Update full validation settings
{
"id": "project-xxx",
"fullVerifyConfig": {
"mode": "AUTO",
"sourceThreads": 8,
"sinkThreads": 8,
"sourceThrottleBps": 512
}
}
Example 5: Update the incremental validation end position (continuous validation)
{
"id": "project-xxx",
"incrVerifyConfig": {
"startCheckpoint": "1720000000000",
"endCheckpoint": null
}
}
Example 6: Update incremental validation settings (preserve the existing end position)
Omitting endCheckpoint or explicitly setting it to null clears the existing end position. To change only the number of revalidation threads while preserving the end position, explicitly include the existing end position:
{
"id": "project-xxx",
"incrVerifyConfig": {
"reInspectionThreads": 8,
"endCheckpoint": "1720086400000"
}
}
Response example
{
"success": true,
"data": null,
"requestId": "req-xxx-xxx",
"cost": "123ms"
}