You need to enable JavaScript to run this app.
导航
CreateInstance - 创建实例
最近更新时间:2024.10.17 15:24:52首次发布时间:2023.03.30 19:59:24

调用 CreateInstance 创建消息队列 Kafka版实例。

使用说明

实例是消息队列 Kafka版服务的虚拟机资源,用于管理和存储 Topic、Group 等资源。

注意事项

  • 如果是首次创建 Kafka 实例,您需要先完成跨服务访问授权,建议通过火山引擎主账号操作。详细说明请参考跨服务访问授权
  • 如果需要通过私有网络访问消息队列 Kafka版实例,请先在相同地域创建 ECS 云服务器、私有网络和子网。创建实例后,不可更改实例所在的私有网络和子网。
  • 如果需要通过公网访问消息队列 Kafka版实例,请先申请同地域的 EIP,详细操作步骤请参考申请公网IP
  • 默认情况下,您可以在每个地域中创建 8 个 Kafka 实例,每个账号在每个地域中的所有实例存储容量总和最大为 90TiB,否则创建实例时报错“The instance_num/storage_sum has exceeded quota”。如需提高配额,请在配额中心提交申请,例如申请提高每个地域下的最大实例数量(InstanceNum),最高可调整至 16 个。

调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数

参数
类型
是否必填
示例值
描述
Action
String

CreateInstance

要执行的操作,取值:CreateInstance。

Version
String

2022-05-01

API的版本,取值:2022-05-01。

ZoneId
String

cn-beijing-a

实例所在的可用区 ID。
消息队列 Kafka版实例支持跨 AZ 部署,多个可用区ID之间以逗号(,)间隔。您可以调用 DescribeAvailabilityZones 查询当前地域提供服务的可用区列表。

UserPassword
String

Test@123456

SASL/PLAIN 用户的密码。需要满足以下要求:

  • 长度为 8~32 个字符。
  • 由大写字母、小写字母、数字、特殊字符中的任意三种组成。
  • 支持的特殊字符包括 !@#$%^&*()_+-=。
UserName
String

Test1

SASL/PLAIN 用户名称。需要满足以下要求:

  • 由小写字母、数字、连字符(-)或下划线组成。
  • 长度为 3~64 个字符。
  • 用户名不支持设置为 admin 或 monitor,且实例内用户名称唯一。
StorageType
String

ESSD_PL0

Kafka 实例数据存储的云盘类型。可设置为 ESSD_FlexPL 或 ESSD_PL0,默认为 ESSD_FlexPL。关于不同存储类型的详细性能说明,请参考云盘规格

  • 对于峰值流量超过 100MB/s 的规格,应使用 ESSD_FlexPL。
  • 创建实例后不支持修改存储类型,请谨慎选择。
IpWhiteList
Array of String

{"acl-2e6694dd6ef3****","acl-4848ddb745fe49****"}

实例绑定的白名单 ID 列表。绑定白名单后,仅配置在白名单中的 IP 地址与地址段才能访问此实例。
若未设置此参数,新 Kafka 实例将绑定白名单 default,对应 IP 地址为 0.0.0.0,表示允许所有地址访问该 Kafka 实例。

Tags
Object

{"testKey":"testVal"}

云资源标签。可以将实例通过标签进行归类,便于实例的搜索和资源聚合。详细说明请参考标签管理

ChargeInfo
Object

--

Kafka 实例的计费类型等计费信息。

Parameters
String

{"LogRetentionHours":"72","MessageMaxByte":"10","MessageTimestampType":"CreateTime","OffsetRetentionMinutes":"4320"}

