Help Center/ Distributed Cache Service/ API Reference/ API V2/ Lifecycle Management/ Creating a DCS Instance

Updated on 2022-09-19 GMT+08:00

View PDF

Creating a DCS Instance

Function

This API is used to create a DCS instance which is billed in pay-per-use mode.

URI

POST /v2/{project_id}/instances

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

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
name	Yes	String	Instance name. An instance name can contain letters, digits, underscores (_), and hyphens (-), and must start with a letter. When you create only one instance at a time, the value of this parameter can contain 4 to 64 characters. When you create multiple instances at a time, the value of this parameter can contain 4 to 56 characters. The instances are named in the format of custom name-n, where n starts from 000 and is incremented by 1. For example, if you create two instances and set the custom name to dcs_demo, the two instances are respectively named dcs_demo-000 and dcs_demo-001.
engine	Yes	String	Cache engine. The value can be Redis.
engine_version	No	String	Cache version. If the cache engine is Redis, the value can be 4.0, or 5.0.
capacity	Yes	Float	Cache capacity (GB). For a single-node or master/standby DCS Redis 4.0 or 5.0 instance, the value can be 0.125, 0.25, 0.5, 1, 2, 4, 8, 16, 32, or 64. For a Redis Cluster DCS Redis 4.0 or 5.0 instance, the value can be 24, 32, 48, 64, 96, 128, 192, 256, 384, 512, 768, or 1024.
spec_code	Yes	String	Product flavor. The query method is as follows: Method 1: Read the Service Overview document Redis 4.0 and 5.0 Instance Specifications. Method 2: Log in to the DCS console, click Buy DCS Instance, and check the instance flavor. Method 3: Call the API used to query product flavors Querying Product Flavors.
az_codes	Yes	Array of strings	ID of the AZ where the cache node resides and which has available resources. For details, see Querying AZs. Check whether the desired AZ has available resources. Master/Standby, Proxy Cluster, and Redis Cluster DCS instances support cross-AZ deployment. You can specify an AZ for the standby node. When specifying AZs for nodes, use commas (,) to separate multiple AZs. For details, see the example request.
vpc_id	Yes	String	VPC ID. You can obtain the value in either of the following ways: Method 1: Log in to the VPC console, and click the name of a VPC to view the VPC ID on the displayed details page. Method 2: Call the API used to query VPCs. For details, see Querying VPCs.
subnet_id	Yes	String	Subnet network ID. You can obtain the value in either of the following ways: Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page. Method 2: Call the API used to query subnets. For details, see Querying Subnets.
security_group_id	No	String	ID of the security group to which the instance belongs. This parameter is optional when the engine is Redis and engine_version is 4.0 or 5.0. DCS Redis 4.0 and 5.0 instances do not support security group access control. They support only whitelist-based access control.
publicip_id	No	String	ID of the EIP bound to the DCS Redis instance. This parameter is mandatory if public access is enabled (that is, enable_publicip is set to true). Default: false
enterprise_project_id	No	String	Enterprise project ID.
enterprise_project_name	No	String	Name of an enterprise project.
description	No	String	Instance description. The description can contain a maximum of 1024 characters. NOTE: The backslash (\) and quotation mark (") are special characters for JSON messages. When using these characters in a parameter value, add the escape character (\) before the characters, for example, \\ and \".
enable_ssl	No	Boolean	Whether to enable SSL for public access to a DCS Redis instance. true: enable false: disable
private_ip	No	String	IP address that is manually specified for a DCS instance. This parameter is available for DCS Redis instances.
instance_num	No	Integer	Number of instances to be created in batches. This parameter is available for DCS Redis instances. Default value: 1 Value range: 1–100 Default: 1
maintain_begin	No	String	UTC time when the maintenance time window starts. The format is HH:mm:ss. The start time and end time of the maintenance time window must indicate the time segment of a supported maintenance time window. For details, see Listing Maintenance Time Windows. The start time must be set to 22:00:00, 02:00:00, 06:00:00, 10:00:00, 14:00:00, or 18:00:00. The start time and end time must be set in pairs. If the start time is left blank, the end time must also be left blank. In this case, the system automatically sets the start time to 02:00:00.
maintain_end	No	String	UTC time when the maintenance time window ends. The format is HH:mm:ss. The start time and end time of the maintenance time window must indicate the time segment of a supported maintenance time window. For details, see Listing Maintenance Time Windows. The end time is four hours later than the start time. For example, if the start time is 22:00:00, the end time is 02:00:00. The start time and end time must be set in pairs. If the end time is left blank, the start time is also left blank. In this case, the system automatically sets the end time to 06:00:00.
password	No	String	DCS instance authentication information. NOTE: When no_password_access is set to false or not specified, the request must contain the password parameter. The password of a DCS Redis instance must meet the following complexity requirements: Can be 8 to 32 characters long. The new password must be different from the old password. Contains at least three of the following character types: Lowercase letters Uppercase letters Digits Special characters `~!@#$%^&*()-_=+\\|[{}]:'"",<.>/?
no_password_access	No	Boolean	Whether the instance can be accessed without a password. true: The instance can be accessed without a password. false: The instance can be accessed only after password authentication. If this parameter is not set, the default value false is used. Default: false
instance_backup_policy	No	BackupPolicy object	Backup policy. This parameter is supported when the instance type is master/standby or cluster.
tags	No	Array of ResourceTag objects	Instance tag key and value.
access_user	No	String	If the cache engine is Redis, you do not need to set this parameter.
enable_publicip	No	Boolean	Whether to enable public network access for the DCS Redis instance. true: enable false: disable Default: false
port	No	Integer	Port customization. If this parameter is not sent or is left empty when you create a Redis 4.0 or 5.0 instance, the default port 6379 will be used. To customize a port, specify a port number in the range from 1 to 65535.
rename_commands	No	Object	Critical command renaming. If this parameter is not sent or is left empty when you create a Redis 4.0 or 5.0 instance, no critical commands will be renamed. Currently, only COMMAND, KEYS, FLUSHDB, FLUSHALL, and HGETALL commands can be renamed.

**Table 3** BackupPolicy
Parameter	Mandatory	Type	Description
backup_type	Yes	String	Backup type. auto: automatic backup manual: manual backup
save_days	No	Integer	This parameter is mandatory when backup_type is set to auto. Retention period, in days. The value ranges from 1 to 7.
periodical_backup_plan	No	BackupPlan object	Backup schedule. This parameter is mandatory when backup_type is set to auto.

**Table 4** BackupPlan
Parameter	Mandatory	Type	Description
timezone_offset	No	String	Time zone in which backup is performed. Range: GMT –12:00 to GMT +12:00. If this parameter is left blank, the current time zone of the DCS-Server VM is used by default.
backup_at	Yes	Array of integers	Day in a week on which backup starts. The value ranges from 1 to 7, where 1 indicates Monday, and 7 indicates Sunday.
period_type	Yes	String	Interval at which backup is performed, which supports only weekly currently.
begin_at	Yes	String	Time at which backup starts. 00:00-01:00 indicates that the backup starts at 00:00.

**Table 5** ResourceTag
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. This field cannot be left blank. The key value of a resource must be unique. The tag key can contain a maximum of 36 characters. The tag key must be unique and cannot be empty.
value	No	String	Tag value. This parameter is mandatory when action is set to create and is optional when action is set to delete. The tag value can contain a maximum of 43 characters.

Response Parameters

Status code: 200

**Table 6** Response body parameters
Parameter	Type	Description
instances	Array of Instances objects	DCS instance ID and name. If multiple DCS instances are created at a time, multiple DCS instance IDs and names will be returned.

**Table 7** Instances
Parameter	Type	Description
instance_id	String	DCS instance ID.
instance_name	String	DCS instance name.

Status code: 400

**Table 8** Response body parameters
Parameter	Type	Description
error_msg	String	Error message. Maximum: 1024
error_code	String	Error code. Maximum: 9
error_ext_msg	String	Extended error information. This parameter is not used currently and is set to null. Maximum: 1024

Status code: 401

**Table 9** Response body parameters
Parameter	Type	Description
error_msg	String	Error message. Maximum: 1024
error_code	String	Error code. Maximum: 9
error_ext_msg	String	Extended error information. This parameter is not used currently and is set to null. Maximum: 1024

Status code: 403

**Table 10** Response body parameters
Parameter	Type	Description
error_msg	String	Error message. Maximum: 1024
error_code	String	Error code. Maximum: 9
error_ext_msg	String	Extended error information. This parameter is not used currently and is set to null. Maximum: 1024

Status code: 404

**Table 11** Response body parameters
Parameter	Type	Description
error_msg	String	Error message. Maximum: 1024
error_code	String	Error code. Maximum: 9
error_ext_msg	String	Extended error information. This parameter is not used currently and is set to null. Maximum: 1024

Status code: 500

**Table 12** Response body parameters
Parameter	Type	Description
error_msg	String	Error message. Maximum: 1024
error_code	String	Error code. Maximum: 9
error_ext_msg	String	Extended error information. This parameter is not used currently and is set to null. Maximum: 1024

Example Requests

Creating a DCS Redis instance

POST https://{dcs_endpoint}/v2/{project_id}/instances

{
  "name" : "dcs-APITest",
  "description" : "Test",
  "engine" : "Redis",
  "engine_version" : 5.0,
  "enterprise_project_id" : 0,
  "enterprise_project_name" : "default",
  "vpc_id" : "5e37b3be-950a-48e1-b498-65b63d336481",
  "security_group_id" : "securityGroupId",
  "enable_ssl" : false,
  "private_ip" : "",
  "az_codes" : [ "xxxxxx" ],
  "capacity" : 2,
  "access_user" : "",
  "instance_num" : 1,
  "maintain_begin" : "02:00:00",
  "maintain_end\"" : "06:00:00",
  "password" : "********",
  "enable_publicip" : false,
  "spec_code" : "redis.single.xu1.tiny.128",
  "subnet_id" : "a3bd29e4-d5bc-414c-a79a-1f35ee4ead88",
  "no_password_access" : false
}

Creating a pay-per-use, master/standby DCS Redis instance with tags, a customized port, renamed commands, and cross-AZ deployment

{
  "enterprise_project_name" : "default",
  "vpc_id" : "c5cd009b-9ba9-41f2-9a26-2b8c3f3ffd39",
  "description" : "Test",
  "security_group_id" : "d57fad27-e3e9-43b7-9498-0a698ab63b27",
  "port" : 4040,
  "maintain_end\"" : "06:00:00",
  "enable_ssl" : false,
  "private_ip" : "",
  "az_codes" : [ "xxxxxx", "xxxxxxx" ],
  "capacity" : 2,
  "access_user" : "",
  "instance_num" : 1,
  "maintain_begin" : "02:00:00",
  "enterprise_project_id" : 0,
  "password" : "********",
  "enable_publicip" : false,
  "engine" : "Redis",
  "spec_code" : "redis.ha.au1.large.2",
  "name" : "dcs-demo",
  "subnet_id" : "7e95c4d6-d7af-424c-a3cf-2be10968fe81",
  "engine_version" : 4.0,
  "no_password_access" : true,
  "rename_commands" : {
    "keys" : "keys001",
    "flushdb" : "flushdb001",
    "flushall" : "flushall001"
  },
  "tags" : [ {
    "key" : "dcs001",
    "value" : 2
  }, {
    "key" : "dcs003",
    "value" : 4
  } ]
}

Creating a master/standby DCS Memcached instance with backup policies

{
  "publicip_id" : "",
  "enterprise_project_name" : "default",
  "vpc_id" : "0402ea19-5457-4032-9d1b-eb48b98f6c66",
  "description" : "Test",
  "security_group_id" : "4b95a790-5cfc-463d-8de5-42199e55371c",
  "maintain_end\"" : "06:00",
  "enable_ssl" : false,
  "private_ip" : "",
  "az_codes" : [ "xxxxxx" ],
  "capacity" : 2,
  "access_user" : "",
  "instance_num" : 1,
  "maintain_begin" : "02:00:00",
  "enterprise_project_id" : 0,
  "password" : "********",
  "enable_publicip" : false,
  "engine" : "Memcached",
  "spec_code" : "dcs.memcached.single_node",
  "name" : "dcs-APITest",
  "subnet_id" : "a3bd29e4-d5bc-414c-a79a-1f35ee4ead88",
  "engine_version" : 3.0,
  "no_password_access" : false,
  "instance_backup_policy" : {
    "save_days" : 1,
    "backup_type" : "auto",
    "periodical_backup_plan" : {
      "begin_at" : "16:00-17:00",
      "period_type" : "weekly",
      "backup_at" : [ 1, 2, 3, 4, 5, 6, 7 ],
      "timezone_offset" : "+0800"
    }
  }
}

Example Responses

Status code: 200

The DCS instance creation task is submitted successfully.

If the instance status is RUNNING, the DCS instance has been successfully created.

Example 1

{
  "instances" : [ {
    "instance_id" : "3c49fd6b-fc7c-419e-9644-b6cce008653f",
    "instance_name" : "dcs-test005"
  } ]
}

Example 2

{
  "instances" : [ {
    "instance_id" : "77284d69-cd51-4bf1-aa30-2e60f055800c",
    "instance_name" : "dcs-APITest1"
  } ]
}

Status code: 400

Invalid request.

{
  "error_code" : "DCS.1004",
  "error_msg" : "Project ID does not match the token."
}

Status code: 401

Invalid authentication information.

{
  "error_code" : "DCS.1001",
  "error_msg" : "Invalid token."
}

Status code: 403

The request is rejected.

{
  "error_code" : "DCS.2003",
  "error_msg" : "This role does not have the permission to perform this operation."
}

Status code: 404

The requested resource is not found.

{
  "error_code" : "DCS.4001",
  "error_msg" : "The requested URL does not exist."
}

Status code: 500

Internal service error.

{
  "error_code" : "DCS.5000",
  "error_msg" : "Internal service error."
}

Status Codes

Status Code	Description
200	The DCS instance creation task is submitted successfully. NOTE: If the instance status is RUNNING, the DCS instance has been successfully created.
400	Invalid request.
401	Invalid authentication information.
403	The request is rejected.
404	The requested resource is not found.
500	Internal service error.