Modifying a Policy

Function

This API is used to modify a policy.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

PUT /v3/{project_id}/policies/{policy_id}

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
policy_id	Yes	String	Policy ID. Default value: N/A For details about how to obtain the policy ID, see Obtaining a Policy ID.
project_id	Yes	String	Project ID. Default value: N/A For details about how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. You can obtain it by calling the IAM API for obtaining a user token. The user token is the value of X-Subject-Token in the response header. Default value: N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
policy	Yes	PolicyUpdate object	Request body for modifying a policy

**Table 4** PolicyUpdate
Parameter	Mandatory	Type	Description
enabled	No	Boolean	Whether to enable the policy. The default value is true. The value can be: true: The policy is enabled, and tasks are triggered periodically. false: The policy is disabled, and tasks are not triggered periodically.
name	No	String	Policy name. The value consists of 1 to 64 characters, including only letters, digits, underscores (_), and hyphens (-). Default value: N/A
operation_definition	No	PolicyoODCreate object	Parameter for scheduling the policy.
trigger	No	PolicyTriggerUpdateReq object	Time rule for the policy execution

**Table 5** PolicyoODCreate
Parameter	Mandatory	Type	Description
day_backups	No	Integer	Number of daily backups retained, which is not affected by the allowed maximum number of retained backups. The value ranges from 0 to 100. Default value: N/A If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both specified.
destination_project_id	No	String	Project ID of the destination region, which is mandatory for cross-region replication. Default value: N/A For details about how to obtain the project ID, see Obtaining a Project ID.
destination_region	No	String	Destination region, which is mandatory for cross-region replication. The destination region cannot be the same as the current region. The value contains a maximum of 255 characters, including only letters, digits, underscores (_), and hyphens (-). Default value: N/A For details about how to obtain the region ID, see Querying Regions and Endpoints.
enable_acceleration	No	Boolean	Whether to enable acceleration to shorten the cross-region replication time. If this parameter is not set, the acceleration function is disabled. If enabled, the acceleration function is additionally charged. true: The acceleration function is enabled. false: The acceleration function is disabled.
max_backups	No	Integer	Maximum number of backups that can be automatically created for a resource. The value can be -1 or in the range of 1 to 99999. Default value: N/A If the value is set to -1, backups will not be cleared when they reach the quantity limit. If this parameter and retention_duration_days are both left unspecified, backups will be retained permanently. This parameter and retention_duration_days cannot be both specified.
month_backups	No	Integer	Number of monthly backups retained, which is not affected by the allowed maximum number of retained backups. The value ranges from 0 to 100. Default value: N/A If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both specified.
retention_duration_days	No	Integer	Backup retention period, in days. The maximum value is 99999. Default value: N/A -1 indicates that the backups will not be cleared based on the retention duration. If this parameter and max_backups are both left blank, the backups will be retained permanently. This parameter cannot be applied together with max_backups, day_backups, week_backups, month_backups, or year_backups.
timezone	No	String	Time zone where the user is located, for example, UTC+08:00. Default value: N/A If any of the yearly, monthly, weekly, and daily backup parameters is selected, this parameter cannot be left blank.
week_backups	No	Integer	Number of weekly backups retained, which is not affected by the allowed maximum number of retained backups. The value ranges from 0 to 100. Default value: N/A If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both specified.
year_backups	No	Integer	Number of yearly backups retained, which is not affected by the allowed maximum number of retained backups. The value ranges from 0 to 100. Default value: N/A If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both specified.
full_backup_interval	No	Integer	Defines how often a full backup is performed. If -1 is specified, full backup will not be performed. Range: [-1, 100]; Default value: N/A
cross_account_urn	No	String	The replication vault ID associated with the cross-account replication policy.
advanced_retention_rules	No	PolicyAdvancedRetentionRules object	Advanced time-based retention settings.

**Table 6** PolicyAdvancedRetentionRules
Parameter	Mandatory	Type	Description
weekly_retention_rules	No	PolicyWeeklyRetentionRules object	Weekly retention rule.
monthly_retention_rules	No	PolicyMonthlyRetentionRules object	Monthly retention rule.
yearly_retention_rules	No	PolicyYearlyRetentionRules object	Yearly retention rule.

**Table 7** PolicyWeeklyRetentionRules
Parameter	Mandatory	Type	Description
days_of_week	No	Array of strings	Sets specific days in each week to retain weekly backups.
retention_duration_periods	No	Integer	Sets the retention period of weekly backups, in the unit of weeks. The value can be any integer from 1 to 5200, or -1. Value -1 means that weekly retention rule is disabled.

