文档中心

CreateInstance

最近更新时间：2023.12.11 21:55:05

首次发布时间：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 个。

请求参数

参数	参数类型	是否必选	示例值	说明
ZoneId	String	是	cn-beijing-a	实例所在的可用区ID。消息队列 Kafka版实例支持跨AZ部署，查看指定可用区下提供哪些计算规格时，可以指定多个可用区。多个可用区ID之间以逗号（,）间隔。您可以调用 DescribeAvailabilityZones 查询当前提供服务的可用区列表。
Version	String	是	2.2.2	支持的Kafka版本。当前支持的版本包括： 2.2.2：Kafka 2.2.2版本。 2.8.2：Kafka 2.8.2版本。
ComputeSpec	String	是	kafka.20xrate.hw	实例的计算规格。消息队列 Kafka版实例提供的计算规格清单，请参考产品规格。
VpcId	String	是	vpc-13fo9gkz6j6683n6nu5ec****	实例所在的 VPC ID。说明实例创建完成后，不可修改对应的私有网络。创建实例时请谨慎操作。您可以调用私有网络（VPC）的 DescribeVpcs 接口查询可用的 VPC 和子网列表。
SubnetId	String	是	subnet-min6uy01kuf45smt1a2i****	实例所在的 VPC 子网 ID。您可以调用私有网络（VPC）的 DescribeVpcs 接口查询可用的 VPC 和子网列表。
ChargeInfo	ChargeInfoObject	是	/	Kafka 实例的计费类型等计费信息。详细信息请参考数据结构文档中 ChargeInfoObject 部分。
UserName	String	否	Test1	SASL/PLAIN 用户名称。应符合以下要求：由字母、数字、连字符（-）或下划线组成。长度为 3~64 个字符。用户名不支持设置为 admin 或 monitor，且实例内用户名称唯一。
UserPassword	String	否	Test@123456	SASL/PLAIN 用户的密码。应符合以下要求：长度为 8~32 个字符。应至少包含大写字母、小写字母、数字、特殊字符中的任意三种。支持的特殊字符包括`!@#$%^&*()_+-=`。
StorageSpace	Integer	否	1000	实例的存储空间。单位为 GiB，必须指定为 100 的倍数。取值范围取决于当前指定的计算规格。
StorageType	String	否	ESSD_PL0	Kafka 实例数据存储的云盘类型。可设置为 ESSD_FlexPL 或 ESSD_PL0，默认为 ESSD_FlexPL。关于不同存储类型的详细性能说明，请参考云盘规格。对于峰值流量超过 100MB/s 的规格，应使用 ESSD_FlexPL。创建实例后不支持修改存储类型，请谨慎选择。
PartitionNumber	Integer	否	1000	分区数量。取值范围取决于当前指定的计算规格。不同规格提供数量不同的免费分区额度，超过免费额度的部分将另外收取分区费用。每个规格可创建的分区数量范围请参考产品规格，分区的计费方式请参考计费项。
EipId	String	否	eip-mjhulvqza6805smt1bnc****	EIP 的 ID。说明指定 EipId 表示开启实例的公网访问。 EIP提供独立的公网IP资源，包括公网IP地址与公网出口带宽服务。指定此参数开启公网访问后，公网地址将绑定您的弹性公网IP（EIP），费用由 EIP 收取。
InstanceName	String	否	Name123	Kafka 实例的名称。应符合以下要求：只能包含中文、字母、数字、下划线（_）和连字符（-）。不能以数字和连字符（-）开头。长度范围为 1~128 个字符。说明如果创建实例时未指定名称，则默认将实例 ID 作为实例名称。
InstanceDescription	String	否	instance for test	Kafka 实例的简单描述。长度范围为 1~128 个字符。
Parameters	String	否	"{"MessageMaxByte": "10","LogRetentionHours": "72","OffsetRetentionMinutes": "4320"}"	Kafka 实例的初始参数配置。当前支持的参数列表及参数默认值，请参考下表 Parameters 参数说明。您也可以通过修改参数配置查看各参数的详细信息。通过 Postman 等方式调用 API 时，应注意转义，例如`{\"LogRetentionHours\":\"72\",\"MessageMaxByte\":\"10\",\"MessageTimestampType\":\"CreateTime\",\"OffsetRetentionMinutes\":\"4320\"}`。
ProjectName	String	否	newproject	当前创建的 Kafka 实例所属的 IAM 项目。如果未指定 IAM 项目，消息队列 Kafka版会将新实例添加到名为 `default` 的 IAM 项目中。
Tags	Map<String, String>	否	{"testKey":"testVal"}	云资源标签。可以将实例通过标签进行归类，便于实例的搜索和资源聚合。详细说明请参考标签概述。
IpWhiteList	Array of String	否	{"acl-2e6694dd6ef3496c9a00aeaf56a7**","acl-4848ddb745fe49b3947c5dbdfbb6**"}	实例绑定的白名单 ID 列表。绑定白名单后，仅配置在白名单中的 IP 地址与地址段才能访问此实例。若未设置此参数，新 Kafka 实例将绑定白名单 `default`，对应 IP 地址为 0.0.0.0，表示允许所有地址访问该 Kafka 实例。
ClientToken	String	否	123e4567-e89b-12d3-a456-426655440000	保证客户端请求幂等性的标识。该标识为 1~64 位的 ASCII 字符串，大小写敏感，由客户端生成，应确保不同请求之间该标识具有唯一性。如何使用幂等标识，请参考请求幂等性。

Parameters 参数说明

参数	参数类型	是否必选	示例值	说明
MessageMaxByte	String	否	12	最大消息大小。单位为 MB，取值范围为 1～12。默认为 10。
LogRetentionHours	String	否	2160	消息保留时长。单位为小时，取值范围为 0～2160，即消息最久保留 90 天。默认为72。
OffsetRetentionMinutes	String	否	10080	消费位点保留时长。单位为分钟，取值范围为 1～10080，即消费位点最久保留 7 天。默认为 4320。
MessageTimestampType	String	否	LogAppendTime	消息时间类型，支持设置为： LogAppendTime：消息写入到服务端的时间。 CreateTime：（默认）Producer 创建消息的时间。
AutoDeleteGroup	String	否	false	是否自动删除 Group。默认为 false。 true：如果消费者组中的所有消费者处于 Empty 状态，超出消费位点保留时长后，后端服务会自动删除该消费者组。 false：消费进度的自动删除不影响消费组的状态，Empty 状态的 Group 不会被自动删除。

响应参数

参数	参数类型	示例值	说明
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.20xrate.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****"
    }
}

使用说明

注意事项

请求参数

响应参数

示例

请求示例

响应示例