OpenAPI SDK¶

OpenAPI SDK 用于在不同开发语言中调用观测云 Open API。SDK 会按模块封装接口，并处理 URL 拼接、DF-API-KEY 认证、请求参数编码、公共响应结构和 SDK 错误。

当前 SDK 列表提供 GitHub 仓库入口，可按开发语言选择对应 SDK。

开发语言	SDK	说明
Python	Python SDK	Python SDK for 观测云 OpenAPI
JavaScript / TypeScript	JavaScript / TypeScript SDK	Node.js 18+ / TypeScript SDK
Java	Java SDK	Java SDK for 观测云 OpenAPI
PHP	PHP SDK	PHP 8.1+ SDK

快速开始¶

按以下步骤准备后，即可使用 SDK 调用 Open API。

1 确认权限¶

创建和管理 API Key 需要拥有工作空间的管理员或 Owner 权限。建议按最小权限原则给 API Key 选择角色，避免使用超过实际需要的权限。

2 创建 API Key¶

进入观测云工作空间。
点击左侧导航栏管理 > API Key 管理。
点击右上角新建 Key。
配置名称、角色和备注。
创建成功后，进入 API Key 详情页，复制 Key（密钥）。

详细说明见 API Keys 管理。

3 选择 Open API Endpoint¶

SDK 初始化时需要传入 Open API Endpoint。常用 SaaS Endpoint 如下：

https://openapi.guance.com

更多站点 Endpoint 见概述。私有部署版以实际部署的 Endpoint 为准。

4 设置环境变量¶

建议先把 Endpoint 和 API Key 写入环境变量，后续各语言示例都可直接复用。

export DF_OPENAPI_ENDPOINT="https://openapi.guance.com"
export DF_API_KEY="替换为你的 API Key"

5 选择语言并准备 SDK¶

PythonJavaScript / TypeScriptJavaPHP

git clone https://github.com/GuanceCloud/guance-sdk-py.git
cd guance-sdk-py
python3 -m pip install -e .

git clone https://github.com/GuanceCloud/guance-sdk-js.git
cd guance-sdk-js
node --version

SDK 仓库内已包含 dist 产物。集成到业务项目时，可按仓库 README 使用 @guance/openapi-sdk。

git clone https://github.com/GuanceCloud/guance-sdk-java.git
cd guance-sdk-java
mvn test

如需安装到本地 Maven 仓库，可执行：

mvn install

git clone https://github.com/GuanceCloud/guance-sdk-php.git
cd guance-sdk-php
composer dump-autoload

6 初始化 Client¶

初始化 Client 时，至少需要传入 Endpoint 和 API Key。

PythonJavaScript / TypeScriptJavaPHP

import os
from guance_openapi_sdk import Client

client = Client(
    api_key=os.environ["DF_API_KEY"],
    base_url=os.environ["DF_OPENAPI_ENDPOINT"],
    timeout=30,
)

import { Client } from "@guance/openapi-sdk";

const client = new Client({
  apiKey: process.env.DF_API_KEY,
  baseUrl: process.env.DF_OPENAPI_ENDPOINT,
  timeoutMs: 30_000,
});

Client client = new Client(
    System.getenv("DF_OPENAPI_ENDPOINT"),
    System.getenv("DF_API_KEY")
);

PHP 命名空间应与所安装的 SDK 包保持一致，use 语句中的代码标识符无需翻译。

<?php

use Guance\OpenAPI\Client;

$client = new Client(
    baseUrl: getenv('DF_OPENAPI_ENDPOINT'),
    apiKey: getenv('DF_API_KEY'),
    timeoutSeconds: 30,
);

第一次调用¶

建议第一次调用选择只读接口，例如“获取仪表板列表”。这个接口对应 Open API 文档中的仪表板列表获取：

GET /api/v1/dashboards/list?pageIndex=1&pageSize=10

SDK 调用时，只需要传入业务参数；DF-API-KEY 会由 SDK 自动放入请求头。

PythonJavaScript / TypeScriptJavaPHP

response = client.board.list(query={"pageIndex": 1, "pageSize": 10})

print(response.content)
print(response.page_info)
print(response.trace_id)

const response = await client.board.list({
  query: { pageIndex: 1, pageSize: 10 },
});

console.log(response.content);
console.log(response.pageInfo);
console.log(response.traceId);

ApiResponseEnvelope response = client.board.list(
    RequestOptions.withQuery(Map.of("pageIndex", 1, "pageSize", 10))
);

System.out.println(response.contentJson);
System.out.println(response.pageInfo);
System.out.println(response.traceId);

