Help Center/ Distributed Cache Service/ API Reference/ API V2/ Network Security/ Asynchronously Configuring IP Address Whitelist Groups
Updated on 2025-08-05 GMT+08:00

Asynchronously Configuring IP Address Whitelist Groups

Function

This API is used to configure IP address whitelist groups for a specific instance, including creating, disabling, editing, and deleting a whitelist. The ID of the asynchronous task is returned. New whitelist settings will overwrite the existing setting. Therefore, save the existing whitelist before you add a new one.

Calling Method

For details, see Calling APIs.

URI

PUT /v2/{project_id}/instance/{instance_id}/whitelist-async

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition:

Project ID. For details, see Obtaining a Project ID.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

instance_id

Yes

String

Definition:

Instance ID. It can be viewed on the instance details page on the DCS console.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

instance_id

No

String

Definition:

Instance ID.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

enable_whitelist

Yes

Boolean

Definition:

Whether to enable the whitelist.

Constraints:

N/A

Range:

true: Yes

false: No

Default Value:

N/A

whitelist

Yes

Array of Whitelist objects

Definition:

IP whitelist group. New whitelist settings will overwrite the existing setting. Therefore, save the existing whitelist before you add a new one.

Constraints:

N/A

Table 3 Whitelist

Parameter

Mandatory

Type

Description

group_name

Yes

String

Definition:

Whitelist group name.

Constraints:

Each instance supports four whitelist groups. The group name must be unique, contain more than four characters, and start with a letter. Only letters, digits, hyphens (-), and underscores (_) are allowed.

Range:

N/A

Default Value:

N/A

ip_list

Yes

Array of strings

Definition:

IP list in a whitelist group. Separate multiple IP addresses or IP address ranges with commas (,).

Constraints:

An instance's IPs must be unique. IP 0.0.0.0 and CIDP are not supported.

Range:

N/A

Default Value:

N/A

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

job_id

String

Definition:

ID of the task for setting an IP address whitelist.

Range:

N/A

Status code: 400

Table 5 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Status code: 401

Table 6 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Status code: 403

Table 7 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Status code: 404

Table 8 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Status code: 500

Table 9 Response body parameters

Parameter

Type

Description

error_msg

String

Definition:

Error message.

Range:

N/A

error_code

String

Definition:

Error code.

Range:

For details, see Error Codes.

error_ext_msg

String

Definition:

Extended error information. This parameter is not used currently and is set to null.

Range:

N/A

Example Requests

  • Enabling the whitelist and configuring IP addresses allowed to access the instance

    PUT https://{dcs_endpoint}/v2/{project_id}/instance/{instance_id}/whitelist-async
    
    {
      "enable_whitelist" : true,
      "whitelist" : [ {
        "group_name" : "test001",
        "ip_list" : [ "10.10.10.1", "10.10.10.2" ]
      } ]
    }
  • Enabling the whitelist and configuring subnet masks allowed to access the instance

    PUT https://{dcs_endpoint}/v2/{project_id}/instance/{instance_id}/whitelist-async
    
    {
      "enable_whitelist" : true,
      "whitelist" : [ {
        "group_name" : "test",
        "ip_list" : [ "10.56.0.0/16" ]
      } ]
    }

Example Responses

Status code: 200

Definition:

IP whitelist groups configured successfully.

{
  "job_id" : "job_id"
}

SDK Sample Code

