# @groundcover/api-client 中文文档

规范地址：https://npmcn.com/package/%40groundcover/api-client/

版本：0\.82\.0
npm 元数据更新时间：2026-11-16T14:30:03.233Z
中文译文更新时间：2026-11-17T03:00:09.576Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40groundcover/api-client
原文对照：https://npmcn.com/package/%40groundcover/api-client/?lang=original
项目主页：https://github.com/groundcover-com/groundcover-sdk-typescript#readme
源码仓库：https://github.com/groundcover-com/groundcover-sdk-typescript

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，69 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：2 个
- 首次发布：2026-08-10T07:22:44.269Z
- 最新版本发布：2026-11-16T14:30:02.992Z
- 近 30 天下载量：8603（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：79（近 12 个月 79 个）

## 中文简介

地面覆盖类型Script API 客户端

## 安装

```sh
npm install @groundcover/api-client
```

也可以使用：`pnpm add @groundcover/api-client`、`yarn add @groundcover/api-client`、`bun add @groundcover/api-client`

## README

# 地盖类型SDK

正式类型SDK [地面覆盖](https://groundcover.com/) API (英语).

## 所需资源

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

## 安装

```bash
# 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
```

## 快速启动

```typescript
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`数字 :

```typescript
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_URL` | API 基础 URL( 默认 ): `https://api.groundcover.com`(中文(简体) ) | 没有 |
| `GC_TRACEPARENT` | 用于跟踪的默认跟踪父头 | 没有 |

您也可以明确通过配置 :

```typescript
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 对象 :

```typescript
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` 如果请求失败,则在结果中标出对象:

```typescript
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.

```bash
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 — 见 [自由主义](https://npmcn.com/package/%40groundcover/api-client/LICENSE)。 。 。 .

## 常见问题

### @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 和提交记录判断。