**Table 8** PolicyMonthlyRetentionRules
Parameter	Mandatory	Type	Description
retention_type	No	String	Monthly retention rule type.
retention_weeks	No	Array of strings	Sets the weeks in each month to retain monthly backups. This parameter must be used together with days_of_week and can only be set when retention_type is Weekly.
days_of_week	No	Array of strings	Sets specific days in each week to retain monthly backups. This parameter must be used together with retention_weeks and can only be set when retention_type is Weekly.
days_of_month	No	Array of integers	Sets specific days in each month to retain monthly backups. This parameter can only be set when retention_type is Monthly. The value can be any integer from 1 to 28, or -1. Value -1 indicates the last day of each month.
retention_duration_periods	No	Integer	Sets the retention period of monthly backups, in the unit of months. The value can be any integer from 1 to 1200, or -1. Value -1 means that monthly retention rule is disabled.

**Table 9** PolicyYearlyRetentionRules
Parameter	Mandatory	Type	Description
retention_type	No	String	Yearly retention rule type.
retention_months	No	Array of strings	Sets specific months to retain yearly backups. If retention_type is set to Weekly, this parameter must be set together with retention_weeks and days_of_week. If retention_type is set to Monthly, this parameter must be set together with days_of_month.
retention_weeks	No	Array of strings	Sets the weeks in the selected months to retain yearly backups. This parameter must be used together with retention_months and days_of_week and can only be set when retention_type is Weekly.
days_of_month	No	Array of integers	Sets specific days for the selected months to retain yearly backups. This parameter can only be set when retention_type is Monthly. The value can be any integer from 1 to 28, or -1. Value -1 indicates the last day of each month. This parameter must be used together with retention_months.
days_of_week	No	Array of strings	Sets specific days in specific weeks of specific months to retain yearly backups. This parameter must be used together with retention_weeks and retention_months and can only be set when retention_type is Weekly.
retention_duration_periods	No	Integer	Sets the retention period of yearly backups, in the unit of years. The value can be any integer from 1 to 100, or -1. Value -1 means that yearly retention rule is disabled.

**Table 10** PolicyTriggerUpdateReq
Parameter	Mandatory	Type	Description
properties	Yes	PolicyTriggerPropertiesUpdateReq object	Policy scheduler update attributes.

**Table 11** PolicyTriggerPropertiesUpdateReq
Parameter	Mandatory	Type	Description
pattern	Yes	Array of strings	Scheduling rule. A maximum of 24 rules can be configured. The rule complies with iCalendar RFC 2445, but it supports only parameters FREQ, BYDAY, BYHOUR, BYMINUTE, and INTERVAL. FREQ can be set only to WEEKLY or DAILY. BYDAY can be set to MO, TU, WE, TH, FR, SA, and SU (seven days of a week). BYHOUR ranges from 0 to 23 hours. BYMINUTE ranges from 0 to 59 minutes. The scheduling interval must not be less than 1 hour. A maximum of 24 time points can be configured in a day. For example, if the scheduling time is 14:00 (UTC time) from Monday to Sunday, set the scheduling rule as follows: FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU;BYHOUR=14;BYMINUTE=00. For example, if the local time zone is UTC+8 and scheduling occurs daily at 14:00, the value of FREQ should reflect the equivalent UTC time, which is 14 minus 8. The corresponding rule is FREQ=DAILY;INTERVAL=1;BYHOUR=6;BYMINUTE=00. Default value: N/A
start_window_minutes	No	Integer	Start window size. The value can be any integer from 60 to 480, or null. Value null means that start window is disabled.

Response Parameters

Status code: 200

**Table 12** Response body parameters
Parameter	Type	Description
policy	Policy object	Response to the request for creating a policy

**Table 13** Policy
Parameter	Type	Description
enabled	Boolean	Whether the policy is enabled. The value can be: true: The policy is enabled. false: The policy is disabled.
id	String	Policy ID. Range: N/A
name	String	Policy name. The value consists of 1 to 64 characters, including only letters, digits, underscores (_), and hyphens (-).
operation_definition	PolicyoODCreate object	Policy attributes.
operation_type	String	Protection type. The value can be backup or replication.
trigger	PolicyTriggerResp object	Time scheduling rule for the policy
associated_vaults	Array of PolicyAssociateVault objects	Associated vault
policy_type	String	Policy type. The value can be: custom_policy: common-user policy organization_policy_v1: organization policy of the old version organization_policy_v2: organization policy of the new version organization_policy_removed: new organization policy associated with a vault for a user that has left the organization. (The policy is not automatically disassociated from the vault, and cannot be associated with a new vault.)