$response = $client->board->list([
    'query' => ['pageIndex' => 1, 'pageSize' => 10],
]);

var_dump($response->content);
var_dump($response->pageInfo);
var_dump($response->traceId);

如果调用成功，响应中的 success 为 true，code 为 200，业务数据位于 content。

参数怎么填¶

阅读每个接口文档时，先看接口标题下方的请求方法和路径，再看参数所在位置。Open API 仅使用 GET 和 POST 两种请求方式：GET 用于数据查询和获取，POST 用于创建、修改、删除等数据变更。

接口文档中的参数位置	SDK 参数	示例
Query 请求参数	`query`	`{"pageIndex": 1, "pageSize": 10}`
路由参数	`path`	`{"dashboard_uuid": "dsbd_xxxx32"}`
Body 请求参数	`body`	`{"name": "demo workspace"}`
附加请求头	`headers`	`{"X-Source": "internal-tool"}`

Query 参数¶

Query 参数会被编码到 URL 查询字符串中。以获取仪表板列表为例：

GET /api/v1/dashboards/list?pageIndex=1&pageSize=10

PythonJavaScript / TypeScriptJavaPHP

response = client.board.list(query={"pageIndex": 1, "pageSize": 10})

const response = await client.board.list({
  query: { pageIndex: 1, pageSize: 10 },
});

ApiResponseEnvelope response = client.board.list(
    RequestOptions.withQuery(Map.of("pageIndex", 1, "pageSize", 10))
);

$response = $client->board->list([
    'query' => ['pageIndex' => 1, 'pageSize' => 10],
]);

路由参数¶

路由参数会替换接口路径中的变量。以获取指定仪表板为例：

GET /api/v1/dashboards/{dashboard_uuid}/get

PythonJavaScript / TypeScriptJavaPHP

response = client.board.get(path={"dashboard_uuid": "dsbd_xxxx32"})

const response = await client.board.get({
  path: { dashboard_uuid: "dsbd_xxxx32" },
});

RequestOptions req = RequestOptions.create();
req.path.put("dashboard_uuid", "dsbd_xxxx32");
ApiResponseEnvelope response = client.board.get(req);

$response = $client->board->get([
    'path' => ['dashboard_uuid' => 'dsbd_xxxx32'],
]);

Body 参数¶

Body 参数用于 POST 请求。以修改当前工作空间为例：

POST /api/v1/workspace/modify

PythonJavaScript / TypeScriptJavaPHP

response = client.workspace.modify(body={"name": "demo workspace"})

const response = await client.workspace.modify({
  body: { name: "demo workspace" },
});

RequestOptions req = RequestOptions.create();
req.bodyJson = "{\"name\":\"demo workspace\"}";
ApiResponseEnvelope response = client.workspace.modify(req);

$response = $client->workspace->modify([
    'body' => ['name' => 'demo workspace'],
]);

响应怎么看¶

Open API 使用统一响应结构。常用字段如下：

字段	说明
`code`	返回的状态码，与 HTTP 状态码保持相同，无错误时固定为 `200`
`content`	业务数据，具体类型由接口决定
`pageInfo`	列表接口的分页信息
`errorCode`	错误状态码，空表示无错误
`message`	错误说明
`success`	接口调用是否成功
`traceId`	请求追踪 ID，用于排查问题

列表接口通常同时返回 content 和 pageInfo。例如 pageInfo.totalCount 表示符合条件的总数据量。

错误怎么处理¶

SDK 会把 Open API 错误包装成对应语言的异常类型。排查问题时，优先查看 HTTP 状态码、errorCode、message 和 traceId。

PythonJavaScript / TypeScriptJavaPHP

from guance_openapi_sdk import ApiError

try:
    response = client.board.list(query={"pageIndex": 1, "pageSize": 10})
except ApiError as error:
    print(error.status)
    print(error.error_code)
    print(error.trace_id)
    print(error.envelope)

import { ApiError } from "@guance/openapi-sdk";

try {
  const response = await client.board.list({
    query: { pageIndex: 1, pageSize: 10 },
  });
} catch (error) {
  if (error instanceof ApiError) {
    console.log(error.status, error.errorCode, error.traceId);
    console.log(error.envelope);
  }
}

try {
    ApiResponseEnvelope response = client.board.list(
        RequestOptions.withQuery(Map.of("pageIndex", 1, "pageSize", 10))
    );
} catch (ApiException error) {
    System.out.println(error.httpStatus);
    System.out.println(error.errorCode);
    System.out.println(error.traceId);
    System.out.println(error.envelope.rawBody);
}

use Guance\OpenAPI\ApiException;

