ForHosting KIT · 開発者向けツール

目標マイルストーン進捗グラフ用データを作成

目標の現在地を、マイルストーンと進捗グラフにそのまま使える一貫したデータへ変換できます。開始値、最新の現在値、目標値、表示したいマイルストーンの達成率を指定してください。実際の進捗率、グラフ表示向けに範囲内へ収めた位置、到達済みのマイルストーン、残っている場合は次のマイルストーン、さらに並び替え済みの描画点が返されます。数値を増やす目標だけでなく、不具合件数、支出、応答時間などを減らす目標にも同じ方法で対応します。

● Beta無料・ブラウザ内で実行

無料で実行 API仕様を見る

ご利用方法ウェブAPIメールTelegramアプリ近日

明確な開始地点を含めて目標を定義します

意味のある進捗率を求めるには、現在値と目標値だけでなく、開始値を含む3つの値が必要です。開始値が0パーセント、目標値が100パーセントを定め、現在値が最新の位置を示します。作業がゼロ以外の基準から始まる場合、この違いは特に重要です。たとえばスコアを20から100へ上げる目標では、60が行程の半分です。現在のスコアが60だからといって、進捗がそのまま60パーセントになるわけではありません。各値を数値で入力し、0から100までのマイルストーン達成率を少なくとも1つ指定してください。マイルストーンの順序は問いません。重複する達成率は統合され、グラフ向けに昇順のきれいな系列へ整えられます。開始値と目標値は異なる必要があります。両者が同じだと区間の長さがゼロになり、意味のある比率を計算できないためです。この場合は、無限値や任意の割合、見かけだけ正しいデータではなく、型付きの入力エラーを返します。1回のリクエストで指定できる項目は最大100件で、詳細な計画に対応しながら処理量と出力量を確実に制限します。

増加目標と減少目標を同じ基準で判定します

どちらの方向にも同じ式を使用します。開始地点から進んだ距離を、開始値から目標値までの全距離で割って進捗を求めます。目標値が開始値より大きければ増加目標、小さければ減少目標として示されます。そのため、インシデントを100件から20件へ減らす場合も、負の結果ではなく正しい前進として扱われます。返される実際の進捗率には、意図的に上限と下限を設けていません。0未満なら開始地点より悪化した状態、100を超えれば目標を上回った成果を表せます。一方、表示用のchart_progress_percentageと現在点のchart_percentageは、0から100の範囲に収めます。マイルストーンの到達判定には、範囲を制限していない真の進捗を使います。正規化された各マイルストーンには、達成率、目標区間上の対応値、到達済みかどうかが含まれます。到達済みの件数と達成率も返し、未達の項目があれば次のマイルストーンを示します。すべて達成済みの場合、この任意項目はnullではなく省略されます。

返された点をグラフや状況表示に利用します

chart_points配列には、開始点、正規化された各マイルストーンの点、目標点が順番に格納されます。各レコードは種類、達成率、値、到達状態を持つため、折れ線グラフ、進捗トラック、時系列マーカー、アクセシブルな文章による要約に利用できます。current_pointは実際の現在値と制限前の進捗率を保持しながら、グラフ用に範囲内へ収めた座標も提供します。この分離により、遅れや目標超過があるときはマーカーをグラフ端に安全に描画し、ラベルやツールチップには正確な数値を表示できます。バッジ、達成メッセージ、監査イベントにはreached_milestone_percentagesを使い、配列を再検索せず次の段階を説明するにはnext_milestoneを使えます。計算は決定的であり、ネットワーク、時刻、保存状態、乱数を利用しません。同じ入力には常に同じ結果が返ります。対話的な計画ではブラウザーで無料実行でき、レポート作成、ダッシュボード更新、目標レコードの自動処理では1リクエストあたり$0.002でAPIを利用できます。

活用例

OKRダッシュボードを表示する

各目標の基準値、最新測定値、目標値、確認しきい値を一貫した進捗マーカーへ変換します。

削減目標を追跡する

不具合、インシデント、サポート遅延など、望ましい結果が小さい場合も進捗を正しく表示します。

マイルストーン通知を作成する

到達済みの達成率とアプリケーションの以前の状態を比較し、送信する達成メッセージを決定します。

よくある質問

目標値が開始値より小さい目標にも対応しますか？

はい。減少目標にも同じ距離ベースの計算を使い、方向を減少として明示します。

進捗が目標を超えた場合はどうなりますか？

実際の進捗率は成果超過を保持するため100を超えられますが、グラフ上の位置は100に制限されます。

順不同または重複したマイルストーンはどう処理されますか？

重複を統合し、値と到達状態を計算する前に達成率の低い順へ並べ替えます。

開始値と目標値が同じ場合に拒否されるのはなぜですか？

区間の長さがゼロになり、除算で意味のある目標進捗率を求められないためです。

APIリクエストの料金はいくらですか？

APIリクエストは1回あたり$0.002で、ブラウザーの対話版は無料です。

開発者向け — APIアクセス

このページの機能はすべてAPIからも利用できます。自社システムに組み込みたいチーム向けのセクションです。それ以外の方は上のツールをそのままお使いください。

エンドポイント

POSThttps://api.kit.forhosting.com/final3/goal-milestone-progress-chart-data

Bearerトークンで認証し、POST1回でタスクをキューに登録します。結果はWebhookまたは署名付きリンクで受け取れます。

お使いのスタックから呼び出す

curl -X POST https://api.kit.forhosting.com/final3/goal-milestone-progress-chart-data \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_value":20,"current_value":68,"target_value":100,"milestone_percentages":[25,50,75,100]}'

const res = await fetch("https://api.kit.forhosting.com/final3/goal-milestone-progress-chart-data", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "start_value": 20,
    "current_value": 68,
    "target_value": 100,
    "milestone_percentages": [
      25,
      50,
      75,
      100
    ]
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/final3/goal-milestone-progress-chart-data",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "start_value": 20,
    "current_value": 68,
    "target_value": 100,
    "milestone_percentages": [
        25,
        50,
        75,
        100
    ]
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/final3/goal-milestone-progress-chart-data", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"start_value":20,"current_value":68,"target_value":100,"milestone_percentages":[25,50,75,100]}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"start_value":20,"current_value":68,"target_value":100,"milestone_percentages":[25,50,75,100]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/final3/goal-milestone-progress-chart-data", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

リクエスト例

{
  "start_value": 20,
  "current_value": 68,
  "target_value": 100,
  "milestone_percentages": [
    25,
    50,
    75,
    100
  ]
}

レスポンス例

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "final3.goal_milestone_progress_chart_data",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

非同期APIです。task_idは即時に返ります。ポーリングは1秒あたり1リクエストまでです。

料金

1リクエストあたり$0.002

単価はすべて公開しています。トークン換算や独自クレジットはありません。失敗したタスクは課金されません。

制限

max_items 100

エラー

HTTP	コード	意味
`401`	`unauthorized`	APIキーが無効か、指定されていません。Authorizationヘッダーを確認してください。
`402`	`insufficient_balance`	残高が不足しています。チャージ後に再度お試しください。
`404`	`unknown_type`	指定されたタスクタイプは存在しません。タイプ名を確認してください。
`429`	`rate_limited`	リクエストが多すぎます。しばらく待ってから再度お試しください。

KITの完全なドキュメントを見る →