**Table 14** PolicyoODCreate
Parameter	Type	Description
day_backups	Integer	Number of daily backups retained, which is not affected by the allowed maximum number of retained backups. The value ranges from 0 to 100. Default value: N/A If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both specified.
destination_project_id	String	Project ID of the destination region, which is mandatory for cross-region replication. Default value: N/A For details about how to obtain the project ID, see Obtaining a Project ID.
destination_region	String	Destination region, which is mandatory for cross-region replication. The destination region cannot be the same as the current region. The value contains a maximum of 255 characters, including only letters, digits, underscores (_), and hyphens (-). Default value: N/A For details about how to obtain the region ID, see Querying Regions and Endpoints.
enable_acceleration	Boolean	Whether to enable acceleration to shorten the cross-region replication time. If this parameter is not set, the acceleration function is disabled. If enabled, the acceleration function is additionally charged. true: The acceleration function is enabled. false: The acceleration function is disabled.
max_backups	Integer	Maximum number of backups that can be automatically created for a resource. The value can be -1 or in the range of 1 to 99999. Default value: N/A If the value is set to -1, backups will not be cleared when they reach the quantity limit. If this parameter and retention_duration_days are both left unspecified, backups will be retained permanently. This parameter and retention_duration_days cannot be both specified.
month_backups	Integer	Number of monthly backups retained, which is not affected by the allowed maximum number of retained backups. The value ranges from 0 to 100. Default value: N/A If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both specified.
retention_duration_days	Integer	Backup retention period, in days. The maximum value is 99999. Default value: N/A -1 indicates that the backups will not be cleared based on the retention duration. If this parameter and max_backups are both left blank, the backups will be retained permanently. This parameter cannot be applied together with max_backups, day_backups, week_backups, month_backups, or year_backups.
timezone	String	Time zone where the user is located, for example, UTC+08:00. Default value: N/A If any of the yearly, monthly, weekly, and daily backup parameters is selected, this parameter cannot be left blank.
week_backups	Integer	Number of weekly backups retained, which is not affected by the allowed maximum number of retained backups. The value ranges from 0 to 100. Default value: N/A If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both specified.
year_backups	Integer	Number of yearly backups retained, which is not affected by the allowed maximum number of retained backups. The value ranges from 0 to 100. Default value: N/A If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both specified.
full_backup_interval	Integer	Defines how often a full backup is performed. If -1 is specified, full backup will not be performed. Range: [-1, 100]; Default value: N/A
cross_account_urn	String	The replication vault ID associated with the cross-account replication policy.
advanced_retention_rules	PolicyAdvancedRetentionRules object	Advanced time-based retention settings.

**Table 15** PolicyAdvancedRetentionRules
Parameter	Type	Description
weekly_retention_rules	PolicyWeeklyRetentionRules object	Weekly retention rule.
monthly_retention_rules	PolicyMonthlyRetentionRules object	Monthly retention rule.
yearly_retention_rules	PolicyYearlyRetentionRules object	Yearly retention rule.

**Table 16** PolicyWeeklyRetentionRules
Parameter	Type	Description
days_of_week	Array of strings	Sets specific days in each week to retain weekly backups.
retention_duration_periods	Integer	Sets the retention period of weekly backups, in the unit of weeks. The value can be any integer from 1 to 5200, or -1. Value -1 means that weekly retention rule is disabled.

**Table 17** PolicyMonthlyRetentionRules
Parameter	Type	Description
retention_type	String	Monthly retention rule type.
retention_weeks	Array of strings	Sets the weeks in each month to retain monthly backups. This parameter must be used together with days_of_week and can only be set when retention_type is Weekly.
days_of_week	Array of strings	Sets specific days in each week to retain monthly backups. This parameter must be used together with retention_weeks and can only be set when retention_type is Weekly.
days_of_month	Array of integers	Sets specific days in each month to retain monthly backups. This parameter can only be set when retention_type is Monthly. The value can be any integer from 1 to 28, or -1. Value -1 indicates the last day of each month.
retention_duration_periods	Integer	Sets the retention period of monthly backups, in the unit of months. The value can be any integer from 1 to 1200, or -1. Value -1 means that monthly retention rule is disabled.

