コンテンツにスキップ

コンポーネントボードのアップロード

メソッド

この API は REST の方法論に従います。

HTTP メソッド

POST: コンポーネントライブラリのボードをアップロードします — component_upload イベントをエンキューし、スコープ付き の component_sweep にルーティングします。ワーカーは選択されたボードのサブツリーのみを走査して COMPONENT / COMPONENT_SET の定義とリモートライブラリのインスタンスを探し、それぞれをコンポーネントレジストリに upsert します。

追加的（additive）です。 ファイル全体を再走査する resync と異なり、選択されたボード外のコンポーネントには一切触れません。

命名規則

一貫性と可読性のため、リクエスト / レスポンスの JSON ノードは camelCase、SQS ペイロードのノードは snake_case を使用します。

リクエストとレスポンス

ヘッダー

メタ情報はレスポンスボディではなく HTTP ヘッダー に設定されます。

リクエストヘッダー

  • Authorization
  • Content-Type
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

コンポーネントボードのアップロード

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/components

パスパラメータ

名前 型 必須 説明
organization_id integer 必須 組織 ID
project_id integer 必須 プロジェクト ID

リクエストボディ

リクエストボディは JSON です。

{
  "figmaFileKey": "abc123XYZ",
  "boardNodeIds": ["10:200", "10:201"],
  "styleCaptures": {
    "color/primary": "VariableID:1:23",
    "spacing/md": "VariableID:1:45"
  }
}

リクエストパラメータ

名前 型 必須 説明
figmaFileKey string 必須 ボードが存在するコンポーネントライブラリファイル。Figma 逐語（^[A-Za-z0-9]+$）。
boardNodeIds string[] 必須 選択されたコンポーネントライブラリのボードフレーム — 1 件以上。CANVAS / SECTION コンテナも受け付け、ワーカー側で展開する。
styleCaptures object (string→string) 任意 プラグインが取得した トークン → VariableID:… のマップ（figma.variables.* で読んだファイルのローカル Figma Variables）。style_captures にマージされ、生成時にライブ変数をバインドできるようにする。

レスポンス

レスポンスは JSON です（HTTP ステータス: 202 Accepted）。

{
  "eventRunId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e71",
  "figmaFileKey": "abc123XYZ",
  "boardNodeIds": ["10:200", "10:201"]
}

レスポンスフィールド

名前 型 説明
eventRunId string GET …/wf2des/events/{eventRunId}/status をポーリングして進行状況を取得する。
figmaFileKey string リクエストのエコー。
boardNodeIds string[] リクエストのエコー — ワーカーがコンテナを展開する前の選択内容。

認証

認証は Amazon Cognito が発行する JSON Web Token（JWT）で行われます。加えて、呼び出し元はプロジェクトへの Write 権限を保持している必要があります。

エラーハンドリング

エラー時には以下のステータスコードが返されます。

説明 ステータスコード ステータス名
不正なボディ（figmaFileKey の形式不正、boardNodeIds が空または形式不正） 400 Bad Request
認証情報の欠落 401 Unauthorized
権限不足（プロジェクトへの Write 権限なし） 403 Forbidden
プロジェクトまたは組織が見つからない 404 Not Found
SQS 送信の失敗 500 Internal Server Error

処理フロー

  1. パスパラメータから組織 ID とプロジェクト ID を、リクエストボディを取得する。
  2. ユーザーがプロジェクトへの Write 権限を持つことを検証する。
  3. 新しい eventRunId を採番する。
  4. component_upload イベントを wf2des-events SQS キューへ送信する。バックエンドは選択されたノード ID のみを転送し、ボードの解決と走査はワーカーが行う。
  5. ポーリング用ハンドルとともに 202 を返す。

非同期処理

component_upload イベントはスコープ付きの component_sweep にルーティングされます。ワーカーはコンポーネントごとに publish key、バリアント軸、テキストスロット、デフォルトサイズを記録し、design_component レジストリへ upsert します。

このスイープは Figma REST API 経由で読み取りますが、REST は デザインシステムライブラリの内部を見ることができません。リモートコンポーネントはそのインスタンス越しにしか観測できないため、スイープは publish key を持たないローカルの双子を、断片的なバリアント軸とともに作ってしまうことがあります。POST …/wf2des/component-captures はまさにこれを補正するために存在し、プラグインは通常このアップロード完了後の 2 回目のパスとしてキャプチャを送信します。

component_sweep は 内部 実行です — ai-status Webhook はありません。レジストリへの効果は GET …/wf2des/registry から観測できます。

SQS ペイロード

{
  "event_type": "component_upload",
  "organization_id": 1,
  "project_id": 7,
  "event_run_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e71",
  "figma_file_key": "abc123XYZ",
  "board_node_ids": ["10:200", "10:201"],
  "style_captures": { "color/primary": "VariableID:1:23" }
}

SQS ペイロードフィールド

名前 型 必須 説明
event_type string 必須 常に component_upload。キューの判別子。
organization_id integer 必須 組織 ID。
project_id integer 必須 プロジェクト ID。
event_run_id string 必須 プラグインがポーリングするライブステータス文書と対応付ける。
figma_file_key string 必須 コンポーネントライブラリファイル（逐語）。
board_node_ids string[] 必須 選択されたボード。コンテナはワーカー側で展開される。
style_captures object 必須 トークン → VariableID:… のマップ。リクエストで省略時は {}。