Creating an Instance

Function

This API is used to create a LakeFormation instance.

URI

POST /v1/{project_id}/instances

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For how to obtain the project ID, see Obtaining a Project ID (lakeformation_04_0026.xml).

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Tenant token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
name	Yes	String	Instance name. Enter 4 to 32 characters. Only letters, numbers, hyphens (-), and underscores (_) are allowed.
charge_mode	Yes	String	Billing type. postPaid indicates the pay-per-use billing and prePaid indicates the yearly/monthly billing. Enumeration values: postPaid prePaid
enterprise_project_id	No	String	Enterprise project ID. This parameter is available only when an enterprise project is interconnected. Enter 1 to 64 characters. Only letters, numbers, and hyphens (-) are allowed.
description	No	String	Instance description entered by a user. The value contains a maximum of 255 characters.
shared	Yes	Boolean	The parameter values include false (physical multi-tenancy) and true (logical multi-tenancy). The default value is true.
order_id	No	String	Order ID of a yearly/monthly instance.
specs	No	Array of CreateSpec objects	Specification list.
tags	No	Array of ResourceTag objects	Tag list. Up to 20 tags can be added.
charge_info	No	ChargeInfo object	Billing information. This parameter cannot be left blank when charge_mode is set to prePaid.

**Table 4** CreateSpec
Parameter	Mandatory	Type	Description
product_id	No	String	Product ID. The system automatically generates a value, for example, OFFI8XXXXXXXXXXXXXXXX4.
spec_code	Yes	String	Specification code. The system automatically generates a value, for example, lakeformation.unit.basic.qps.
stride_num	Yes	Integer	Number of steps. QPS indicates the maximum number of requests per second. The minimum value is 5 and the step is 1.

**Table 5** ResourceTag
Parameter	Mandatory	Type	Description
key	Yes	String	Key.
value	No	String	Value.

**Table 6** ChargeInfo
Parameter	Mandatory	Type	Description
period_type	No	String	Subscription period type. This parameter is valid and mandatory when charge_mode is set to prePaid. The options are MONTH (monthly) and YEAR (yearly). Enumeration values: MONTH YEAR
period_num	No	Integer	Subscription period. This parameter is valid and mandatory only when charge_mode is set to prePaid. If period_type is set to month, the parameter value ranges from 1 to 9. If period_type is set to year, the parameter value ranges from 1 to 3. When a floating-point value is transferred, the value is automatically truncated to an integer.
is_auto_renew	No	Boolean	Whether to automatically renew the subscription. This parameter is valid and mandatory when charge_mode is set to prePaid. The payment is automatically made during subscription renewal. The default renewal period is one month for monthly subscription and one year for yearly subscription. The renewal period can be configured as needed. true: Automatic renewal is enabled. false: Automatic renewal is disabled. The default value is false.
is_auto_pay	No	Boolean	Whether the order will be automatically paid after yearly/monthly DB instances are created. This parameter does not affect the payment mode of automatic renewal. And it is valid and mandatory when charge_mode is set to prePaid. true: The order will be automatically paid. false: The order will be manually paid. The default value is false.

Response Parameters

Status code: 202

**Table 7** Response header parameters
Parameter	Type	Description
X-request-id	String	Request ID, which is used to locate auxiliary information.

