用途
Telnyx Networking - Java 是 Telnyx 官方提供的 Java SDK 技能示例集合，面向需要在 Java 应用中调用 Telnyx 网络相关 API 的开发者。它通过可复制的代码片段，展示如何配置私有网络、WireGuard VPN 网关、互联网网关与虚拟交叉连接，以及如何管理 Global IP、健康检查、集成连接和 AI 聚类等资源。
安装与初始化
该技能使用 Telnyx Java SDK，版本为 6.89.0。
Maven 依赖：
<dependency>
<groupId>com.telnyx.sdk</groupId>
<artifactId>telnyx</artifactId>
<version>6.89.0</version>
</dependency>
Gradle 依赖：
implementation("com.telnyx.sdk:telnyx:6.89.0")
客户端初始化：
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
文档中所有示例均假设 client 已按上述方式初始化。
错误处理
所有 API 调用都可能因网络错误、速率限制（429）、校验错误（422）或认证错误（401）而失败。生产代码中应始终处理错误：
import com.telnyx.sdk.errors.TelnyxServiceException;
try {
var result = client.messages().send(params);
} catch (TelnyxServiceException e) {
System.err.println("API error " + e.statusCode() + ": " + e.getMessage());
if (e.statusCode() == 422) {
System.err.println("Validation error — check required fields and formats");
} else if (e.statusCode() == 429) {
// Rate limited — wait and retry with exponential backoff
Thread.sleep(1000);
}
}
常见错误码：401 无效 API key，403 权限不足，404 资源未找到，422 校验错误（检查字段格式），429 速率受限（使用指数退避重试）。
分页
列表方法返回一页数据。可使用 .autoPager() 自动迭代：for (var item : page.autoPager()) { ... }。如需手动控制，可使用 .hasNextPage() 与 .nextPage()。
主要能力与示例
AI 聚类
- 列出所有聚类：
GET /ai/clusters，返回 bucket、created_at、finished_at、min_cluster_size、min_subcluster_size、status（pending、starting、running、completed、failed）、task_id。 - 计算新聚类：
POST /ai/clusters，必填 bucket，可选 files、min_cluster_size、min_subcluster_size、prefix，返回 task_id。 - 获取聚类：
GET /ai/clusters/{task_id}，返回 bucket、clusters、status。 - 删除聚类：
DELETE /ai/clusters/{task_id}。 - 获取聚类可视化：
GET /ai/clusters/{task_id}/graph。
集成
- 列出所有可用集成：
GET /ai/integrations，返回 available_tools、description、display_name、id、logo_url、name、status（disconnected、connected）。 - 列出用户集成连接：
GET /ai/integrations/connections，返回 allowed_tools、id、integration_id。 - 按 ID 获取用户集成连接：
GET /ai/integrations/connections/{user_connection_id}。 - 删除集成连接：
DELETE /ai/integrations/connections/{user_connection_id}。 - 按 ID 获取集成详情：
GET /ai/integrations/{integration_id}。
Global IP 允许端口
- 列出所有 Global IP 允许端口：
GET /global_ip_allowed_ports，返回 first_port、id、last_port、name、protocol_code、record_type。
Global IP 分配健康检查指标
- 获取指标：
GET /global_ip_assignment_health，返回 global_ip、global_ip_assignment、health、timestamp。
Global IP 分配
- 列出所有分配：
GET /global_ip_assignments，返回 created_at、global_ip_id、id、is_announced、is_connected、is_in_maintenance、record_type、status（created、provisioning、provisioned、deleting）、updated_at、wireguard_peer_id。 - 创建分配：
POST /global_ip_assignments。 - 获取分配：
GET /global_ip_assignments/{id}。 - 更新分配：
PATCH /global_ip_assignments/{id}。 - 删除分配：
DELETE /global_ip_assignments/{id}。
Global IP 分配用量指标
- 获取用量：
GET /global_ip_assignments_usage，返回 global_ip、global_ip_assignment、received、timestamp、transmitted。
Global IP 健康检查类型
- 列出所有类型：
GET /global_ip_health_check_types，返回 health_check_params、health_check_type、record_type。
Global IP 健康检查
- 列出所有健康检查：
GET /global_ip_health_checks，返回 created_at、global_ip_id、health_check_params、health_check_type、id、record_type、updated_at。 - 创建健康检查：
POST /global_ip_health_checks。 - 获取健康检查：
GET /global_ip_health_checks/{id}。 - 删除健康检查：
DELETE /global_ip_health_checks/{id}。
Global IP 延迟指标
- 获取延迟：
GET /global_ip_latency，返回 global_ip、mean_latency、percentile_latency、prober_location、timestamp。
Global IP 协议
- 列出所有协议：
GET /global_ip_protocols，返回 code、name、record_type。
Global IP 用量指标
- 获取用量：
GET /global_ip_usage，返回 global_ip、received、timestamp、transmitted。
Global IP
- 列出所有 Global IP：
GET /global_ips，返回 created_at、description、id、ip_address、name、ports、record_type、updated_at。 - 创建 Global IP：
POST /global_ips。 - 获取 Global IP：
GET /global_ips/{id}。
适用场景
适用于需要在 Java 后端服务、自动化脚本或运维工具中集成 Telnyx 网络能力的场景，例如管理 Global IP 及其分配、配置健康检查与监控指标、查询延迟与用量数据，以及通过 AI 聚类分析存储桶中的数据主题与模式。
限制
资料中未提供私有网络、WireGuard VPN 网关、互联网网关与虚拟交叉连接的具体 API 示例代码，仅说明该技能涵盖这些能力。收费、价格、平台支持范围等信息暂未提供。