OpenAPI SDK¶

OpenAPI SDK は、さまざまな開発言語で Guance Open API を呼び出すために使用されます。SDK はモジュールごとにインターフェースをカプセル化し、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 の作成¶

Guance ワークスペースにアクセスします。
左側のナビゲーションバーで管理 > 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

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 の 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

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 で 1 分間に最大 200 リクエスト。トリガーされると `ft.TriggerApiAkCurrentLimiting` を返します。
ワークスペースレベルのレート制限	同一ワークスペースで 1 分間に最大 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 パラメータ¶

レスポンスの見方¶

エラーの処理方法¶

データクエリの例¶

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

関連ドキュメント¶

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

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