**Table 8** Response body parameters
Parameter	Type	Description
instance_id	String	LakeFormation instance ID.
name	String	Instance name.
description	String	Description.
enterprise_project_id	String	Enterprise project ID.
shared	Boolean	Logical multi-tenancy or physical multi-tenancy. false indicates physical multi-tenancy and true indicates logical multi-tenancy.
default_instance	Boolean	Default instance or not.
create_time	String	Instance creation timestamp.
update_time	String	Instance update timestamp.
status	String	Instance status. RESOURCE_PREPARATION indicates that the instance is being prepared. RUNNING indicates that the instance is running. RESOURCE_RELEASE indicates that the instance is being released. DELETED indicates that the instance has been released, RESOURCE_PREPARATION_FAIL indicates that the instance preparation fails. FROZEN_RELEASABLE indicates that the instance can be restored. FROZEN_UNRELEASABLE indicates that the instance cannot be restored. RECOVERING, DELETING, and SCALING indicates that the instance is being restored, deleted, and scaled, respectively. SCALE_FAIL indicates the scaling of the instance fails. Enumeration values: RESOURCE_PREPARATION RUNNING RESOURCE_RELEASE DELETED RESOURCE_PREPARATION_FAIL FROZEN_RELEASABLE FROZEN_UNRELEASABLE RECOVERING DELETING SCALING SCALE_FAIL
resource_progress	Integer	Resource preparation progress, in percentage. This value is calculated and returned only when the instance is in the resource preparation state.
resource_expected_duration	Integer	Estimated resource preparation duration, in minutes.
scale_progress	Integer	Specification change progress, in percentage. The value is calculated and returned only when the instance is in the specification changing state.
scale_expected_duration	Integer	Estimated specification change duration, in minutes.
in_recycle_bin	Boolean	Whether the target is in the recycle bin.
tags	Array of ResourceTag objects	Tags.
specs	Array of CreateSpec objects	Specifications.
charge_mode	String	Billing mode. postPaid indicates pay-per-use billing and prePaid indicates yearly/monthly billing. Enumeration values: prePaid postPaid

**Table 9** ResourceTag
Parameter	Type	Description
key	String	Key.
value	String	Value.

**Table 10** CreateSpec
Parameter	Type	Description
product_id	String	Product ID. The system automatically generates a value, for example, OFFI8XXXXXXXXXXXXXXXX4.
spec_code	String	Specification code. The system automatically generates a value, for example, lakeformation.unit.basic.qps.
stride_num	Integer	Number of steps. QPS indicates the maximum number of requests per second. The minimum value is 5 and the step is 1.

Status code: 400

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.
common_error_code	String	CBC common error code.
solution_msg	String	Solution.

Status code: 404

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.
common_error_code	String	CBC common error code.
solution_msg	String	Solution.

Status code: 500

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.
common_error_code	String	CBC common error code.
solution_msg	String	Solution.

Example Requests

POST https://{endpoint}/v1/{project_id}/instances

{
  "name" : "lakeformation-instance",
  "charge_mode" : "postPaid",
  "shared" : "true",
  "description" : "",
  "tags" : [ {
    "key" : "key1"
  } ],
  "enterprise_project_id" : "0"
}

Example Responses

Status code: 202

Successful submission of an instance creation request.

{
  "instance_id" : "2aeb1789-1b04-4bad-92bf-486a399b9a3e",
  "name" : "lakeformation-instance",
  "description" : "",
  "enterprise_project_id" : "0",
  "shared" : false,
  "default_instance" : false,
  "create_time" : "2023-08-03T11:50:02.000+00:00",
  "update_time" : "2023-08-03T11:50:04.000+00:00",
  "status" : "RUNNING",
  "in_recycle_bin" : false,
  "tags" : [ ],
  "specs" : [ {
    "spec_code" : "lakeformation.unit.basic.metadata",
    "stride_num" : 0
  }, {
    "spec_code" : "lakeformation.unit.basic.apiinvoke",
    "stride_num" : 0
  } ],
  "charge_mode" : "postPaid"
}

Status code: 400

Bad Request

{
  "error_code" : "common.01000001",
  "error_msg" : "failed to read http request, please check your input, code: 400, reason: Type mismatch., cause: TypeMismatchException"
}

Status code: 401

Unauthorized

{
  "error_code": 'APIG.1002',
  "error_msg": 'Incorrect token or token resolution failed'
}

Status code: 403

Forbidden

{
  "error" : {
    "code" : "403",
    "message" : "X-Auth-Token is invalid in the request",
    "error_code" : null,
    "error_msg" : null,
    "title" : "Forbidden"
  },
  "error_code" : "403",
  "error_msg" : "X-Auth-Token is invalid in the request",
  "title" : "Forbidden"
}

Status code: 404

Not Found

{
  "error_code" : "common.01000001",
  "error_msg" : "response status exception, code: 404"
}

Status code: 408

Request Timeout

{
  "error_code" : "common.00000408",
  "error_msg" : "timeout exception occurred"
}

Status code: 500

Internal Server Error

{
  "error_code" : "common.00000500",
  "error_msg" : "internal error"
}

Status Codes

Status Code	Description
202	Successful submission of an instance creation request.
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
408	Request Timeout
500	Internal Server Error