aps-docs-portal

このスキルでは、ドキュメントポータルを参照しながら、APS 関連の質問に回答する手順を説明します。

動作

1. ユーザーの最初の質問が曖昧または広範な場合は、詳しい回答に入る前に、意図を確認するための短い質問を1つします。
2. 回答には必ず参照リンクを記載します。
3. APS 関連の質問には必ず直接回答するようにします。
4. 訪問者に合わせて詳しさを調整します。ビジネス担当者には要約と ROI、ビルダーには手順ごとの説明、開発者には REST スキーマと認証フローを提供します。判断に迷う場合は質問します。

基本ルール

• aps.autodesk.com/en/docs/... は決して取得しないでください（WebFetch、curl など、方法を問いません）。ポータルは JavaScript SPA であり、その配下の URL は有効かどうかにかかわらず、すべて同じ約 10 KB の HTML シェルを返します。ドキュメントの内容は含まれておらず、URL が存在するかどうかさえ判別できません。
• すべてのコンテンツは、TOC JSON（developer.doc.config.autodesk.com）とページ HTML（developer.doc.autodesk.com）の2か所にあります。これらのみを使用してください。
• これらの CDN URL をユーザーに表示しないでください。また、CDN パスからポータルリンクを手動で作成しないでください。ポータルリンクはすべて、TOC インデックスの列1（ステップ3）から取得します。
• 質問が用語についてのみの場合は、用語集だけを参照して回答してください。取得は不要です。

---

APS に関する質問への回答方法

ステップ 1 — 用語集を読み、専門用語を理解する

質問に、ここに記載されていない略語が含まれている場合は、後で取得するドキュメントで定義を確認してください。

APS 用語集

• APS：Autodesk Platform Services（旧称 Forge）
• ACC：Autodesk Construction Cloud。最近のドキュメントページでは、ACC のサービスを Forma と表記することもあります（例：「Forma Issues」、「Forma Data Management」）。別個の Forma Site Design API は forma_v1 です。
• BIM 360：従来の建設管理プラットフォーム（ACC の前身）
• MD：Model Derivative API — 設計ファイルを表示可能な形式（SVF/SVF2）に変換します
• DM：Data Management API — ファイル、フォルダー、ストレージ（OSS、BIM 360、ACC のハブ）を管理します
• URN：APS API 全体で使用される、Base64 でエンコードされたリソース識別子
• SVF/SVF2：Scalable Viewing Format — Model Derivative によって生成され、APS Viewer SDK のみで使用される、最適化された 3D ウェブ表示形式です。openCTM 圧縮を使用する glTF 形式と同様の概念です
• OSS：Object Storage Service — 設計ファイルのアップロードに使用する APS のクラウドストレージ
• Webhook：APS のイベント（例：モデルの変換完了、ファイルバージョンの追加）によってトリガーされる、サーバー間コールバック
• 2LO/3LO：OAuth 認証フローの二者間／三者間方式
• Hub：Data Management における最上位のコンテナー（ACC または BIM 360 のアカウントに対応）
• Manifest：Model Derivative の変換ステータスと出力メタデータ
• ACAD：AutoCAD — Autodesk の主力 2D/3D CAD 作図ソフトウェア（.dwg ファイルを生成します）
• Civil：Autodesk Civil 3D — インフラプロジェクト向けの土木設計ソフトウェア
• Revit：Autodesk Revit — 建築、構造、MEP 設計向けの BIM ソフトウェア（.rvt ファイルを生成します）
• Build：Autodesk Build — ACC の建設管理モジュール（現場管理、コスト管理など）
• IFC：Industry Foundation Classes — ツール間で BIM データを交換するためのオープン標準ファイル形式
• RFI：Request for Information — 建設中に提出され、ACC/BIM 360 で追跡される正式な質問
• SSA：Secure Service Accounts — 秘密鍵で JWT アサーションに署名し、それを 三者間（ユーザーコンテキスト）のアクセストークンと交換するサーバー間 ID です。対話形式でのサインインは必要ありません
• AEC：Architecture, Engineering, and Construction — APS が主にサービスを提供する業界分野
• AECDM：AEC Data Model API — ACC 全体の設計データと建設データにアクセスするための統合 API
• DX：Data Exchange — 中立的な形式でアプリケーション間の設計データを交換するための API
• Auth：Authentication — 2LO、3LO、PKCE、PAT（Personal Access Tokens）、SSA を含む APS OAuth フロー

変換コスト（Model Derivative API）： 複雑なジョブは Revit（.rvt）、IFC、Navisworks（.nwd/.nwc）です。それ以外はすべて単純なジョブです。

---

ステップ 2 — 関連する API を特定する

