コンテンツにスキップ

OpenAPI SDK


OpenAPI SDK は、さまざまな開発言語で Guance Open API を呼び出すために使用します。SDK は API をモジュール単位でラップし、URL の組み立て、DF-API-KEY 認証、リクエストパラメータのエンコード、共通レスポンス構造、SDK エラーを処理します。

現在の SDK リストは GitHub リポジトリへの入口を提供しています。開発言語に応じて対応する SDK を選択できます。

開発言語 SDK 説明
Python Python SDK Guance OpenAPI 用 Python SDK
JavaScript / TypeScript JavaScript / TypeScript SDK Node.js 18+ / TypeScript SDK
Java Java SDK Guance OpenAPI 用 Java SDK
PHP PHP SDK PHP 8.1+ SDK

クイックスタート

以下の手順で準備すると、SDK を使用して Open API を呼び出せます。

1 権限の確認

API Key の作成と管理には、ワークスペースの管理者または Owner 権限が必要です。最小権限の原則に従い、API Key に付与するロールは実際に必要な権限の範囲に留めることをお勧めします。

2 API Key の作成

  1. Guance のワークスペースに移動します。
  2. 左側のナビゲーションバーで管理 > API Key 管理をクリックします。
  3. 右上隅の新規 Key をクリックします。
  4. 名前、ロール、備考を設定します。
  5. 作成が完了したら、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 の準備

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 を渡す必要があります。

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

最初の呼び出し

初回の呼び出しでは、読み取り専用の API(例:「ダッシュボードリスト取得」)を選択することをお勧めします。この API は、Open API ドキュメントの ダッシュボードリスト取得 に対応します:

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

SDK 呼び出し時は、ビジネスパラメータのみを渡します。DF-API-KEY は SDK が自動的にリクエストヘッダーに設定します。

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 に格納されます。

パラメータの指定方法

各 API ドキュメントを読むときは、まず API タイトル下のリクエストメソッドとパスを確認し、次にパラメータの位置を確認します。Open API は GET と POST の 2 種類のリクエストメソッドのみを使用します:GET はデータの照会・取得に、POST は作成・変更・削除などのデータ変更に使用します。

API ドキュメントでのパラメータ位置 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
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],
]);

ルートパラメータ

ルートパラメータは API パス内の変数を置き換えます。指定ダッシュボード取得 を例にします:

GET /api/v1/dashboards/{dashboard_uuid}/get
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
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 ビジネスデータ。具体的な型は API によって異なります
pageInfo リスト API のページネーション情報
errorCode エラーステータスコード。空の場合はエラーなしです
message エラーの説明
success API 呼び出しの成否
traceId リクエスト追跡 ID。問題の調査に使用します

リスト API は通常、content と pageInfo の両方を返します。たとえば、pageInfo.totalCount は条件に一致するデータの総数を示します。

エラーの処理方法

SDK は、Open API エラーを対応する言語の例外型にラップします。問題を調査するときは、まず HTTP ステータスコード、errorCode、message、traceId を確認してください。

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 データクエリ API を使用できます。DQL の構文は DQL クエリ、API の説明は DQL データクエリ を参照してください。

次の例では、cpu メトリクスを照会します:

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 でデータクエリを実行する場合、デフォルトは管理者ロールですが、データアクセスルールの制限を受ける場合があります。

トラブルシューティングチェックリスト

初回の呼び出しが失敗した場合は、次の順序で確認してください:

  1. DF_OPENAPI_ENDPOINT が現在のサイトに対応する Open API アドレスであること。
  2. DF_API_KEY に、API Key 詳細ページの Key(シークレット) を設定していること(Key ID ではないこと)。
  3. API Key が属するワークスペースが、照会または変更対象のワークスペースであること。
  4. API Key のロールが対象 API に必要な権限を持っていること。
  5. Query、Path、Body パラメータが対応する SDK パラメータに指定されていること。
  6. リスト API で適切な pageIndex と pageSize を設定していること。
  7. API Key またはワークスペースレベルのレート制限に達していないこと。
  8. エラー情報の traceId を記録していること(後続の調査に使用します)。

関連ドキュメント

フィードバック

このページは役に立ちましたか?