Creating a Policy¶

Function¶

This API is used to create a backup policy.

URI¶

POST /v3/{project_id}/policies

**Table 1** Path Parameters¶
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID

Request Parameters¶

**Table 2** Request header parameters¶
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

**Table 3** Request body parameters¶
Parameter	Mandatory	Type	Description
policy	Yes	PolicyCreate object	Request body for creating a policy

**Table 4** PolicyCreate¶
Parameter	Mandatory	Type	Description
enabled	No	Boolean	Whether to enable the policy Default: true
name	Yes	String	Specifies the policy name. The value consists of 1 to 64 characters and can contain only letters, digits, underscores (_), and hyphens (-). Minimum: 1 Maximum: 64
operation_definition	Yes	PolicyoODCreate object	Scheduling parameter
operation_type	Yes	String	Protection type, which can be backup or replication
trigger	Yes	PolicyTriggerReq object	Time rule for the policy execution

**Table 5** PolicyoODCreate¶
Parameter	Mandatory	Type	Description
day_backups	No	Integer	Maximum number of daily backups that can be retained. The latest backup of each day is saved in the long term. This parameter and max_backups will both be applied. The value ranges from 0 to 100. If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both applied. Minimum: 0 Maximum: 100
destination_project_id	No	String	ID of the replication destination project, which is mandatory for cross-region replication
destination_region	No	String	Replication destination region, which is mandatory for cross-region replication. The destination region cannot be the same as the current region. The value contains 0 to 255 characters, including only letters, digits, underscores (_), and hyphens (-).
max_backups	No	Integer	Maximum number of backups that can be automatically created for an object. The value can be -1 or 1-99999. If the value is set to -1, backups will not be cleared by the quantity of backups. If this parameter and retention_duration_days are both left blank, backups will be retained permanently. This field and retention_duration_days cannot be both set. Minimum: 1 Maximum: 99999 Default: -1
month_backups	No	Integer	Maximum number of monthly backups that can be retained. The latest backup of each month is saved in the long term. This parameter and max_backups will both be applied. The value ranges from 0 to 100. If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both applied. Minimum: 0 Maximum: 100
retention_duration_days	No	Integer	Duration of retaining a backup, in days. The maximum value is 99999. If the value is set to -1, backups will not be cleared by retention duration. If this parameter and max_backups are left blank at the same time, the backups will be retained permanently. This parameter cannot be applied together with max_backups, day_backups, week_backups, month_backups, and year_backups. Minimum: 1 Maximum: 99999 Default: -1
timezone	No	String	Time zone where the user is located. The format is UTC+01:00. If any of the parameters of yearly, monthly, weekly, or daily backup is selected, this parameter cannot be left empty.
week_backups	No	Integer	Maximum number of weekly backups that can be retained. The latest backup of each week is saved in the long term. This parameter and max_backups will both be applied. The value ranges from 0 to 100. If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both applied.
year_backups	No	Integer	Maximum number of yearly backups that can be retained. The latest backup of each year is saved in the long term. This parameter and max_backups will both be applied. The value ranges from 0 to 100. If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both applied. Minimum: 0 Maximum: 100

**Table 6** PolicyTriggerReq¶
Parameter	Mandatory	Type	Description
properties	Yes	PolicyTriggerPropertiesReq object	Scheduler attributes

**Table 7** PolicyTriggerPropertiesReq¶
Parameter	Mandatory	Type	Description
pattern	Yes	Array of strings	Scheduling rule of the scheduler. A maximum of 24 rules can be configured. The scheduling rule complies with iCalendar RFC 2445, but it supports only the FREQ, BYDAY, BYHOUR, BYMINUTE, and INTERVAL parameters. 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 cannot 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) from Monday to Sunday, set the scheduling rule as follows: FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU;BYHOUR=14;BYMINUTE=00. If the scheduling time is 14:00 (UTC+8) every day, set the scheduling rule as follows: FREQ=DAILY;INTERVAL=1;BYHOUR=6;BYMINUTE=00

Response Parameters¶

Status code: 200

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

**Table 9** Policy¶
Parameter	Type	Description
enabled	Boolean	Whether the policy is enabled
id	String	Policy ID
name	String	Policy Name
operation_definition	PolicyoODCreate object	Policy attributes
operation_type	String	Protection type, which can be backup or replication Enumeration values: backup replication
trigger	PolicyTriggerResp object	Time scheduling rule for the policy
associated_vaults	Array of PolicyAssociateVault objects	Associated vault