**Table 18** PolicyYearlyRetentionRules
Parameter	Type	Description
retention_type	String	Yearly retention rule type.
retention_months	Array of strings	Sets specific months to retain yearly backups. If retention_type is set to Weekly, this parameter must be set together with retention_weeks and days_of_week. If retention_type is set to Monthly, this parameter must be set together with days_of_month.
retention_weeks	Array of strings	Sets the weeks in the selected months to retain yearly backups. This parameter must be used together with retention_months and days_of_week and can only be set when retention_type is Weekly.
days_of_month	Array of integers	Sets specific days for the selected months to retain yearly backups. This parameter can only be set when retention_type is Monthly. The value can be any integer from 1 to 28, or -1. Value -1 indicates the last day of each month. This parameter must be used together with retention_months.
days_of_week	Array of strings	Sets specific days in specific weeks of specific months to retain yearly backups. This parameter must be used together with retention_weeks and retention_months and can only be set when retention_type is Weekly.
retention_duration_periods	Integer	Sets the retention period of yearly backups, in the unit of years. The value can be any integer from 1 to 100, or -1. Value -1 means that yearly retention rule is disabled.

**Table 19** PolicyTriggerResp
Parameter	Type	Description
id	String	Scheduler ID. Range: N/A
name	String	Scheduler name. Range: N/A
properties	PolicyTriggerPropertiesResp object	Policy scheduler attributes
type	String	Scheduler type. Currently, only time (periodic scheduling) is supported.

**Table 20** PolicyTriggerPropertiesResp
Parameter	Type	Description
pattern	Array of strings	Scheduling rule. A maximum of 24 rules can be configured. The scheduling rule complies with iCalendar RFC 2445, but it supports only parameters FREQ, BYDAY, BYHOUR, BYMINUTE, and INTERVAL. FREQ can be set only to WEEKLY or DAILY. BYDAY* can be set to MO, TU, WE, TH, FR, SA, or SU (seven days of a week). BYHOUR ranges from 0 to 23 hours. BYMINUTE ranges from 0 minutes to 59 minutes. The scheduling interval must not be less than 1 hour. A maximum of 24 time points are allowed in a day. For example, if the scheduling time is 14:00 (UTC time) from Monday to Sunday, set the scheduling rule as follows: FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU;BYHOUR=14;BYMINUTE=00. For example, if the time of an area is UTC+8. The scheduling is performed at 14:00 every day in this area. The value of FREQ is the same as that of 14:00 minus 8. The rule is as follows: FREQ=DAILY;INTERVAL=1;BYHOUR=6;BYMINUTE=00.
start_time	String	Scheduler start time, for example, 2020-01-08 09:59:49.
start_window_minutes	Integer	Start window size.

**Table 21** PolicyAssociateVault
Parameter	Type	Description
destination_vault_id	String	ID of the associated remote vault. For details, see Obtaining a Vault ID, where project_id must be set to the project ID of the destination region.
vault_id	String	Vault ID. For details about how to obtain the vault ID, see Obtaining a Vault ID.

Example Requests

Modify the backup policy to run automatically at 14:00 every day, with each backup retained for one day.

PUT https://{endpoint}/v3/f841e01fd2b14e7fa41b6ae7aa6b0594/policies/cbb3ce6f-3332-4e7c-b98e-77290d8471ff

{
  "policy" : {
    "enabled" : true,
    "name" : "policy001",
    "operation_definition" : {
      "day_backups" : 0,
      "month_backups" : 0,
      "max_backups" : 1,
      "timezone" : "UTC+08:00",
      "week_backups" : 0,
      "year_backups" : 0
    },
    "trigger" : {
      "properties" : {
        "pattern" : [ "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU;BYHOUR=14;BYMINUTE=00" ]
      }
    }
  }
}

Example Responses

Status code: 200

{
  "policy" : {
    "name" : "policy001",
    "associated_vaults" : [ ],
    "enabled" : true,
    "trigger" : {
      "properties" : {
        "pattern" : [ "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU;BYHOUR=14;BYMINUTE=00" ],
        "start_time" : "2019-05-08T06:57:05.000+00:00"
      },
      "type" : "time",
      "id" : "d67269a6-5369-42d7-8150-5254bd446328",
      "name" : "default"
    },
    "operation_definition" : {
      "max_backups" : 1,
      "year_backups" : 0,
      "day_backups" : 0,
      "month_backups" : 0,
      "week_backups" : 0,
      "timezone" : "UTC+08:00"
    },
    "operation_type" : "backup",
    "id" : "cbb3ce6f-3332-4e7c-b98e-77290d8471ff",
    "policy_type" : "custom_policy"
  }
}