This topic describes the basic information and usage notes for calling ApsaraDB for ClickHouse API operations.
Overview of OpenAPI Explorer
Alibaba Cloud provides OpenAPI Explorer for you to efficiently understand and use the API operations of various Alibaba Cloud services. OpenAPI Explorer integrates the following features for API operations: intelligent search, documentation, online debugging, SDK obtaining, sample code, call error diagnostics, and call statistics. In OpenAPI Explorer, you can call API operations of Alibaba Cloud services and view API requests and responses. In addition, OpenAPI Explorer automatically generates the corresponding SDK sample code to facilitate the use of Alibaba Cloud services. For more information, see What is an API?
Version description
Alibaba Cloud APIs use version numbers to manage the API operations of ApsaraDB for ClickHouse clusters with different architectures. You can select proper APIs based on your cluster edition.
Version number | Description |
2019-11-11 | API operations of this version are suitable for Community-compatible Edition clusters. |
2023-05-22 | API operations of this version are suitable for Enterprise Edition clusters. |
Online debugging
ApsaraDB for ClickHouse provides features such as API debugging in OpenAPI Explorer. Before you call API operations, you must understand the following information provided by ApsaraDB for ClickHouse: versions, endpoints, and integration methods.
API debugging URLs
The API debugging URLs of ApsaraDB for ClickHouse Community-compatible Edition and Enterprise Edition are different. You need to select a proper URL based on your cluster edition.
Edition | Description |
Community-compatible Edition | API debugging URL of ApsaraDB for ClickHouse Community-compatible Edition |
Enterprise Edition | API debugging URL of ApsaraDB for ClickHouse Enterprise Edition |
Endpoint description
You can select an endpoint based on the region where your resource resides to reduce latency. If ApsaraDB for ClickHouse resides in the China (Zhangjiakou) region, the public endpoint is clickhouse.cn-zhangjiakou.aliyuncs.com, and the virtual private cloud (VPC) endpoint is clickhouse-vpc.cn-zhangjiakou.aliyuncs.com.
Public endpoints can be globally accessed.
VPCs are isolated from each other. Each VPC corresponds to a virtual network. VPC endpoints have the following benefits:
Higher security: VPC endpoints are accessible only within the corresponding VPCs. This provides higher security and privacy.
Faster response: VPC endpoints use the internal network environment to deliver faster responses than public endpoints. In addition, you are free from issues such as network latency and bandwidth limits.
Lower cost: VPC endpoints are accessed over an internal network.
For more information, see Endpoints.
Supported user identities
After you log on to OpenAPI Explorer by using your Alibaba Cloud account, OpenAPI Explorer uses your Alibaba Cloud account to perform online debugging by default. An Alibaba Cloud account has permissions on all API operations. Security risks may arise if you use an Alibaba Cloud account to debug API operations online. We recommend that you use a RAM user to call API operations or perform routine O&M. Before you call API operations as a RAM user, grant the required permissions to the RAM user based on your business requirements. Make sure that the RAM user has the management permissions on ApsaraDB for ClickHouse. For more information, see RAM authorization.
Identity | Supported |
Yes | |
RAM user (recommended) | Yes |
RAM role (recommended) | Yes |
Integration methods
ApsaraDB for ClickHouse provides the following integration methods: Alibaba Cloud SDKs, Terraform, Resource Orchestration Service (ROS), and custom encapsulation. You can select an integration method based on your business requirements.
SDKs are the most recommended method to call API operations because SDKs can be easily integrated.
Integration method | Supported |
Alibaba Cloud SDKs | Yes |
Alibaba Cloud CLI | No |
Terraform | No |
ROS | Partially supported |
Custom encapsulation | Yes |
Alibaba Cloud SDKs
Alibaba Cloud provides SDKs in multiple programming languages, such as Java, C#, Go, Python, Node.js, TypeScript, PHP, and C++. SDKs free you from considering the implementation details of API operations, and standardize the identity, authentication, and signing rules. You need to only integrate SDKs and use the SDKs to directly call API operations. For more information about Alibaba Cloud SDKs, see Alibaba Cloud SDKs.
Alibaba Cloud SDKs can be used to call API operations of ApsaraDB for ClickHouse. For more information about the supported programming languages and dependency installation, see SDK overview.
Alibaba Cloud CLI
Alibaba Cloud CLI allows you to use
aliyuncommands in the CLI shell to interact with Alibaba Cloud services and manage cloud service resources. For more information about Alibaba Cloud CLI, see What is Alibaba Cloud CLI?Alibaba Cloud CLI cannot be used to call API operations of ApsaraDB for ClickHouse.
Terraform
Terraform is a secure and efficient open source tool used to preview, configure, and manage cloud infrastructures and resources. Terraform works in a similar way as ROS. Terraform calls API operations by interpreting templates. For more information, see What is Terraform?
Terraform cannot be used to call API operations of ApsaraDB for ClickHouse.
ROS
ROS is an Alibaba Cloud service that can simplify the management of cloud computing resources. You can create templates to define the required Alibaba Cloud resources such as Elastic Compute Service (ECS) and ApsaraDB RDS instances, and dependency relationships between the resources. The ROS engine automatically creates and configures all resources in a stack based on a template to implement automated deployment and O&M. For more information, see What is ROS?
ROS can be used to call API operations of ApsaraDB for ClickHouse. For more information about the resources and data sources supported by ROS, see Resources supported by ROS.
Custom encapsulation
You can encapsulate API requests based on your business requirements to call API operations. To make native HTTP calls, you must create custom requests and sign the requests. For more information about the signature mechanism, see Request syntax and signature method V3.
Usage notes
If an error is returned after you call an API operation, check whether the request parameters and the parameter values are valid based on the returned error code. For more information, see ApsaraDB for ClickHouse - Error Codes.
You can also perform self-service diagnostics based on the returned request ID or SDK error information on the OpenAPI problem diagnostics page.