API & SDK 操作指南

一. SDK下载

Java SDK（推荐）。

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

其他语言 SDK。

• Go SDK：支持完整功能。

• Python SDK：支持完整功能。

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

• NodeJS SDK：支持完整功能。

2. 客户端初始化

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

// 配置访问凭证
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
    .setAccessKeyId(System.getenv("AK"))
    .setAccessKeySecret(System.getenv("SK"))
    .setSecurityToken(System.getenv("SecurityToken"));

// 设置endpoint
// 线上环境：cms.[RegionId].aliyuncs.com
// 预发环境：cms-pre.cn-hangzhou.aliyuncs.com
config.endpoint = "cms-pre.cn-hangzhou.aliyuncs.com";

Client client = new Client(config);

3. 环境配置说明

1. 创建Workspace

String workspaceName = "my-umodel-workspace";

// 创建Workspace请求
PutWorkspaceRequest putWorkspaceRequest = new PutWorkspaceRequest();
putWorkspaceRequest.setSlsProject(workspaceName);
putWorkspaceRequest.setDescription("UModel测试工作空间");

try {
    PutWorkspaceResponse response = client.putWorkspace(workspaceName, putWorkspaceRequest);
    System.out.println("Workspace创建成功：" + response.getBody());
} catch (Exception e) {
    System.err.println("创建失败：" + e.getMessage());
}

2. 查询Workspace

try {
    // 获取特定Workspace
    GetWorkspaceResponse getResponse = client.getWorkspace(workspaceName);
    System.out.println("Workspace信息：" + getResponse.getBody());
    
    // 列出所有Workspace
    ListWorkspacesRequest listRequest = new ListWorkspacesRequest();
    listRequest.setMaxResults(10);
    listRequest.setWorkspaceName("my-umodel"); // 模糊查询
    
    ListWorkspacesResponse listResponse = client.listWorkspaces(listRequest);
    System.out.println("Workspace列表：" + listResponse.getBody());
    
} catch (Exception e) {
    System.err.println("查询失败：" + e.getMessage());
}

3. 删除Workspace

try {
    DeleteWorkspaceResponse deleteResponse = client.deleteWorkspace(workspaceName);
    System.out.println("删除成功：" + deleteResponse.getBody());
} catch (Exception e) {
    System.err.println("删除失败：" + e.getMessage());
}

1. UModel 数据新增/更新

// 准备UModel数据
List<Object> elementsData = new ArrayList<>();
// 这里添加具体的UModel定义数据...

UpsertUmodelRequest request = new UpsertUmodelRequest();
request.setMethod("upsert"); // 统一使用upsert方法
request.setElements(elementsData);

try {
    UpsertUmodelResponse response = client.upsertUmodel(workspaceName, request);
    System.out.println("UModel数据操作成功：" + JSONObject.toJSONString(response, true));
} catch (Exception e) {
    System.err.println("操作失败：" + e.getMessage());
}

2. UModel 数据删除

DeleteUmodelRequest deleteRequest = new DeleteUmodelRequest();
// 可选：按条件删除
deleteRequest.setDomain("apm");        // 特定域
deleteRequest.setKind("entity_set");   // 特定类型  
deleteRequest.setName("service");      // 特定名称
// 不设置表示删除全部

try {
    DeleteUmodelResponse response = client.deleteUmodel(workspaceName, deleteRequest);
    System.out.println("删除成功：" + JSONObject.toJSONString(response, true));
} catch (Exception e) {
    System.err.println("删除失败：" + e.getMessage());
}

3. UModel数据查询

UModel数据查询支持两种方式：ListData（列表查询）和GetRelatedData（关系查询）。

// 构建查询请求
Map<String, Object> content = new HashMap<>();
content.put("type", "node"); // 可选值：node | link | all，默认：all
content.put("offset", 0);
content.put("size", 200);
content.put("order", "asc");

// 设置过滤条件
Map<String, Object> filter = new HashMap<>();
filter.put("kinds", Arrays.asList("entity_set", "metric_set"));
filter.put("domains", Arrays.asList("apm", "acs"));
filter.put("names", Arrays.asList()); // 通常不需要设置

content.put("filter", filter);

// 发送请求
GetUmodelRequest getRequest = new GetUmodelRequest();
getRequest.setMethod("ListData");
getRequest.setContent(content);

try {
    GetUmodelResponse response = client.getUmodel(workspaceName, getRequest);
    System.out.println("查询结果：" + JSONObject.toJSONString(response, true));
} catch (Exception e) {
    System.err.println("查询失败：" + e.getMessage());
}

Map<String, Object> content = new HashMap<>();

// 设置起始节点
List<Map<String, String>> startNodes = new ArrayList<>();
Map<String, String> startNode1 = new HashMap<>();
startNode1.put("kind", "entity_set");
startNode1.put("domain", "apm");
startNodes.add(startNode1);

content.put("startNodes", startNodes);
content.put("depth", 2);         // 遍历深度，-1表示不限制
content.put("direction", "both"); // both | in | out

// 设置关联节点和边的过滤条件
Map<String, Object> filter = new HashMap<>();
Map<String, Object> relatedNode = new HashMap<>();
relatedNode.put("kinds", Arrays.asList("entity_set"));
relatedNode.put("domains", Arrays.asList("apm"));