**Table 10** PolicyoODCreate¶
Parameter	Type	Description
day_backups	Integer	Maximum number of daily backups that can be retained. The latest backup of each day is saved in the long term. This parameter and max_backups will both be applied. The value ranges from 0 to 100. If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both applied. Minimum: 0 Maximum: 100
destination_project_id	String	ID of the replication destination project, which is mandatory for cross-region replication
destination_region	String	Replication destination region, which is mandatory for cross-region replication. The destination region cannot be the same as the current region. The value contains 0 to 255 characters, including only letters, digits, underscores (_), and hyphens (-).
max_backups	Integer	Maximum number of backups that can be automatically created for an object. The value can be -1 or 1-99999. If the value is set to -1, backups will not be cleared by the quantity of backups. If this parameter and retention_duration_days are both left blank, backups will be retained permanently. This field and retention_duration_days cannot be both set. Minimum: 1 Maximum: 99999 Default: -1
month_backups	Integer	Maximum number of monthly backups that can be retained. The latest backup of each month is saved in the long term. This parameter and max_backups will both be applied. The value ranges from 0 to 100. If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both applied. Minimum: 0 Maximum: 100
retention_duration_days	Integer	Duration of retaining a backup, in days. The maximum value is 99999. If the value is set to -1, backups will not be cleared by retention duration. If this parameter and max_backups are left blank at the same time, the backups will be retained permanently. This parameter cannot be applied together with max_backups, day_backups, week_backups, month_backups, and year_backups. Minimum: 1 Maximum: 99999 Default: -1
timezone	String	Time zone where the user is located. The format is UTC+01:00. If any of the parameters of yearly, monthly, weekly, or daily backup is selected, this parameter cannot be left empty.
week_backups	Integer	Maximum number of weekly backups that can be retained. The latest backup of each week is saved in the long term. This parameter and max_backups will both be applied. The value ranges from 0 to 100. If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both applied.
year_backups	Integer	Maximum number of yearly backups that can be retained. The latest backup of each year is saved in the long term. This parameter and max_backups will both be applied. The value ranges from 0 to 100. If this parameter is configured, timezone is mandatory. This parameter and retention_duration_days cannot be both applied. Minimum: 0 Maximum: 100

**Table 11** PolicyTriggerResp¶
Parameter	Type	Description
id	String	Scheduler ID
name	String	Scheduler name
properties	PolicyTriggerPropertiesResp object	Scheduler attributes
type	String	Scheduler type. Currently, only time (periodic scheduling) is supported. Enumeration values: time

**Table 12** PolicyTriggerPropertiesResp¶
Parameter	Type	Description
pattern	Array of strings	Scheduling rule of the scheduler. A maximum of 24 rules can be configured. The scheduling rule complies with iCalendar RFC 2445, but it supports only the FREQ, BYDAY, BYHOUR, BYMINUTE, and INTERVAL parameters. 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 cannot 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) from Monday to Sunday, set the scheduling rule as follows: FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU;BYHOUR=14;BYMINUTE=00. If the scheduling time is 14:00 (UTC+8) every day, set the scheduling rule as follows: FREQ=DAILY;INTERVAL=1;BYHOUR=6;BYMINUTE=00
start_time	String	Start time of the scheduler, for example, 2020-01-08 09:59:49

**Table 13** PolicyAssociateVault¶
Parameter	Type	Description
destination_vault_id	String	ID of the associated remote vault
vault_id	String	Vault ID

Example Requests¶

Creating a backup policy with backups automatically executed at 14:00 everyday and with each backup saved for one day

POST https://{endpoint}/v3/f841e01fd2b14e7fa41b6ae7aa6b0594/policies

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

Creating a replication policy with backups automatically replicated at 14:00 everyday and with each backup saved for one day

POST https://{endpoint}/v3/f841e01fd2b14e7fa41b6ae7aa6b0594/policies

{
  "policy" : {
    "enabled" : true,
    "name" : "policy002",
    "operation_definition" : {
      "retention_duration_days" : 1,
      "day_backups" : 0,
      "week_backups" : 0,
      "month_backups" : 0,
      "year_backups" : 0,
      "timezone" : "UTC+01:00",
      "destination_region" : "eu-nl",
      "destination_project_id" : "fcf6cb26c3bf4402869792207ad3dce4"
    },
    "operation_type" : "replication",
    "trigger" : {
      "properties" : {
        "pattern" : [ "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU;BYHOUR=14;BYMINUTE=00" ]
      }
    }
  }
}

Example Responses¶

Status code: 200

The backup policy is created. The backup policy is to automatically perform backup at 14:00 everyday and save each backup for one day.

{
  "policy" : {
    "name" : "policy001",
    "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" : {
      "retention_duration_days" : 1,
      "year_backups" : 0,
      "day_backups" : 0,
      "month_backups" : 0,
      "week_backups" : 0,
      "timezone" : "UTC+01:00"
    },
    "operation_type" : "backup",
    "id" : "cbb3ce6f-3332-4e7c-b98e-77290d8471ff"
  }
}

Succeeded in creating a replication policy. The policy is to perform replication at 14:00 every day from Monday to Sunday. The retention policy is based on the backup retention period, which is one day.

{
  "policy" : {
    "name" : "policy002",
    "enabled" : true,
    "trigger" : {
      "id" : "b37cf79e-5cfa-4a84-99a3-91d60a314c46",
      "name" : "default",
      "type" : "time",
      "properties" : {
        "pattern" : [ "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU;BYHOUR=14;BYMINUTE=00" ],
        "start_time" : "2019-05-08T06:58:05.000+00:00"
      }
    },
    "operation_definition" : {
      "retention_duration_days" : 1,
      "day_backups" : 0,
      "week_backups" : 0,
      "month_backups" : 0,
      "year_backups" : 0,
      "timezone" : "UTC+01:00",
      "destination_region" : "eu-nl",
      "destination_project_id" : "fcf6cb26c3bf4402869792207ad3dce4"
    },
    "operation_type" : "replication",
    "id" : "e47e4916-481a-4d10-95a2-165bcfe598c5"
  }
}

Status Codes¶

Status Code	Description
200	OK

Error Codes¶

See Error Codes.

last updated: 2025-09-10 09:23 UTC - commit: a29acaa99901552d6f0af9a2dbed2904c720143b