以下のソース一覧から、開く TOC を選びます。例：

• 「ファイル変更」 → Webhooks API（webhooks_v1）に記載されている Data Management イベント
• 「モデルの変換」 → Model Derivative API（model-derivative_v2）
• 「デジタルツイン」 → Tandem（tandem_v1）
• 「イベント／コールバック」 → Webhooks API（webhooks_v1） — すべてのイベントファミリー（dm.*、issue.*、extraction.*、コスト、レビューなど）は、その reference/events/ セクションにあります

ソース ID	API タイトル
acc_v1	Autodesk Construction Cloud APIs
aecdatamodel_v1	AEC Data Model API
applications_v1	Application Management API
bim360_v1	BIM 360 API
buildingconnected_v2	BuildingConnected & TradeTapp APIs
data_v2	Data Management API
dataviz_v1	Data Visualization
design-automation_v3	Automation API
dx-sdk-beta_v7.2.0	Data Exchange .NET SDK v7.2.0
fdxgraph_v1	Data Exchange GraphQL
flow_graph_engine_v1	Flow Graph Engine
forma_v1	Forma Site Design API (Beta)
informed-design_v1	Informed Design API (Beta)
insights_v1	Business Success Plan Reporting API
mfgdataapi_v3	Manufacturing Data Model API
model-derivative_v2	Model Derivative API
oauth_v2	Authentication API
parameters_v1	Parameters API
profile_v2	User Profile API
ssa_v1	Secure Service Account API
sustainability_v3	Sustainability Data API
tandem_v1	Tandem Data
tokenflex_v1	Token Flex Usage Data API
vaultdataapi_v2	Vault Data API
viewer_v7	Viewer
webhooks_v1	Webhooks API

ポータル URL ↔ ソース ID： ポータル URL https://aps.autodesk.com/en/docs/{api}/{version}/… は、常にソース ID {api}_{version} に対応します（例：/en/docs/acc/v1/… → acc_v1）。

---

ステップ 3 — TOC をダウンロードしてインデックス化する（ソースごとに 1 回）

必要な各 TOC をローカルファイルに一度だけダウンロードし、そのファイルを検索します。TOC は大きいため（ACC は約 140 KB、Data Exchange SDK は約 650 KB）、生の内容をそのまま出力したり、再ダウンロードしたりしないでください。

curl -sL --create-dirs -o /tmp/aps-docs/acc_v1.json "https://developer.doc.config.autodesk.com/bPlouYTd/acc_v1.json"

フラットなインデックスに変換します。ページごとに 1 行とし、ポータル URL、タイトル、CDN ソースパスをタブ区切りで記載します。

jq -r '.url_path as $api | .doc_version as $v | def w($p): ($p + [.url_path // ""]) as $q | (if .source then "https://aps.autodesk.com/en/docs/\($api)/\($v)/\($q | map(select(. != "")) | join("/"))/\t\(.display_name)\t\(.source)" else empty end), (.children[]? | w($q)); .children[] | w([])' /tmp/aps-docs/acc_v1.json | grep -i 'issues'

トピックのキーワードで grep -i を使って絞り込みます。構造を手早く確認するには、トップレベルのセクションを jq -r '.children[] | .url_path' FILE で一覧表示します。

出力例：

https://aps.autodesk.com/en/docs/acc/v1/reference/http/issues-issues-GET/	GET issues	acs-acs-api-documentation-main-52/acc/v1/reference/http/issues/issues-GET.html

• 1 列目だけが、そのページの有効なポータルリンクです。 ポータルは TOC の url_path 値でページを解決し、CDN ファイルパスでは解決しません。この 2 つは異なることがよくあります。

  CDN ソースパス（リポジトリのスラッグ以降）	正しいポータル URL
  acc/v1/reference/http/issues/issues-GET.html	…/en/docs/acc/v1/reference/http/issues-issues-GET/
  model-derivative/v2/overview.html	…/en/docs/model-derivative/v2/developers_guide/overview/
  dx-sdk-beta/v1/v720/developers_guide/overview.html	…/en/docs/dx-sdk-beta/v7.2.0/developers_guide/overview/

• 3 列目は、ステップ 4 で使用するページの HTML パスです。

• ポータル URL が指定された場合（ユーザーから、または別の場所から）：ソース ID に対応付け（ステップ 2）、その TOC をインデックス化し、末尾の / を含む URL を grep -F で完全一致検索して CDN ソースを取得します。CDN URL が指定された場合：3 列目から bPlouYTd/ 以降のパスを grep -F で検索します。リポジトリのスラッグが古い場合は、代わりにパス末尾部分を検索します。

• ページを持たないセクションノードには source がないため、インデックスには含まれません。その場合は、最初の子ページにリンクします。