Kafka 实例的初始参数配置。
当前支持的参数列表及参数默认值,请参考下表。您也可以通过文档修改参数配置查看各参数的详细信息。
通过 Postman 等方式调用 API 时,应注意转义,例如 {\"LogRetentionHours\":\"72\",\"MessageMaxByte\":\"10\",\"MessageTimestampType\":\"CreateTime\",\"OffsetRetentionMinutes\":\"4320\"}

Parameters 参数说明

  • "MessageMaxByte":"10":最大消息大小。单位为MB,取值范围为1~12。默认为10。
  • "LogRetentionHours":"72":消息保留时长。单位为小时,取值范围为0~2160,即消息最久保留90天。默认为72。
  • "OffsetRetentionMinutes":"4320":消费位点保留时长。单位为分钟,取值范围为1~10080,即消费位点最久保留7天。默认为4320。
  • "MessageTimestampType":"LogAppendTime":消息时间类型,支持设置为LogAppendTimeCreateTime。LogAppendTime 表示消息写入到服务端的时间;CreateTime 表示Producer 创建消息的时间。
InstanceDescription
String

instance for test

Kafka 实例的简单描述。长度范围为 1~128 个字符。

InstanceName
String

Name123

Kafka 实例的名称。 需满足以下要求:

  • 只能包含中文、字母、数字、下划线(_)和连字符(-)。
  • 不能以数字和连字符(-)开头。
  • 长度范围为 1~128 个字符。

说明

如果创建实例时未指定名称,则默认将实例ID作为实例名称。

EipId
String

eip-mjhulvqza6805smt1bnc****

EIP 的 ID。

说明

  • 指定 EipId 表示开启实例的公网访问。
  • EIP 提供独立的公网 IP 资源,包括公网 IP 地址与公网出口带宽服务。指定此参数开启公网访问后,公网地址将绑定您的弹性公网 IP(EIP),费用由 EIP 收取。
SubnetId
String

subnet-min6uy01kuf45smt1a2i****

实例所在的 VPC 子网 ID。

VpcId
String

vpc-13fo9gkz6j6683n6nu5ec****

实例所在的私有网络(VPC) ID。

说明

  • 实例创建完成后,不可修改对应的私有网络和子网。创建实例时请谨慎操作。
  • 您可以调用私有网络(VPC)的 DescribeVpcs 接口查询可用的 VPC 和子网列表。
PartitionNumber
Integer

1000

分区数量。取值范围取决于当前指定的计算规格,您可以通过文档产品规格查看指定计算规格支持的分区数量范围。
不同规格提供数量不同的免费分区额度,超过免费额度的部分将另外收取分区费用。每个规格可创建的分区数量范围请参考产品规格,分区的计费方式请参考计费项

StorageSpace
Integer

1000

实例的存储空间。单位为 GiB,必须指定为 100 的倍数。
取值范围取决于当前指定的计算规格,您可以通过文档产品规格查看指定计算规格支持的存储空间范围和默认存储空间大小。

ComputeSpec
String

kafka.30xrate.hw

实例的计算规格。您可以通过文档产品规格查看计算规格列表。

Version
String

2.2.2

支持的 Kafka 版本。当前支持的版本包括:

  • 2.2.2:Kafka 2.2.2 版本。
  • 2.8.2:Kafka 2.8.2 版本。
ClientToken
String

123e4567-e89b-12d3-a456-426655440000

保证客户端请求幂等性的标识。 该标识为 1~64 位的 ASCII 字符串,大小写敏感,由客户端生成,应确保不同请求之间该标识具有唯一性。
如何使用幂等标识,请参考请求幂等性

ProjectName
String

default

当前创建的 Kafka 实例所属的 IAM 项目。如果未指定 IAM 项目,消息队列 Kafka版会将新实例添加到名为 default 的 IAM 项目中。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构

参数
类型
示例值
描述
InstanceId
String

kafka-cnngqkfgdudt****

Kafka 实例 ID。

OrderId
String

order-712089661643355****

订单 ID。

请求示例

POST /?Action=CreateInstance&Version=2022-05-01 HTTP/1.1
Content-Type: application/json
Host: kafka.volcengineapi.com
X-Date: 20210328T100802Z
Authorization: HMAC-SHA256 Credential=AK********/20210328/cn-beijing/Kafka/request, SignedHeaders=x-date, Signature=********

{
  "ZoneId": "cn-beijing-a",
  "Version": "2.2.2",
  "ComputeSpec": "kafka.30xrate.hw",
  "VpcId": "vpc-rs4yccs57e9sv0x57bf****",
  "SubnetId": "subnet-rrps5hvr1bswv0x58fp****",
  "UserName": "kafka2001",
  "UserPassword":"Test@123456",
  "ChargeInfo": {
    "ChargeType": "PrePaid",
    "AutoRenew": true,
    "PeriodUnit": "Month",
    "Period": 1
  }
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202302271904532FE25613615E5671AB07",
        "Action": "CreateInstance",
        "Version": "2022-05-01",
        "Service": "Kafka",
        "Region": "cn-beijing"
    },
    "Result": {
        "InstanceId": "kafka-cnngbnntswg1****",
        "OrderId": "Order720478931462498****"
    }
}

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码
错误码
错误信息
说明
400
InvalidParameter.EipNumber
The EIP number is insufficient.

EIP数量不足。

400
InvalidProject.NotFound
The specified project does not exist.

该项目不存在。

400
ResourceScaleSoldOut
The scale of zone %s is sold out. Please select another availability zone to create an instance.

%s可用区资源不足。

400
ResourceAZSoldOut
zone %s is sold out. Please select another availability zone to create an instance.

%s可用区资源不足。

400
InsufficientResource
The resource is insufficient.

资源不足,无法执行该操作。

400
QuotaExceeded.CreateInstance
The quota of create instance exceeds.

实例个数超过配额限制。

400
OperationDenied.ResourceSoldOut
The operation is not permitted due to the requested resource is sold out in the specified zone; try other types of resources or other regions and zones.

当前可用区资源不足。

400
InvalidInstance.AlreadyExists
The specified instance has already existed.

该实例已存在。

400
Insufficient.Balance
The account balance is insufficient.

您的账户余额不足。

400
Forbidden.Authentication
This operation is forbidden by Realname Authentication system.

账户未实名认证。

400
InvalidParameter.Malformed
The specified parameter %s is Malformed.

%s参数不符合规范。

400
InvalidParameter.Unsupported
The specified parameter %s is not supported.

不支持%s参数。

400
InvalidParameter
The specified parameter is not valid.

参数值无效。

400
QuotaExceeded.InstanceNumber
The number of instances exceeds the limit.

实例数量超出上限。

400
QuotaExceeded.StorageCapacity
The sum storage capacity of all instances exceeds the limit.

所有实例的存储空间之和超出配额上限。

400
InvalidParameter.StorageCapacity
The storage capacity is not within the range specified by the instance specification.

期望的存储空间不在计算规格指定的范围内。

400
InstanceOrderCreateFailed
Create instance order failed.

创建订单失败。

400
OperationDenied.ExistCreatingOrder
The operation is not permitted due to exist creating instance order.

已存在创建中的订单,无法执行该操作。

400
OperationDenied.InsufficientIp
The operation is not permitted due to the insufficient IP address in the target subnet.

所选子网IP数量不足,无法执行该操作。

400
InvalidParameter.DiskType
The specified parameter DiskType is not valid.

DiskType 参数值无效。

403
OperationDenied.AccountNotAuthorized
You are not authorized to perform this operation.

您不具备相关权限 ,请授权或切换账号后重试。

404
InvalidEip.NotFound
The specified EIP does not exist.

该EIP不存在。

500
InternalError
The request failed due to some unknown error, exception or failure.

内部错误,请稍后重试。