コンテンツにスキップ

時系列トレンドチャートの取得



GET /api/v1/chart_image/get

概要

Client Token を使用して DQL または PromQL の時系列クエリを実行し、PNG トレンドチャートを直接ダウンロードします。

呼び出し前の確認と使用手順

このインターフェースは Client Token を使用してワークスペースを特定します。DF-API-KEY やログイン Token は不要です。URL 内の Token は適切に保管し、公開ページや共有リンクに書き込まないでください。データアクセスの識別情報はワークスペース API Key とは異なり、API Key のロール権限からこのインターフェースのアクセス制御を推測することはできません。まず対象ワークスペースで時系列文を検証し、スパンがサイトの制限を超えない実データの時間を選択してから、クエリパラメータを URL エンコードして画像をダウンロードします。例の時刻はあくまで参考です。呼び出し前にデータが存在する時間ウィンドウに置き換えてください。

レスポンス成功時は生の PNG バイナリであり、code/content/success/traceId などの JSON 業務フィールドはありません。エラー時は JSON が返る可能性があるため、クライアントは HTTP ステータス、Content-Type、PNG ファイル署名を同時に確認する必要があり、任意の 200 を有効な画像として保存してはいけません。描画失敗時はサーバー側ログに記録されますが、HTTP200、image/png、空の本文が返る可能性があります。空データでも空の座標図が得られることがあり、リクエスト失敗を意味するものではありません。本文が空の場合は、まず文、タイムゾーン、実際のデータを確認し、レスポンスヘッダー内のトレース情報を保持して管理者にフィードバックしてください。

パラメータ表に記載された Query のみをサポートします。内部的には showLegend の読み取りが存在しますが、公開仕様では開放されていないため、このパラメータは送信できません。デフォルトでは凡例を表示しません。結果はキャッシュされず、レスポンスには no-store が設定されます。Token 情報は本プロセスが依存する Redis に 60 秒間キャッシュされるため、失効後も短時間のキャッシュウィンドウが残る可能性があり、即時失効は保証されません。

Query リクエストパラメータ

パラメータ名 型 必須 説明
clientToken string Y 必須。有効状態が 0 の Client Token のみを対象とします。前後の空白は除去されます。Token により照会先のワークスペースが決まります。
null を許可: False
例: <CLIENT-TOKEN>
取得または入力方法: 現在のワークスペースのClient Token 管理から実際の Token 値をコピーします。Token レコードの UUID や API Key ではありません。
endTime integer Y 必須の整数。10 桁の秒値はミリ秒に変換され、それ以外はミリ秒として扱われます。0 の場合はサーバー側の現在時刻を使用します。最大スパンはサイトの ChartImageSet.maxTimeSc によって制約され、コードのデフォルトは 3600 秒で、管理者が上書きできます。
null を許可: False
例: 1785429000
取得または入力方法: クエリの終点を選択します。startTime 以上である必要があり、同じ単位を使用します。
interval integer 任意。デフォルトは 60 秒で、内部的に 1000 を乗算してクエリ間隔とします。0 の場合はスパンとサイトのポイント密度に基づいて計算され、最小は 1 ミリ秒です。負の値は 406 となります。実際のポイント数はクエリサービスとポイント密度の制限も受け、各ポイントにデータがあることは保証されません。
null を許可: False
例: 60
取得または入力方法: 画像に必要な粒度に応じて正の整数秒を選択します。自動推定の場合は 0 を渡します。
q string Y 必須のクエリ文。時間と数値を含むシーケンスを返す必要があります。DQL と PromQL の構文を混在させることはできません。Tag でグループ化すると複数のラインを生成できます。
null を許可: False
例: M::cpu:(avg(usage_idle)) BY host
取得または入力方法: 対象ワークスペースのクエリツールでデータが存在することを確認した時系列クエリを指定し、Query を URL エンコードします。
qtype string 任意。dql/promql。ダウンストリームでのデフォルト値の処理に依存しないよう、常に明示的に渡すことを推奨します。ルートにはデフォルト値が設定されていないため、省略するとクエリサービスに None が渡されます。
null を許可: False
選択可能な値: ['dql', 'promql']
例: dql
取得または入力方法: クエリ文の種類に応じて dql または promql を明示的に選択します。DQLとPromQLを参照してください。
startTime integer Y 必須の整数。10 桁の値は内部的に 1000 を乗算し、それ以外の桁数はミリ秒としてそのまま使用します。桁数判定に依存しないよう、秒で統一して渡すことを推奨します。0 の場合は endTime から 1 時間を減算した値をフォールバックとして使用し、Unix エポックではありません。
null を許可: False
例: 1785427200
取得または入力方法: 実際にデータが存在するクエリ開始点を選択し、Unix 秒のタイムスタンプを使用します。
tz string 任意。デフォルトは Asia/Shanghai。クエリのアライメントと画像の横軸表示を制御します。Unix タイムスタンプの意味は変更しません。タイムゾーンの列挙チェックはなく、誤った名前を指定するとダウンストリームのクエリが失敗したり、画像が空になったりする可能性があります。
null を許可: False
例: Asia/Shanghai
取得または入力方法: 業務上の表示タイムゾーンに応じて IANA タイムゾーン名を選択します。

