Autodesk Developer Blog : Automation API：キュー可視化を導入

Automation API がキューの可視化機能を追加しています。システム全体のキューのヘルスメトリクス（健全性の指標）を公開して、WorkItem 毎のキューポジションフィールドも 2 週間後の 2026年8月10日を目途に配信される予定です。

現在、WorkItem を提出して GET /workitems/{id}でエンドポイントでポーリングすると、pending ステータスだけが返されます。システムが Busy 状態なのか、WorkItem がスタックしているのか、遅延がオートデスク側に起因するものなのか、あるいはアプリ側にあるのかを判断することが出来ません。

キューの可視化機能は、この問題に対して2段階で情報を提供します。

システムレベルのキューのヘルスメトリクスが公開されます。任意のエンジンの最近のキュー時間パーセンタイルを参照することで、システムがスムーズに動作している状態か、負荷がかかっているか状態かを確認することが出来ます。
保留中の WorkItem がキュー内のどの辺りに位置しているかをおおよそ把握出来る「ジョブレベルのキュー位置」機能が、2週間後にリリースされます。これは GET /workitems/{id} エンドポイントに新しい approximateQueuePosition フィールドとして追加されるものです。変更に先立ってこの情報を公開するのは、必要に応じて対応を準備するための2週間の期間を設けるためです。

（Automation API を使用すると、開発者は Revit®、AutoCAD®、Inventor、3ds Max、および Fusion のアドイン/プラグインやワークフローを、クラウド上でプログラムによって実行して成果に応じた従量課金制で利用することが出来ます。）

何を意味するのか?

システムヘルスをご確認ください。
GET /health/{engine}/stats をクエリすると、指定したエンジンの直近のキュー待機時間（ミリ秒単位）のパーセンタイルを示す2つのフィールド（p50QueueTimeMs および p95QueueTimeMs）が返されます。コードの変更や新しいパラメータの追加は不要です。
2 週間後を目途に、ジョブのキュー内での位置が確認できるようになります。
2 週間後に保留中の WorkItem に対して GET /workitems/{id} を実行すると、新たに approximateQueuePosition5 フィールドが含まれるようになります。このフィールドは、キュー内での順位（例：5 番目なら「5」）といった、ジョブのおおよその位置を示します。このフィールドの追加は既存の仕様を拡張する形でおこなわれますが、未知のフィールドを拒否する厳密な JSON 解析をおこなっている統合システムを使用している場合には、この2週間の期間中に、新しいフィールドを許容するようにシステムを更新する必要があります。標準的な .NET や Node.js の統合システムを含むほとんどのクライアントは、認識出来ないフィールドを無視する仕様になっているため、明示的な変更は不要です。
サポートチケットを削減できます。
運用時にローカルな問題かオートデスク側の遅延かを区別し、キュー内の順序に対して直接的な対応をとることが可能になります。

キューの可視化機能導入の理由

Automation API は多くのチームのミッションクリティカルなワークフローを担っているため、キューの可視化はお客様からの頻繁に寄せられていた要望でした。ジョブが pending 状態のまま前述のような追加情報が得られない場合、システムが正常に稼働していても、チームはサポートチケットを起票したり、ロールアウトを一時停止したりしてしまいます。

システムの状態をリアルタイムで可視化することで、負荷を考慮した計画立案や迅速なトラブルシューティングが可能になり、本番環境での自動化をより確信を持って拡張出来るようになります。

仕組み

キューの可視化は、2 つのフェーズで提供される 2 つの追加要素によって実現されます。システムレベルの健全性を示す新しいエンドポイントと、既存のエンドポインドに追加される、ジョブレベルの順位を示す新しいフィールドです。

1. システムレベルのキュー健全性（現在利用可能）

GET /health/{engine}/stats エンドポイントは、単一エンジンについて過去 5 分間のキュー待機時間のパーセンタイルを返すため、個々のジョブをポーリングすることなく、システム全体のキュー挙動を把握できます。Automation API の他の部分と同じエンジン（AutoCAD、Revit、Inventor、Fusion、3ds Max）に対応しています。レスポンスにはミリ秒単位の 2 つのフィールドが含まれます:

p50QueueTimeMs(中央値): 「通常の」体験を示します。過去 5 分間で、ジョブの半数はこの値未満の待機時間でした。
p95QueueTimeMs: ほぼ最悪ケースに近いリクエストの体験を示します(最も遅い 5 %を除いた値)。

Revit のキュー健全性を確認する例:

			
curl -H "Authorization: Bearer $TOKEN" \
  https://developer.api.autodesk.com/da/us-east/v3/health/Revit/stats
{
  "p50QueueTimeMs": 106.72,
  "p95QueueTimeMs": 372.19
}

		