The SDK sample code is as follows.

  • Enabling the whitelist and configuring IP addresses allowed to access the instance

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    package com.huaweicloud.sdk.test;
    
    import com.huaweicloud.sdk.core.auth.ICredential;
    import com.huaweicloud.sdk.core.auth.BasicCredentials;
    import com.huaweicloud.sdk.core.exception.ConnectionException;
    import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
    import com.huaweicloud.sdk.core.exception.ServiceResponseException;
    import com.huaweicloud.sdk.dcs.v2.region.DcsRegion;
    import com.huaweicloud.sdk.dcs.v2.*;
    import com.huaweicloud.sdk.dcs.v2.model.*;
    
    import java.util.List;
    import java.util.ArrayList;
    
    public class UpdateIpWhitelistAsyncSolution {
    
        public static void main(String[] args) {
            // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
            // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
            String ak = System.getenv("CLOUD_SDK_AK");
            String sk = System.getenv("CLOUD_SDK_SK");
            String projectId = "{project_id}";
    
            ICredential auth = new BasicCredentials()
                    .withProjectId(projectId)
                    .withAk(ak)
                    .withSk(sk);
    
            DcsClient client = DcsClient.newBuilder()
                    .withCredential(auth)
                    .withRegion(DcsRegion.valueOf("<YOUR REGION>"))
                    .build();
            UpdateIpWhitelistAsyncRequest request = new UpdateIpWhitelistAsyncRequest();
            request.withInstanceId("{instance_id}");
            ModifyIpWhitelistBody body = new ModifyIpWhitelistBody();
            List<String> listWhitelistIpList = new ArrayList<>();
            listWhitelistIpList.add("10.10.10.1");
            listWhitelistIpList.add("10.10.10.2");
            List<Whitelist> listbodyWhitelist = new ArrayList<>();
            listbodyWhitelist.add(
                new Whitelist()
                    .withGroupName("test001")
                    .withIpList(listWhitelistIpList)
            );
            body.withWhitelist(listbodyWhitelist);
            body.withEnableWhitelist(true);
            request.withBody(body);
            try {
                UpdateIpWhitelistAsyncResponse response = client.updateIpWhitelistAsync(request);
                System.out.println(response.toString());
            } catch (ConnectionException e) {
                e.printStackTrace();
            } catch (RequestTimeoutException e) {
                e.printStackTrace();
            } catch (ServiceResponseException e) {
                e.printStackTrace();
                System.out.println(e.getHttpStatusCode());
                System.out.println(e.getRequestId());
                System.out.println(e.getErrorCode());
                System.out.println(e.getErrorMsg());
            }
        }
    }
    
  • Enabling the whitelist and configuring subnet masks allowed to access the instance

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    package com.huaweicloud.sdk.test;
    
    import com.huaweicloud.sdk.core.auth.ICredential;
    import com.huaweicloud.sdk.core.auth.BasicCredentials;
    import com.huaweicloud.sdk.core.exception.ConnectionException;
    import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
    import com.huaweicloud.sdk.core.exception.ServiceResponseException;
    import com.huaweicloud.sdk.dcs.v2.region.DcsRegion;
    import com.huaweicloud.sdk.dcs.v2.*;
    import com.huaweicloud.sdk.dcs.v2.model.*;
    
    import java.util.List;
    import java.util.ArrayList;
    
    public class UpdateIpWhitelistAsyncSolution {
    
        public static void main(String[] args) {
            // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
            // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
            String ak = System.getenv("CLOUD_SDK_AK");
            String sk = System.getenv("CLOUD_SDK_SK");
            String projectId = "{project_id}";
    
            ICredential auth = new BasicCredentials()
                    .withProjectId(projectId)
                    .withAk(ak)
                    .withSk(sk);
    
            DcsClient client = DcsClient.newBuilder()
                    .withCredential(auth)
                    .withRegion(DcsRegion.valueOf("<YOUR REGION>"))
                    .build();
            UpdateIpWhitelistAsyncRequest request = new UpdateIpWhitelistAsyncRequest();
            request.withInstanceId("{instance_id}");
            ModifyIpWhitelistBody body = new ModifyIpWhitelistBody();
            List<String> listWhitelistIpList = new ArrayList<>();
            listWhitelistIpList.add("10.56.0.0/16");
            List<Whitelist> listbodyWhitelist = new ArrayList<>();
            listbodyWhitelist.add(
                new Whitelist()
                    .withGroupName("test")
                    .withIpList(listWhitelistIpList)
            );
            body.withWhitelist(listbodyWhitelist);
            body.withEnableWhitelist(true);
            request.withBody(body);
            try {
                UpdateIpWhitelistAsyncResponse response = client.updateIpWhitelistAsync(request);
                System.out.println(response.toString());
            } catch (ConnectionException e) {
                e.printStackTrace();
            } catch (RequestTimeoutException e) {
                e.printStackTrace();
            } catch (ServiceResponseException e) {
                e.printStackTrace();
                System.out.println(e.getHttpStatusCode());
                System.out.println(e.getRequestId());
                System.out.println(e.getErrorCode());
                System.out.println(e.getErrorMsg());
            }
        }
    }
    
  • Enabling the whitelist and configuring IP addresses allowed to access the instance

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    # coding: utf-8
    
    import os
    from huaweicloudsdkcore.auth.credentials import BasicCredentials
    from huaweicloudsdkdcs.v2.region.dcs_region import DcsRegion
    from huaweicloudsdkcore.exceptions import exceptions
    from huaweicloudsdkdcs.v2 import *
    
    if __name__ == "__main__":
        # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak = os.environ["CLOUD_SDK_AK"]
        sk = os.environ["CLOUD_SDK_SK"]
        projectId = "{project_id}"
    
        credentials = BasicCredentials(ak, sk, projectId)
    
        client = DcsClient.new_builder() \
            .with_credentials(credentials) \
            .with_region(DcsRegion.value_of("<YOUR REGION>")) \
            .build()
    
        try:
            request = UpdateIpWhitelistAsyncRequest()
            request.instance_id = "{instance_id}"
            listIpListWhitelist = [
                "10.10.10.1",
                "10.10.10.2"
            ]
            listWhitelistbody = [
                Whitelist(
                    group_name="test001",
                    ip_list=listIpListWhitelist
                )
            ]
            request.body = ModifyIpWhitelistBody(
                whitelist=listWhitelistbody,
                enable_whitelist=True
            )
            response = client.update_ip_whitelist_async(request)
            print(response)
        except exceptions.ClientRequestException as e:
            print(e.status_code)
            print(e.request_id)
            print(e.error_code)
            print(e.error_msg)
    
  • Enabling the whitelist and configuring subnet masks allowed to access the instance

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    # coding: utf-8
    
    import os
    from huaweicloudsdkcore.auth.credentials import BasicCredentials
    from huaweicloudsdkdcs.v2.region.dcs_region import DcsRegion
    from huaweicloudsdkcore.exceptions import exceptions
    from huaweicloudsdkdcs.v2 import *
    
    if __name__ == "__main__":
        # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak = os.environ["CLOUD_SDK_AK"]
        sk = os.environ["CLOUD_SDK_SK"]
        projectId = "{project_id}"
    
        credentials = BasicCredentials(ak, sk, projectId)
    
        client = DcsClient.new_builder() \
            .with_credentials(credentials) \
            .with_region(DcsRegion.value_of("<YOUR REGION>")) \
            .build()
    
        try:
            request = UpdateIpWhitelistAsyncRequest()
            request.instance_id = "{instance_id}"
            listIpListWhitelist = [
                "10.56.0.0/16"
            ]
            listWhitelistbody = [
                Whitelist(
                    group_name="test",
                    ip_list=listIpListWhitelist
                )
            ]
            request.body = ModifyIpWhitelistBody(
                whitelist=listWhitelistbody,
                enable_whitelist=True
            )
            response = client.update_ip_whitelist_async(request)
            print(response)
        except exceptions.ClientRequestException as e:
            print(e.status_code)
            print(e.request_id)
            print(e.error_code)
            print(e.error_msg)
    
  • Enabling the whitelist and configuring IP addresses allowed to access the instance

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    package main
    
    import (
    	"fmt"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
        dcs "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2/model"
        region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2/region"
    )
    
    func main() {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak := os.Getenv("CLOUD_SDK_AK")
        sk := os.Getenv("CLOUD_SDK_SK")
        projectId := "{project_id}"
    
        auth := basic.NewCredentialsBuilder().
            WithAk(ak).
            WithSk(sk).
            WithProjectId(projectId).
            Build()
    
        client := dcs.NewDcsClient(
            dcs.DcsClientBuilder().
                WithRegion(region.ValueOf("<YOUR REGION>")).
                WithCredential(auth).
                Build())
    
        request := &model.UpdateIpWhitelistAsyncRequest{}
    	request.InstanceId = "{instance_id}"
    	var listIpListWhitelist = []string{
            "10.10.10.1",
    	    "10.10.10.2",
        }
    	var listWhitelistbody = []model.Whitelist{
            {
                GroupName: "test001",
                IpList: listIpListWhitelist,
            },
        }
    	request.Body = &model.ModifyIpWhitelistBody{
    		Whitelist: listWhitelistbody,
    		EnableWhitelist: true,
    	}
    	response, err := client.UpdateIpWhitelistAsync(request)
    	if err == nil {
            fmt.Printf("%+v\n", response)
        } else {
            fmt.Println(err)
        }
    }
    
  • Enabling the whitelist and configuring subnet masks allowed to access the instance

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    package main
    
    import (
    	"fmt"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
        dcs "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2/model"
        region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/dcs/v2/region"
    )
    
    func main() {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak := os.Getenv("CLOUD_SDK_AK")
        sk := os.Getenv("CLOUD_SDK_SK")
        projectId := "{project_id}"
    
        auth := basic.NewCredentialsBuilder().
            WithAk(ak).
            WithSk(sk).
            WithProjectId(projectId).
            Build()
    
        client := dcs.NewDcsClient(
            dcs.DcsClientBuilder().
                WithRegion(region.ValueOf("<YOUR REGION>")).
                WithCredential(auth).
                Build())
    
        request := &model.UpdateIpWhitelistAsyncRequest{}
    	request.InstanceId = "{instance_id}"
    	var listIpListWhitelist = []string{
            "10.56.0.0/16",
        }
    	var listWhitelistbody = []model.Whitelist{
            {
                GroupName: "test",
                IpList: listIpListWhitelist,
            },
        }
    	request.Body = &model.ModifyIpWhitelistBody{
    		Whitelist: listWhitelistbody,
    		EnableWhitelist: true,
    	}
    	response, err := client.UpdateIpWhitelistAsync(request)
    	if err == nil {
            fmt.Printf("%+v\n", response)
        } else {
            fmt.Println(err)
        }
    }
    

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

200

Definition:

IP whitelist groups configured successfully.

400

Definition:

Invalid request.

401

Definition:

Authentication failed.

403

Definition:

Request rejected.

404

Definition:

Incorrect path.

500

Definition:

Internal error.

Error Codes

See Error Codes.