パラメータ補足説明

クエリ説明


注意: 現在のインターフェースは clientToken による認証を行います。clientToken が有効な場合にのみ機能します。現在のインターフェースでは、リクエストヘッダー DF-API-KEY を追加しなくてもかまいません。

リクエスト例

curl --get 'https://openapi.guance.com/api/v1/chart_image/get' \
  --data-urlencode 'clientToken=<CLIENT-TOKEN>' \
  --data-urlencode qtype=dql \
  --data-urlencode 'q=M::cpu:(avg(usage_idle)) BY host' \
  --data-urlencode startTime=1785427200 \
  --data-urlencode endTime=1785429000 \
  --data-urlencode interval=60 \
  --data-urlencode tz=Asia/Shanghai \
  --output chart.png

レスポンス

HTTP 200 は生の PNG 画像ストリームです。エラーは通常 JSON で、描画失敗時も 200 と空の本文を返す可能性があるため、ステータス/タイプ/ファイル署名を確認する必要があります。

レスポンスヘッダー 型 説明
Content-Type string 成功時は image/png。異常時は実際の JSON またはプロキシのレスポンスタイプに従って処理します。
Cache-Control string 成功時は no-store, max-age=0 で、画像レスポンスはキャッシュされません。
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: no-store, max-age=0

<PNG バイナリ、ファイルヘッダーの16進数は 89 50 4e 47 0d 0a 1a 0a>

エラー応答

本エントリポイントは requireSignIn=false であり、DF-API-KEY の認証/ロールエラーは適用されません。リクエスト検証は引き続き適用されます。クエリサービスは、文、データソース、容量、ネットワークに関連する動的なエラーを返す可能性があり、HTTP ステータスとエラーコードは実際のレスポンスに従います。描画エラーでは 200 と空の PNG 本文のみが返る可能性があり、常に JSON エラーが返るとは限りません。

HTTP ステータス errorCode トリガー条件 メッセージまたはレスポンス説明 処理方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している パラメータ解析に失敗しました パラメータの位置、フィールド名、型、値を確認します。
406 ft.DqlParseError DQL 文の構文または解析構造が無効 dql parser の解析に失敗しました: {} まずクエリツールで文を検証し、正しく URL エンコードしたうえで、実際の解析原因を保持します。
406 ft.NotSupportedByGroupQuery BY index によるグループ化を使用 index フィールドによる by グループ化クエリはサポートされていません index のグループ化フィールドを削除し、実際の業務 Tag によるグループ化に変更します。
503 ft.QueryServiceUnavailable クエリ上流の HTTP503 が統一的にマッピングされる クエリサービスは一時的に利用できません。しばらくしてから再試行してください エラー本文の content.retryable を確認し、バックオフ後に読み取りを再試行してください。高頻度の再試行は避けてください。
404 ft.ClientTokenNotExistOrDelete Client Token が空白除去後に空である、またはキャッシュミスで有効な Token レコードが存在しない 指定された Client Token は存在しないか、削除されています 実際の Token 値と対象サイトを確認し、有効な Token を使用してください。レコードの UUID で代用することはできません。
400 ft.IllegalStartOrEndTime 終点が起点より早い、またはスパンがサイトの最大値を超えている 無効な開始/終了タイムスタンプ 同じ単位のタイムスタンプを使用し、許容範囲内に縮小してください。
406 ft.InvalidParameter interval が 0 未満 パラメータ interval が無効です 正の整数秒または自動推定の 0 に変更してください。
500 ft.InternalServerError キャッシュ/データベースが利用できない、返却データ構造が異常、またはその他の未捕捉エラー 内部エラー 返却された Content-Type と本文を確認し、traceId を保持して管理者に連絡してください。エラー JSON を PNG として扱わないでください。

フィードバック

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