該当エンジンについて直近のキュー待機時間データが存在しない場合（例:ウィンドウ内にジョブがない場合）、両フィールドとも時間値ではなく -1.0 を返します。-1.0 は「直近のデータなし」として扱い、待機時間として扱わないでください:

			
{
  "p50QueueTimeMs": -1.0,
  "p95QueueTimeMs": -1.0
}

重要なのは、2 つのパーセンタイルが互いにどう変化するかです。

キューの各フェーズの読み取り方:

キューが増加し始めている: p95 が上昇する一方、p50 は横ばい。一部のジョブがワーカーの空きを待ち始めているが、一般的なジョブはまだすぐに開始している状態。
キューが増加を続けている: p50 も上昇し始める。バックログが遅延の裾野だけでなく、大多数のジョブに影響を及ぼし始めている状態。
キュー待機時間が高い: p50 と p95 の両方が高い状態。システムが持続的な競合状態にあるか、キャパシティが不足している状態。
キューが解消に向かっている: p95 が p50 に近づいていく。バックログが解消されつつある状態。
キュー待機時間が低い: 両パーセンタイルとも低い状態。システムに余裕がある状態。

例えば、このエンドポイントを定期的にポーリングし、p50 が上昇してきた際には緊急性の低いバッチ送信を保留・抑制することで、混雑しているエンジンへの負荷追加を避けることができます。

2. ジョブレベルのキュー順位（2026年8月10日提供開始）

保留中（pending）の WorkItem を GET /workitems/{id} でポーリングすると、レスポンスに新しい approximateQueuePosition フィールドが含まれるようになります:

			
{
  "id": "a1b2c3d4e5f6...",
  "status": "pending",
  "approximateQueuePosition": 5
}

		

これは 1 から始まる整数で、「Revit のキューで 5 番目です」のような意味になります。ジョブの処理が開始されると、このフィールドは返されなくなります。順位は各リクエストごとに再計算されるため、常に最新の状態を確認できます。

知っておくべき点:

null になる場合あります。 ジョブが保留中の間、その時点で順位が判定できない場合、approximateQueuePosition は null になることがあります。ジョブはキューに入ったままであり、通常どおり処理されます。
近似値であり、前後することがあります。 順位は前方のジョブが処理されるにつれて基本的に減少しますが、例えば前方のジョブがキャンセルまたは再キューされた場合など、一時的に変動することがあります。これは想定内の挙動です。
エンジンごとに 1 つのキュー。 順位の扱いは対象とするエンジンのバージョンに関わらず同じです。バージョンごとに個別のキューがあるのではなく、エンジンごとに 1 つの共有キューとなります。

重要: キュー順位は健全性を示すシグナルであり、推定待機時間ではありません。前方のジョブが 30 秒で終わる RFA ファイルかもしれませんし、10 分かかる Revit モデルかもしれません。順位は、システムがジョブを処理しており、自分のジョブが順番待ちの列に入っていることを裏付けるものであり、どれくらい待つことになるかを示すものではありません。

変わらない点

同じ POST /workitems の送信フロー
同じ課金モデル
既存のエンドポイントとパラメータは同じ挙動を維持します。キューの可視化は新しいエンドポイントと新しいフィールドを追加するのみです。
ほとんどのインテグレーションでコード変更は不要です。approximateQueuePosition は純粋な追加項目です。
唯一の例外: インテグレーションが未知のフィールドを拒否する厳格な JSON パースを使用している場合、この新しいフィールドによりエラーが発生します。標準の .NET および Node.js クライアントは既定で未知のフィールドを無視するため、これは稀なケースですが、厳格なパースを採用している場合は、フィールド提供開始までの 2 週間の猶予期間内に、追加フィールドを許容するよう緩和してください。それ以外、現時点で対応が必要な変更はありません。

利用にあたって

現在利用可能:

GET /health/{engine}/stats: 指定したエンジンの p50QueueTimeMs と p95QueueTimeMs（直近のキュー待機時間パーセンタイル、ミリ秒単位）を返します。

2026年8月10日提供開始:

GET /workitems/{id}: ジョブが保留中の間、approximateQueuePosition フィールドが含まれるようになります。提供開始日にこの投稿とチェンジログを更新予定です。

最新状況については Automation API リファレンスドキュメントおよびチェンジログをご確認ください。認証や設定の変更は不要です。

今後の予定

approximateQueuePosition は 2 週間後に提供開始予定です。正確な日付についてはAutomation API ドキュメントのチェンジログをご確認ください。提供開始後は、フェーズ 1 のキュー順位機能に関するフィードバックを収集し、今後の展開に活かしていく予定です。ご質問やフィードバックがございましたら、APS Get Help ページをご覧ください。

※ 本記事は Introducing queue visibility for Automation API | Autodesk Platform Services から転写・意訳・補足したものです。

Automation API：キュー可視化を導入