Configure endpoints
When you use the V2.0 SDK to call an OpenAPI operation, you must configure the endpoint of the target Alibaba Cloud service. When you create a resource, select the endpoint of the region that is physically closest to your business to reduce network latency and improve response speed. When you query, update, or delete a resource, select the endpoint of the region where the resource resides, because resource storage is region-specific and a cross-region operation may fail or introduce data consistency risks. This topic describes how to configure endpoints in the V2.0 SDK.
Endpoint types
Endpoints fall into two categories: public endpoints and VPC endpoints. If your business is deployed in a VPC, such as on ECS or ACK, you can access cloud resources in that VPC over a VPC endpoint. VPC endpoints improve security and reduce network latency. For more information, see Endpoints.
Set an endpoint
The V2.0 SDK provides two ways to set an endpoint: specify an endpoint, or specify a region ID to obtain the endpoint automatically.
Method 1: Specify an endpoint (recommended)
You can specify the endpoint when you initialize the client object of a cloud service. Both public endpoints and VPC endpoints are supported.
The following sample shows only the endpoint-related configuration:
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
// Set the endpoint.
config.setEndpoint("<ENDPOINT>");Method 2: Specify a region ID
If you do not specify an endpoint, you can specify a region ID when you initialize the client object of a cloud service. The SDK then resolves the corresponding endpoint automatically.
The addressing logic is as follows:
Most cloud service SDKs define an endpointMap that maps region IDs to endpoints. For example, the endpointMap in the ECS SDK is as follows:
{
"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-haidian-cm12-c01": "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"
}-
If no
endpointMapexists, the SDK constructs the endpoint based on the construction rules. -
If the
endpointMapexists and contains the specified region ID, the endpoint is the value mapped to that region ID. -
If the
endpointMapdoes not contain the specified region ID, the SDK constructs the endpoint based on the construction rules.
The construction rules are as follows:
-
Regionalized services:
<PRODUCT_CODE><SUFFIX><NET_WORK>.<REGION_ID>.aliyuncs.com -
Centralized services:
<PRODUCT_CODE><SUFFIX><NET_WORK>.aliyuncs.com
The deployment type and <PRODUCT_CODE> are determined by the cloud service SDK that you use. Specify the other three parameters based on your scenario:
-
<SUFFIX>: the suffix in a VPC endpoint. Specify this parameter based on the suffix in the VPC endpoint of the cloud service. Do not add a hyphen (-). -
<NET_WORK>: the endpoint type. A public endpoint is used by default. Valid values:-
vpc: obtains the VPC endpoint of the service. -
intranet: when you use the Simple Log Service SDK (sls20201230), obtains the VPC endpoint of Simple Log Service. -
accelerate: when you use the Simple Log Service SDK (sls20201230), obtains the transfer acceleration endpoint of Simple Log Service.
-
-
<REGION_ID>: the region where the resource resides.
VPC endpoint formats vary widely. To configure a VPC endpoint, specify the endpoint with Method 1 instead of constructing it from a region ID.
The following sample shows only the endpoint-related configuration:
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
// Specify the region ID.
config.setRegionId("<REGION_ID>");
config.setNetwork("<NET_WORK>"); // You do not need to set this parameter for a public endpoint. For a VPC endpoint, set it to vpc.
config.setSuffix("<SUFFIX>"); // You do not need to set this parameter for a public endpoint. For a VPC endpoint, specify it based on the suffix in the VPC endpoint of the cloud service and do not add a hyphen (-).Appendix: Find an endpoint
You can find the endpoint of a cloud service in the OpenAPI 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.