---

ステップ 4 — 各ページを一度だけ取得し、ローカルで抽出する

ページの HTML を一度ダウンロードし、その後、ローカルファイルに対してすべての抽出を実行します。

curl -sL -o /tmp/aps-docs/page.html "https://developer.doc.autodesk.com/bPlouYTd/{source}"

# 1. Structure first — tells you whether it's a reference page, guide, tutorial, or event list
htmlq -f /tmp/aps-docs/page.html -r 'script, style' --text 'h1, h2, h3, h4'

# 2. Prose, lists, and code samples
htmlq -f /tmp/aps-docs/page.html -r 'script, style, noscript' --text 'p, li, pre'

# 3. Tables (parameters, response fields, status codes) — one row per line
htmlq -f /tmp/aps-docs/page.html -r 'script, style' --text 'tr' | sed 's/^[[:space:]]*//' | grep -v '^$'

注意事項：

• REST リファレンスページは、Method and URI、Authentication Context（例：「User context required」）、Required OAuth Scopesを含むテーブルで始まり、その後にヘッダー、URI／クエリパラメーター、リクエストボディ、レスポンスボディのテーブルが続きます。必須フィールドには * が付いています。ページ全体を読むのではなく、必要なパラメーターやフィールドを含むテーブル行を grep してください（例：grep -A2 '^limit'）。
• 複数のページを同時に扱う必要がある場合は、ページごとに異なるファイル名を使用してください。
• td／table ではなく tr を選択してください。そうしないと、ネストされたセルで同じテキストが何度も繰り返されます。

---

ステップ 5 — 一貫性のある回答にまとめる

1. 用語を定義する（用語集またはドキュメントで確認した内容を参照）
2. 関連する API とエンドポイントを説明する（目次と取得したページを参照）
3. 具体的なイベント、パラメーター、機能を列挙する（リファレンスページを参照し、値は正確に引用）
4. 参照リンクを提示する — インデックスの 1 列目からコピーしたポータル URL のみを使用
5. 該当する場合は、実用的な例を含める（curl コマンド、コードスニペットなど）

---

注意点

• htmlq はプリインストールされていません — macOS では brew install htmlq、または cargo install htmlq でインストールしてください。使用できない場合は、html.parser を使う python3 -c に切り替えてください。
• ソース ID が間違っていると TOC JSON URL は失敗します — 大文字と小文字が区別され、バージョンが付いています（data ではなく data_v2）。ステップ 2 のテーブルを使用してください。
• 古い CDN リポジトリのスラッグは引き続き解決されますが、古いコンテンツが返されます — 記憶や以前の回答にあるパスを再利用せず、必ず現在の TOC から source パスを取得してください。
• Webhook イベントは webhooks_v1 の reference/events/{family}/（例：data_management_events/dm.version.added/）にのみ記載されています。Data Management イベントには dm. プレフィックスが付きます。ACC Issues イベントにはバージョンが付いています（issue.created-1.0）。

---

作業例：「ファイル変更時に利用できる webhook は何ですか？」

ステップ 1 — 用語集。 webhook はサーバー間コールバックです。Data Management は OSS、BIM 360 Docs、ACC Docs のファイルを扱います。

ステップ 2 — API を特定する。 ファイルイベントは Data Management イベントで、Webhooks API（webhooks_v1）に記載されています。

ステップ 3 — TOC のインデックスを作成する。

curl -sL --create-dirs -o /tmp/aps-docs/webhooks_v1.json "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json"
jq -r '<index filter from Step 3>' /tmp/aps-docs/webhooks_v1.json | grep 'data_management_events'

これにより、イベントごとに 1 行が出力されます。dm.version.added、dm.version.modified、dm.version.deleted、dm.version.moved、dm.version.copied、dm.lineage.reserved、dm.lineage.unreserved、dm.lineage.updated、dm.folder.added、dm.folder.modified、dm.folder.deleted、dm.folder.purged、dm.folder.moved、dm.folder.copied、dm.operation.started、dm.operation.completed などが、それぞれポータル URL とソースパスとともに表示されます。

ステップ 4 — 必要なページを取得する（例：3 列目にある dm.version.added ページ）。見出しを抽出し、続いてペイロードテーブルを抽出します。

ステップ 5 — まとめる。

• dm.version.added — 「アイテムの新しいバージョンがフォルダーに追加されたとき」（スコープ：フォルダー）
• dm.version.modified / dm.version.deleted / dm.version.moved / dm.version.copied — バージョンの変更
• dm.folder.* — フォルダーの変更

リンク（1 列目からコピー）：

• Data Management イベント
• dm.version.added
• Webhooks API の概要