How to configure an endpoint in the Java async SDK-Alibaba Cloud SDK(Alibaba Cloud SDK)-阿里云帮助中心

When you call an Alibaba Cloud API, you must specify the correct service endpoint. Choose the endpoint closest to your workloads to reduce latency when creating resources. When you query, update, or delete a resource, use the endpoint for the resource's region, because resources are region-scoped and cross-region operations can cause access failures or data consistency issues.

Endpoint types

Endpoints fall into two types: public endpoints and VPC endpoints. If your workloads run in a VPC (for example, on ECS or ACK), use a VPC endpoint for better security and lower latency. For more information, see service endpoints.

Configuration methods

The SDK supports three configuration methods, in descending priority: RequestConfiguration > ClientOverrideConfiguration > AsyncClient. To find the endpoint for a specific service, see Appendix: Find an endpoint.

Method 1: Use RequestConfiguration

Set the endpoint with the endpointOverride parameter.

RequestConfiguration requestConfiguration = RequestConfiguration.create()
        .setEndpointOverride("<ENDPOINT>");

Apply the configuration to a specific API request object. For example, to set the endpoint for a DescribeInstances call:

DescribeInstancesRequest request = DescribeInstancesRequest.builder()
        .regionId("cn-hangzhou") // API request parameter
        .requestConfiguration(RequestConfiguration.create()
                .setEndpointOverride("ecs.cn-hangzhou.aliyuncs.com")) // endpoint
        .build();

Method 2: Use ClientOverrideConfiguration

Set the endpoint with the endpointOverride parameter.

ClientOverrideConfiguration clientOverrideConfiguration = ClientOverrideConfiguration.create()
        .setEndpointOverride("<ENDPOINT>"); // endpoint

Then pass the configuration to AsyncClient:

AsyncClient client = AsyncClient.builder()
                .credentialsProvider(credentialProvider) // The credentials provider. Implementation details are omitted.
                .overrideConfiguration(
                        ClientOverrideConfiguration.create()
                                .setEndpointOverride("<ENDPOINT>") // endpoint
                )
                .build();

Method 3: Automatic endpoint resolution

If no endpoint is explicitly configured, the SDK resolves one automatically when you set the region parameter on the client builder.

Note

If a service does not support the region ID you specify, the request might fail. Explicitly set the endpoint with Method 1 or Method 2 to avoid this.

The automatic addressing logic works as follows:

Most cloud product SDKs include an endpointMap that maps region IDs to endpoints. For example, the ECS SDK defines the following map:

{
    "ap-northeast-2-pop": "ecs.aliyuncs.com",
    "cn-beijing-finance-pop": "ecs.aliyuncs.com",
    "cn-beijing-gov-1": "ecs.aliyuncs.com",
    "cn-beijing-nu16-b01": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-edge-1": "ecs.cn-qingdao-nebula.aliyuncs.com",
    "cn-fujian": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-hangzhou": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-hangzhou-bj-b01": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-hangzhou-finance": "ecs.aliyuncs.com",
    "cn-hangzhou-internal-prod-1": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-hangzhou-internal-test-1": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-hangzhou-internal-test-2": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-hangzhou-internal-test-3": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-hangzhou-test-306": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-hongkong-finance-pop": "ecs.aliyuncs.com",
    "cn-huhehaote-nebula-1": "ecs.cn-qingdao-nebula.aliyuncs.com",
    "cn-north-2-gov-1": "ecs.aliyuncs.com",
    "cn-shanghai-et15-b01": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-shanghai-et2-b01": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-shanghai-finance-1": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-shanghai-inner": "ecs.aliyuncs.com",
    "cn-shanghai-internal-test-1": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-shenzhen-finance-1": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-shenzhen-inner": "ecs.aliyuncs.com",
    "cn-shenzhen-st4-d01": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-shenzhen-su18-b01": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-wuhan": "ecs.aliyuncs.com",
    "cn-yushanfang": "ecs.aliyuncs.com",
    "cn-zhangbei": "ecs.aliyuncs.com",
    "cn-zhangbei-na61-b01": "ecs-cn-hangzhou.aliyuncs.com",
    "cn-zhangjiakou-na62-a01": "ecs.cn-zhangjiakou.aliyuncs.com",
    "cn-zhengzhou-nebula-1": "ecs.cn-qingdao-nebula.aliyuncs.com",
    "eu-west-1-oxs": "ecs.cn-shenzhen-cloudstone.aliyuncs.com",
    "rus-west-1-pop": "ecs.aliyuncs.com"
}

The system checks for an endpointMap and, if one is not found, automatically constructs the Endpoint based on concatenation rules.
If endpointMap exists and contains a given RegionId, the Endpoint is the value that corresponds to that RegionId.
If the endpointMap does not contain the specified RegionId, an Endpoint is automatically generated based on the concatenation rules.

The concatenation rules are as follows:

For a regional product: <PRODUCT_CODE><ENDPOINT_TYPE>.<REGION_ID>.aliyuncs.com
For a central product: <PRODUCT_CODE><ENDPOINT_TYPE>.aliyuncs.com

In these patterns, <PRODUCT_CODE> is determined by the cloud product SDK, and <ENDPOINT_TYPE> distinguishes public from VPC endpoints.

AsyncClient client = AsyncClient.builder()
        .credentialsProvider(credentialProvider) // The credentials provider. Implementation details are omitted.
        .region("<REGION_ID>")
        .overrideConfiguration(
                ClientOverrideConfiguration.create()
                        // To get the VPC endpoint for the region ID, set this parameter to "vpc". By default, the public endpoint is used.
                        .setEndpointType("vpc")
        )
        .build();

Appendix: Find an endpoint

You can find the endpoint of a cloud service in theOpenAPI portal:

From the top menu of the portal, choose Products and select a product, such as ECS.
On the product homepage, find the list of service regions.
Select the endpoint that corresponds to your region ID, and then copy and paste it.
Alternatively, on the API debugging page, click Regions in the left-side navigation pane to view the endpoints supported by the cloud service.