try {
    $response = $client->board->list([
        'query' => ['pageIndex' => 1, 'pageSize' => 10],
    ]);
} catch (ApiException $error) {
    echo $error->httpStatus . PHP_EOL;
    echo $error->errorCode . PHP_EOL;
    echo $error->traceId . PHP_EOL;
}

常见错误和限制：

场景	说明
API Key 无效	返回 `ft.InvalidAPIKey`
API Key 级别限流	同一 API Key 每分钟最多请求 200 次，触发后返回 `ft.TriggerApiAkCurrentLimiting`
工作空间级别限流	同一工作空间每分钟最多支持 1000 次 Open API 调用，触发后返回 `ft.TriggerApiWorkspaceCurrentLimiting`

更多说明见公共响应结构、公共错误定义和使用限制。

查询数据示例¶

如果需要查询指标、日志、事件等数据，可使用 DQL 数据查询接口。DQL 语法说明见 DQL 查询，接口说明见 DQL 数据查询。

以下示例查询 cpu 指标：

PythonJavaScript / TypeScriptJavaPHP

response = client.query_data.query_data_v1(body={
    "queries": [
        {
            "qtype": "dql",
            "query": {
                "q": "M::`cpu`:(avg(`usage_idle`))",
                "timeRange": [1708911106000, 1708912906999],
                "interval": 10,
                "maxPointCount": 720,
                "tz": "Asia/Shanghai",
            },
        }
    ],
    "fieldTagDescNeeded": False,
})

print(response.content)

const response = await client.queryData.queryDataV1({
  body: {
    queries: [
      {
        qtype: "dql",
        query: {
          q: "M::`cpu`:(avg(`usage_idle`))",
          timeRange: [1708911106000, 1708912906999],
          interval: 10,
          maxPointCount: 720,
          tz: "Asia/Shanghai",
        },
      },
    ],
    fieldTagDescNeeded: false,
  },
});

console.log(response.content);

RequestOptions req = RequestOptions.create();
req.bodyJson = """
{
  "queries": [
    {
      "qtype": "dql",
      "query": {
        "q": "M::`cpu`:(avg(`usage_idle`))",
        "timeRange": [1708911106000, 1708912906999],
        "interval": 10,
        "maxPointCount": 720,
        "tz": "Asia/Shanghai"
      }
    }
  ],
  "fieldTagDescNeeded": false
}
""";

QueryDataContent content = client.queryData.queryDataV1Content(req);
System.out.println(content.data);

$response = $client->queryData->queryDataV1([
    'body' => [
        'queries' => [[
            'qtype' => 'dql',
            'query' => [
                'q' => 'M::`cpu`:(avg(`usage_idle`))',
                'timeRange' => [1708911106000, 1708912906999],
                'interval' => 10,
                'maxPointCount' => 720,
                'tz' => 'Asia/Shanghai',
            ],
        ]],
        'fieldTagDescNeeded' => false,
    ],
]);

var_dump($response->content);

注意

Open API 进行数据查询时默认为管理员角色，仍可能受到数据访问规则限制。

排查清单¶

如果第一次调用失败，可按以下顺序检查：

DF_OPENAPI_ENDPOINT 是否为当前站点对应的 Open API 地址；
DF_API_KEY 是否填写的是 API Key 详情页中的 Key（密钥），不是 Key ID；
API Key 所属工作空间是否就是要查询或修改的工作空间；
API Key 角色是否拥有目标接口所需权限；
Query、Path、Body 参数是否放到了对应的 SDK 参数中；
列表接口是否设置了合理的 pageIndex 和 pageSize；
是否触发 API Key 或工作空间级别限流；
报错信息中的 traceId 是否已记录，便于后续排查。

OpenAPI SDK¶

快速开始¶

1 确认权限¶

2 创建 API Key¶

3 选择 Open API Endpoint¶

4 设置环境变量¶

5 选择语言并准备 SDK¶

6 初始化 Client¶

第一次调用¶

参数怎么填¶

Query 参数¶

路由参数¶

Body 参数¶

响应怎么看¶

错误怎么处理¶

查询数据示例¶

排查清单¶

相关文档¶

文档内容是否对您有帮助？

OpenAPI SDK¶

快速开始¶

1 确认权限¶

2 创建 API Key¶

3 选择 Open API Endpoint¶

4 设置环境变量¶

5 选择语言并准备 SDK¶

6 初始化 Client¶

第一次调用¶

参数怎么填¶

Query 参数¶

路由参数¶

Body 参数¶

响应怎么看¶

错误怎么处理¶

查询数据示例¶

排查清单¶

相关文档¶

文档内容是否对您有帮助？ ×

文档内容是否对您有帮助？