API & SDK 操作指南

一. SDK下载

Java SDK：

<!-- Maven依赖 -->
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>cms20240330</artifactId>
    <version>${latest}</version>
</dependency>

Python SDK：

pip install alibabacloud_cms20240330

其他语言 SDK。

• Go SDK：支持完整功能。

• C++ SDK：支持完整功能。

• NodeJS SDK：支持完整功能。

2. 客户端初始化

Java 案例：

import com.aliyun.cms20240330.Client;
import com.aliyun.cms20240330.models.*;

// 配置客户端
Config config = new Config()
        .setAccessKeyId(accessKeyId)
        .setAccessKeySecret(accessKeySecret)
        .setEndpoint("cms.cn-hangzhou.aliyuncs.com");

Client client = new Client(config);

Python 案例：

from alibabacloud_cms20240330.client import Client
from alibabacloud_tea_openapi.models import Config
from alibabacloud_cms20240330 import models as cms_models

# 配置客户端
config_model = open_api_models.Config(
    access_key_id=access_key_id,
    access_key_secret=access_key_secret,
    endpoint='cms.cn-hangzhou.aliyuncs.com'
)

client = Client(config_model)

3. 环境配置说明

1. 创建Workspace

// 创建workspace
PutWorkspaceRequest createWorkspaceRequest = new PutWorkspaceRequest()
       .setSlsProject(SLS_PROJECT_NAME)
       .setDescription("test workspace")
       .setDisplayName("test_workspace");
PutWorkspaceResponse workspaceResponse = client.putWorkspace(WORKSPACE_NAME, createWorkspaceRequest);
System.out.println("Create workspace: " + workspaceResponse.getStatusCode() + " " + JSONObject.toJSONString(workspaceResponse));

from alibabacloud_cms20240330.client import Client
from alibabacloud_cms20240330 import models as cms_models

# 创建workspace
create_workspace_request = cms_models.PutWorkspaceRequest(
    sls_project=SLS_PROJECT_NAME,
    description="test workspace",
    display_name="test_workspace"
)
response = client.put_workspace(WORKSPACE_NAME, create_workspace_request)
print(f"Create workspace: {response}")

2. 查询Workspace

// get workspace
GetWorkspaceResponse getWorkspaceResponse = client.getWorkspace(WORKSPACE_NAME);
System.out.println("Get workspace: " + getWorkspaceResponse.getStatusCode()  + " " + JSONObject.toJSONString(getWorkspaceResponse));

// list workspaces
ListWorkspacesRequest listWorkspacesRequest = new ListWorkspacesRequest()
       .setMaxResults(10)
       .setWorkspaceName("test");
ListWorkspacesResponse listWorkspacesResponse = client.listWorkspaces(listWorkspacesRequest);
System.out.println("List workspaces: " + listWorkspacesResponse.getStatusCode() + " " + JSONObject.toJSONString(listWorkspacesResponse));

# get workspace
response = client.get_workspace(WORKSPACE_NAME)
print(f"Get workspace: {response}")

# list workspaces
response = client.list_workspaces(cms_models.ListWorkspacesRequest(
    max_results=10,
    workspace_name='test'
))
print(f"List workspaces: {response}")

3. 删除Workspace

// delete workspace
DeleteWorkspaceResponse deleteWorkspaceResponse = client.deleteWorkspace(WORKSPACE_NAME);
System.out.println("Delete workspace: " + deleteWorkspaceResponse.getStatusCode() + " " + JSONObject.toJSONString(deleteWorkspaceResponse));

# delete workspace
response = client.delete_workspace(WORKSPACE_NAME)
print(f"Delete workspace: {response}")

UModel 资源管理

注意：创建UModel资源时，会同时创建EntityStore资源。

// create umodel
try {
   CreateUmodelRequest createUmodelRequest = new CreateUmodelRequest()
           .setDescription("test umodel");
   CreateUmodelResponse createUmodelResponse = client.createUmodel(WORKSPACE_NAME, createUmodelRequest);
   System.out.println("Create umodel: " + createUmodelResponse.getStatusCode() + " " + JSONObject.toJSONString(createUmodelResponse));
} catch (TeaException e) {
   System.out.println("Create umodel error: " + e.getMessage());
}

