@groundcover/api-client

中文文档
0.82.0发布于 2026/11/16Apache-2.0TypeScriptES Module近 30 天下载 8603

地面覆盖类型Script API 客户端

中文使用文档
文档目录9 节
  1. 所需资源
  2. 安装
  3. 快速启动
  4. 配置
  5. 监视器( YAML)
  6. 处理错误
  7. 重试行为
  8. 发展
  9. 许可证

地盖类型SDK

正式类型SDK 地面覆盖 API (英语).

所需资源

  • 节点.js (>= 18.0.0)
  • 阿宝 (>= 1.0.0)
  • 德诺 页:1
  • 一个地面封面 API 密钥和后端 ID

安装

# npm
npm install @groundcover/api-client

# yarn
yarn add @groundcover/api-client

# pnpm
pnpm add @groundcover/api-client

# bun
bun add @groundcover/api-client

# deno
deno add npm:@groundcover/api-client

快速启动

import { initClient } from '@groundcover/api-client';
import { metricsQuery } from '@groundcover/api-client';

// Initialize the client
// Uses GC_API_KEY and GC_BACKEND_ID from environment by default
const client = initClient();

async function run() {
  const now = new Date();
  const start = new Date(now.getTime() - 60 * 60 * 1000);

  const result = await metricsQuery({
    client,
    body: {
      Promql: 'up',
      QueryType: 'instant',
      Start: start.toISOString(),
      End: now.toISOString(),
      Step: '1m',
    },
  });

  console.log(result.data);
}

run();

SDK提供 已键入 API 函数 作为主界面. 导入操作模块并使用 client数字 :

import { searchLogs } from '@groundcover/api-client';

const result = await searchLogs({
  client,
  body: {
    start: start.toISOString(),
    end: now.toISOString(),
    query: '* | stats count(*)',
  },
});

原始 HTTP 方法( 缩写)client.get(), (中文(简体) ), client.post()(a) 继续提供 高级使用大小写或端点尚未作为键入函数可用.

配置

SDK默认从环境变量中读取:

变量说明需求
GC_API_KEY您的地标 API 密钥对
GC_BACKEND_ID您的后端标识对
GC_BASE_URLAPI 基础 URL( 默认 ): https://api.groundcover.com(中文(简体) )没有
GC_TRACEPARENT用于跟踪的默认跟踪父头没有

您也可以明确通过配置 :

const client = initClient({
  apiKey: 'your-api-key',
  backendId: 'your-backend-id',
  baseUrl: 'https://api.groundcover.com',
  timeout: 60000,
  maxRetries: 5,
});

监视器( YAML)

监视端点返回YAML内容类型. SDK提供方便包装 getMonitorParsed 将 YAML 响应自动解析为 JavaScript 对象 :

import { getMonitorParsed, createMonitor, updateMonitor } from '@groundcover/api-client';

// Fetch and automatically parse YAML to a JS object
const { data: monitorObj, error } = await getMonitorParsed({ client, path: { id: 'monitor-id' } });

// Create or update using standard JS objects
// (Since JSON is a valid subset of YAML, the standard client correctly serializes your object)
await createMonitor({ 
  client, 
  body: { name: 'My Monitor', type: 'logs' } 
});

await updateMonitor({ 
  client, 
  path: { id: 'monitor-id' }, 
  body: updatedMonitorObj 
});

处理错误

所有请求——既输入了API呼叫,又输入了原始的HTTP方法——返回 a error 如果请求失败,则在结果中标出对象:

import { getDashboard } from '@groundcover/api-client';

const result = await getDashboard({
  client,
  path: { id: 'nonexistent' }
});

if (result.error) {
  console.error(`API error:`, result.error);
} else {
  console.log(result.data);
}

重试行为

默认情况下, SDK 重试了 idepotent 请求 (GET, (中文(简体) ), HEAD, (中文(简体) ), OPTIONS, (中文(简体) ), TRACE在HTTP 429和503上带有指数后退和焦急:

  • 默认重试: 3个
  • 默认重试状态: 429 503 (中文(简体) )
  • 备份: 以时速、 1分、 最大 30分表示

发展

已发布的客户端仍在Node.js 18+上运行. 使用的维特/维特工具链 页:1 pnpm test:unit 需要节点20.19+或22.12+(Vite 8 / Vitest 4.

cd sdk-typescript
pnpm install

# Run unit tests
pnpm test:unit

# Run e2e tests
pnpm test:e2e

# Run linting
pnpm lint

# Format code
pnpm format

许可证

Apache 2.0 — 见 自由主义。 。 。 .

版本与发布记录

@groundcover/api-client 共发布 79 个版本,首次发布于 2026/08/10;过去 12 个月发布了 79 个版本。

版本发布日期距今
0.82.0latest2026/11/16今天
0.81.02026/11/16今天
0.80.02026/11/134 天前
0.79.02026/11/124 天前
0.78.02026/11/115 天前
0.77.02026/11/106 天前

关于 @groundcover/api-client 的常见问题

@groundcover/api-client 是什么?

地面覆盖类型Script API 客户端

如何安装 @groundcover/api-client?

在项目目录运行 npm install @groundcover/api-client,或使用 pnpm add / yarn add / bun add。

@groundcover/api-client 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@groundcover/api-client 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@groundcover/api-client 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@groundcover/api-client 可以商用吗?

@groundcover/api-client 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@groundcover/api-client 的下载量有多少?

根据 npm 官方下载统计,@groundcover/api-client 在 2026/10/17 – 2026/11/15 这 30 天内被下载 8,603 次,日均约 287 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@groundcover/api-client 还在维护吗?

最新版本 0.82.0 发布于 2026/11/16(今天);至今共发布 79 个版本,其中过去 12 个月发布了 79 个;首次发布于 2026/08/10。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。