All Products
Search

This Product

    Cloud Firewall:AddAddressBook

    Document Center

    Cloud Firewall:AddAddressBook

    Last Updated:Dec 15, 2025

    Creates an address book. You can create an IPv4 address book, an ECS tag-based address book, an IPv6 address book, a domain name address book, or an ACK address book.

    Operation description

    This operation creates an address book. You can create an IPv4 address book, an ECS tag-based address book, an IPv6 address book, a domain name address book, or an ACK address book.

    QPS limit

    This operation has a queries per second (QPS) limit of 10 for each user. If you exceed this limit, API calls are throttled, which can affect your business. Call this operation at a reasonable rate.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    No authorization for this operation. If you encounter issues with this operation, contact technical support.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    SourceIp deprecated

    string

    No

    The source IP address of the visitor.

    192.0.XX.XX
    Lang

    string

    No

    The language of the address book description.

    Valid values:

    • en :

      English

    • zh :

      Chinese (default)

    zh
    AddressList

    string

    No

    The list of addresses in the address book. Separate multiple addresses with commas (,). For each address, separate the address and its description with a space.

    Note

    This parameter is required when GroupType is set to ip, port, or domain.

    • If you set GroupType to ip, enter IP addresses in the list. Example: 192.0.XX.XX/32 development segment,10.0.0.X/24,192.0.XX.XX/24 test segment.

    • If you set GroupType to port, enter ports or port ranges in the list. Example: 80 HTTP port,100/200,3306 database port.

    • If you set GroupType to domain, enter domain names in the list. Example: example.com test domain name,aliyundoc.com,www.aliyun.com Alibaba Cloud official website.

    192.0.XX.XX/32 开发网段,192.0.XX.XX/24 测试网段
    Description

    string

    Yes

    The description of the address book.

    sz-001
    GroupName

    string

    Yes

    The name of the address book.

    sz-001
    GroupType

    string

    Yes

    The type of the address book.

    Valid values:

    • port :

      Port

    • ackLabel :

      ACK cluster pod label

    • ipv6 :

      IPv6

    • ip :

      IPv4

    • domain :

      Domain name

    • ackNamespace :

      ACK cluster pod namespace

    • tag :

      ECS tag

    ip
    AutoAddTagEcs

    string

    No

    Specifies whether to automatically add the public IP addresses of ECS instances that match the specified tags to the address book.

    Valid values:

    • 0 :

      No (default)

    • 1 :

      Yes

    1
    TagRelation

    string

    No

    The logical relationship between multiple ECS tags.

    Valid values:

    • or :

      An OR relationship. The public IP addresses of ECS instances that match any of the specified tags are added to the address book.

    • and :

      An AND relationship. The public IP addresses of ECS instances that match all the specified tags are added to the address book. This is the default value.

    and
    TagList

    array<object>

    No

    The list of ECS tags.

    object

    No

    The ECS tag.

    TagValue

    string

    No

    The value of the ECS tag.

    1
    TagKey

    string

    No

    The key of the ECS tag.

    TXY
    AckClusterConnectorId

    string

    No

    The ID of the ACK cluster connector. You can obtain this value from the following operation:

    ac-7c1bad6c3cc84c33baab1

    AckNamespaces

    array

    No

    The list of ACK cluster pod namespaces.

    Note

    You can specify a maximum of 10 namespaces.

    string

    No

    The ACK cluster pod namespace. You can obtain this value from the following operation:

    Note

    This parameter is required when GroupType is set to ackNamespace.

    kube-system
    AckLabels

    array<object>

    No

    The list of ACK cluster pod labels.

    Note

    You can specify a maximum of 10 labels.

    object

    No

    The ACK cluster pod label. You can obtain this value from the following operation:

    Note

    This parameter is required when GroupType is set to ackLabel.

    Key

    string

    No

    The key of the ACK cluster pod label.

    app
    Value

    string

    No

    The value of the ACK cluster pod label.

    storage-operator

    When you call this operation, you must specify both the API-specific request parameters and common request parameters. For more information about common request parameters, see Common parameters. For more information about the request format, see the Examples section in this topic.

    Response elements

    Element

    Type

    Description

    Example

    object

    GroupUuid

    string

    The unique ID of the address book that is created.

    f04ac7ce-628b-4cb7-be61-310222b7****
    RequestId

    string

    The request ID.

    CBF1E9B7-D6A0-4E9E-AD3E-2B47E6C2****

    Examples

    Success response

    JSON format

    {
  "GroupUuid": "f04ac7ce-628b-4cb7-be61-310222b7****",
  "RequestId": "CBF1E9B7-D6A0-4E9E-AD3E-2B47E6C2****"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 ErrorParametersGroupType The group type is invalid. The group type is invalid.
    400 ErrorParametersUid The aliUid parameter is invalid. The aliUid parameter is invalid.
    400 ErrorParametersGroupAddress The IP address of the address group is invalid. The IP address of the address group is invalid.
    400 ErrorDBSelect An error occurred while querying database. An error occurred while querying database.
    400 ErrorAddressCountExceed The maximum number of addresses is exceeded. The maximum number of address is exceeded.
    400 ErrorAddressGroupExist The address group already exists. The address group already exists.
    400 ErrorParamDomain The parameter Domain is invalid. The parameter Domain is invalid.
    400 ErrorUUIDNew The UUID is invalid. The UUID is invalid.
    400 ErrorAddressGroupCountExceed The maximum number of address group is exceeded. The maximum number of address group is exceeded.
    400 ErrorDBInsert An error occurred while performing an insert operation in the database. An error occurred while performing an insert operation in the database.
    400 ErrorRecordLog An error occurred while updating the operation log. An error occurred while updating the operation log.
    400 ErrorDBUpdate internal error: sql updat. An error occurred while updating the database.
    400 ErrorParametersTagKey The tag key is invalid. The TagKey parameter is invalid.
    400 ErrorParametersTagList The tag list is invalid. The tag list is invalid.
    400 ErrorTagCountExceed The maximum number of tag is exceeded. The maximum number of tag is exceeded.
    400 ErrorParametersTagRelation The tag relation is invalid. The TagRelation parameter is invalid.
    400 ErrorParametersGroupPort The group port is invalid. The group port is invalid.
    400 ErrorPortCountExceed The maixmum number of port in the group is exceeded. The maixmum number of port in the group is exceeded.
    400 InternalError The request processing has failed due to some unknown error. Request processing failed due to some unknown error.
    400 ErrorAckClusterConnectorBusy The ACK cluster connector is operating. The ACK cluster connector is operating.
    404 ErrorAckClusterConnectorNotFound The specified resource ACK cluster connector is not found. The specified resource ACK cluster connector is not found.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.