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

OK

  • 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.