// get umodel
try {
   GetUmodelResponse getUmodelResponse = client.getUmodel(WORKSPACE_NAME);
   System.out.println("Get umodel: " + getUmodelResponse.getStatusCode() + " " + JSONObject.toJSONString(getUmodelResponse));
} catch (TeaException e) {
   System.out.println("Get umodel error: " + e.getMessage());
}

// delete umodel
try {
   DeleteUmodelResponse deleteUmodelResponse = client.deleteUmodel(WORKSPACE_NAME);
   System.out.println("Delete umodel: " + deleteUmodelResponse.getStatusCode() + " " + JSONObject.toJSONString(deleteUmodelResponse));
} catch (TeaException e) {
   System.out.println("Delete umodel error: " + e.getMessage());
}

from Tea.exceptions import TeaException
# create umodel
try:
    response = client.create_umodel(WORKSPACE_NAME, cms_models.CreateUmodelRequest(
        description="test umodel"
    ))
    print(f"Create umodel: {response.status_code} {response.body}")
except TeaException as e:
    print(f"Create umodel error: {e}")

# get umodel
try:
    response = client.get_umodel(WORKSPACE_NAME)
    print(f"Get umodel: {response.status_code} {response.body}")
except TeaException as e:
    print(f"Get umodel error: {e}")

# delete umodel
try:
    response = client.delete_umodel(WORKSPACE_NAME)
    print(f"Delete umodel: {response.status_code} {response.body}")
except TeaException as e:
    print(f"Delete umodel error: {e}")

EntityStore 资源管理

注意：若希望删除EntityStore资源，需要首先调用DeleteUmodel接口。

// create entitystore
try {
   CreateEntityStoreResponse createEntityStoreResponse = client.createEntityStore(WORKSPACE_NAME);
   System.out.println("Create entitystore: " + createEntityStoreResponse.getStatusCode() + " " + JSONObject.toJSONString(createEntityStoreResponse));
} catch (TeaException e) {
   System.out.println("Create entitystore error: " + e.getMessage());
}

// get entitystore
try {
   GetEntityStoreResponse getEntityStoreResponse = client.getEntityStore(WORKSPACE_NAME);
   System.out.println("Get entitystore: " + getEntityStoreResponse.getStatusCode() + " " + JSONObject.toJSONString(getEntityStoreResponse));
} catch (TeaException e) {
   System.out.println("Get entitystore error: " + e.getMessage());
}

// delete entitystore
try {
   DeleteEntityStoreResponse deleteEntityStoreResponse = client.deleteEntityStore(WORKSPACE_NAME);
   System.out.println("Delete entitystore: " + deleteEntityStoreResponse.getStatusCode() + " " + JSONObject.toJSONString(deleteEntityStoreResponse));
} catch (TeaException e) {
   System.out.println("Delete entitystore error: " + e.getMessage());
}

# create entitystore
try:
    response = client.create_entity_store(WORKSPACE_NAME)
    print(f"Create entitystore: {response.status_code} {response.body}")
except TeaException as e:
    print(f"Create entitystore error: {e}")
    
# get entitystore
try:
    response = client.get_entity_store(WORKSPACE_NAME)
    print(f"Get entitystore: {response.status_code} {response.body}")
except TeaException as e:
    print(f"Get entitystore error: {e}")

# delete entitystore
try:
    response = client.delete_entity_store(WORKSPACE_NAME)
    print(f"Delete entitystore: {response.status_code} {response.body}")
except TeaException as e:
        print(f"Delete entitystore error: {e}")

1. UModel 数据新增/更新

 // 读取 UModel elements 数据
String jsonFilePath = "src/main/java/org/example/data/functionTest.json";
List<Map<String, Object>> elementsData = loadUmodelElements(jsonFilePath);
System.out.println("load " + elementsData.size() + " umodel elements");

// upsert umodel
try {
    UpsertUmodelDataRequest upsertRequest = new UpsertUmodelDataRequest()
            .setMethod("upsert")
            .setElements(elementsData);
    UpsertUmodelDataResponse upsertResponse = client.upsertUmodelData(WORKSPACE_NAME, upsertRequest);
    System.out.println("Upsert umodel: " + upsertResponse.getStatusCode() + " " + JSONObject.toJSONString(upsertResponse));
} catch (TeaException e) {
    System.out.println("Upsert umodel error: " + e.getMessage());
}

# 读取 UModel elements 数据
json_file_path = "<your_data_path>"
elements_data = load_umodel_elements(json_file_path)
print(f"load {len(elements_data)} umodel elements")