Map<String, Object> relatedLink = new HashMap<>();
relatedLink.put("kinds", Arrays.asList("data_link"));

filter.put("relatedNode", relatedNode);
filter.put("relatedLink", relatedLink);
content.put("filter", filter);

GetUmodelRequest getRequest = new GetUmodelRequest();
getRequest.setMethod("GetRelatedData");
getRequest.setContent(content);

try {
    GetUmodelResponse response = client.getUmodel(workspaceName, getRequest);
    System.out.println("关系查询结果：" + JSONObject.toJSONString(response, true));
} catch (Exception e) {
    System.err.println("查询失败：" + e.getMessage());
}

1. 创建EntityStore

CreateEntityStoreRequest createRequest = new CreateEntityStoreRequest();
// EntityStore会自动创建 {workspace}__entity 和 {workspace}__topo 日志库

try {
    CreateEntityStoreResponse response = client.createEntityStore(workspaceName, createRequest);
    System.out.println("EntityStore创建成功：" + response.getBody());
} catch (Exception e) {
    System.err.println("创建失败：" + e.getMessage());
}

2. 查询EntityStore信息

try {
    GetEntityStoreResponse response = client.getEntityStore(workspaceName);
    System.out.println("EntityStore信息：" + response.getBody());
} catch (Exception e) {
    System.err.println("查询失败：" + e.getMessage());
}

3. EntityStore数据查询

EntityStore 支持多种查询方式：USearch 实体查询、Graph Query 图查询、UModel 模式查询等。

// 构建EntityStore查询请求
Map<String, Object> content = new HashMap<>();
content.put("query", ".entity with(domain='apm', type='apm.service', query='order-service')");
// 更多查询语法参见具体的查询文档

GetEntityStoreDataRequest request = new GetEntityStoreDataRequest();
request.setContent(content);

try {
    GetEntityStoreDataResponse response = client.getEntityStoreData(workspaceName, request);
    System.out.println("查询结果：" + response.getBody());
} catch (Exception e) {
    System.err.println("查询失败：" + e.getMessage());
}

4. 删除EntityStore

try {
    DeleteEntityStoreResponse response = client.deleteEntityStore(workspaceName);
    System.out.println("EntityStore删除成功：" + response.getBody());
} catch (Exception e) {
    System.err.println("删除失败：" + e.getMessage());
}

1. UModel资源管理

UModel 资源是 UModel 的元数据配置，控制 UModel 的行为和特性。

// 创建UModel资源
CreateUmodelRequest createUmodelRequest = new CreateUmodelRequest();
// 设置UModel配置...

try {
    CreateUmodelResponse response = client.createUmodel(workspaceName, createUmodelRequest);
    System.out.println("UModel资源创建成功：" + response.getBody());
} catch (Exception e) {
    System.err.println("创建失败：" + e.getMessage());
}

// 更新UModel资源
UpdateUmodelRequest updateRequest = new UpdateUmodelRequest();
// 设置更新内容...

try {
    UpdateUmodelResponse response = client.updateUmodel(workspaceName, updateRequest);
    System.out.println("UModel资源更新成功：" + response.getBody());
} catch (Exception e) {
    System.err.println("更新失败：" + e.getMessage());
}

2. CommonSchema管理

CommonSchema 是可复用的 UModel 模式定义，支持跨 Workspace 共享。

// 创建CommonSchema（需要使用inner SDK）
CreateUModelCommonSchemaRequest createSchemaRequest = new CreateUModelCommonSchemaRequest();
// 设置CommonSchema内容...

try {
    CreateUModelCommonSchemaResponse response = innerClient.createUModelCommonSchema(createSchemaRequest);
    System.out.println("CommonSchema创建成功：" + response.getBody());
} catch (Exception e) {
    System.err.println("创建失败：" + e.getMessage());
}

// 在Workspace中引用CommonSchema
UpsertUmodelCommonSchemaRefRequest refRequest = new UpsertUmodelCommonSchemaRefRequest();
// 设置引用配置...

try {
    UpsertUmodelCommonSchemaRefResponse response = client.upsertUmodelCommonSchemaRef(workspaceName, refRequest);
    System.out.println("CommonSchema引用成功：" + response.getBody());
} catch (Exception e) {
    System.err.println("引用失败：" + e.getMessage());
}

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);

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

// 使用分页查询大量数据
public void queryAllUModelData(String workspace) {
    int offset = 0;
    int pageSize = 100;
    boolean hasMore = true;
    
    while (hasMore) {
        Map<String, Object> content = new HashMap<>();
        content.put("offset", offset);
        content.put("size", pageSize);
        
        GetUmodelRequest request = new GetUmodelRequest();
        request.setMethod("ListData");
        request.setContent(content);
        
        try {
            GetUmodelResponse response = client.getUmodel(workspace, request);
            // 处理当前页数据...
            
            // 检查是否还有更多数据
            hasMore = checkHasMore(response);
            offset += pageSize;
            
        } catch (Exception e) {
            System.err.println("查询失败：" + e.getMessage());
            break;
        }
    }
}

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));
}