# upsert umodel
try:
    response = client.upsert_umodel_data(WORKSPACE_NAME, cms_models.UpsertUmodelDataRequest(
        method="upsert",
        elements=elements_data
    ))
    print(f"Upsert umodel: {response.status_code} {response.body}")
except TeaException as e:
    print(f"Upsert umodel error: {e}")

2. UModel数据查询

// get umodel data
try {
  GetEntityStoreDataRequest getRequest = new GetEntityStoreDataRequest()
          .setFrom(1729224800)
          .setTo(1730273861)
          .setQuery(".umodel");
  GetEntityStoreDataResponse getResponse = client.getEntityStoreData(WORKSPACE_NAME, getRequest);
  System.out.println("Get umodel data: " + getResponse.getStatusCode() + " " + JSONObject.toJSONString(getResponse));
} catch (TeaException e) {
  System.out.println("Get umodel data error: " + e.getMessage());
}

# get umodel data
try:
    response = client.get_entity_store_data(WORKSPACE_NAME, cms_models.GetEntityStoreDataRequest(
        from_=1729224800,
        to=1730273861,
        query=f".umodel"
    ))
    print(f"Get umodel data: {response.status_code} {response.body}")
except TeaException as e:
    print(f"Get umodel data error: {e}")

这种查询方式是无条件查询 umodel。附带筛选条件、附加图查询等更高级的 umodel 查询请参见 UModel 查询文档。

3. UModel 数据删除

// delete umodel data
try {
    DeleteUmodelDataRequest deleteRequest = new DeleteUmodelDataRequest()
            .setDomain("custom")
            .setKind("entity_set")
            .setName("link1");
    DeleteUmodelDataResponse deleteResponse = client.deleteUmodelData(WORKSPACE_NAME, deleteRequest);
    System.out.println("Delete umodel data: " + deleteResponse.getStatusCode() + " " + JSONObject.toJSONString(deleteResponse));
} catch (TeaException e) {
    System.out.println("Delete umodel data error: " + e.getMessage());
}

# delete umodel data
try:
    response = client.delete_umodel_data(WORKSPACE_NAME, cms_models.DeleteUmodelDataRequest(
        domain="custom",
        kind="entity_set",
        name="link1"
    ))
    print(f"Delete umodel data: {response.status_code} {response.body}")
except TeaException as e:
    print(f"Delete umodel data error: {e}")

1. 异常处理模式

public class UModelOperationHelper {
    
    private final Client client;
    
    public UModelOperationHelper(Client client) {
        this.client = client;
    }
    
    public boolean safeCreateWorkspace(String workspaceName, String description) {
        try {
            PutWorkspaceRequest request = new PutWorkspaceRequest();
            request.setSlsProject(workspaceName);
            request.setDescription(description);
            
            PutWorkspaceResponse response = client.putWorkspace(workspaceName, request);
            
            // 检查响应状态
            if (response.getStatusCode() == 200) {
                System.out.println("Workspace创建成功：" + workspaceName);
                return true;
            } else {
                System.err.println("创建失败，状态码：" + response.getStatusCode());
                return false;
            }
            
        } catch (com.aliyun.teautil.models.RuntimeOptions.RuntimeException e) {
            System.err.println("运行时异常：" + e.getMessage());
            return false;
        } catch (Exception e) {
            System.err.println("未知异常：" + e.getMessage());
            return false;
        }
    }
}

2. 性能优化建议

// 批量创建UModel数据
List<Object> batchElements = new ArrayList<>();
// 添加多个元素到批次中...

UpsertUmodelRequest batchRequest = new UpsertUmodelRequest();
batchRequest.setMethod("upsert");
batchRequest.setElements(batchElements);

// 单次请求处理多个元素，提高效率

3. 调试技巧

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class UModelClient {
    private static final Logger logger = LoggerFactory.getLogger(UModelClient.class);
    
    private void logRequest(String operation, Object request) {
        if (logger.isDebugEnabled()) {
            logger.debug("执行操作: {}, 请求参数: {}", operation, 
                        JSONObject.toJSONString(request, true));
        }
    }
}

private void validateResponse(String operation, Object response) {
    if (response == null) {
        throw new RuntimeException(operation + " 返回空响应");
    }
    
    // 记录响应用于调试
    logger.info("{} 响应: {}", operation, JSONObject.toJSONString(response, true));
}