sheets (v3)

重要 — 開始する前に、../lark-shared/SKILL.md を必ず Read ツールで読み込んでください。これには認証と権限処理に関する情報が含まれています。

迅速な意思決定

• クラウドスペース内のスプレッドシートファイルをタイトルまたはキーワードで検索するには、まず lark-cli docs +search を使用します。
• docs +search は直接 SHEET の結果を返しますので、ドキュメント/Wiki のみ検索できると誤解しないでください。
• スプレッドシートの URL / トークンが分かっている場合は、sheets +info、sheets +read、sheets +find などのオブジェクト内部操作に進んでください。

コアコンセプト

ドキュメントタイプとトークン

飛書オープンプラットフォームでは、異なるタイプのドキュメントには異なる URL 形式とトークン処理方法があります。ドキュメント操作（コメントの追加、ファイルのダウンロードなど）を行う際には、まず正しい file_token を取得する必要があります。

ドキュメント URL 形式とトークン処理

Wiki リンクの特殊処理（重要！）

ナレッジベースリンク（/wiki/TOKEN）の背後には、クラウドドキュメント、スプレッドシート、多次元テーブルなど、さまざまな種類のドキュメントが存在する可能性があります。URL 内のトークンが file_token であると直接仮定することはできません。まず実際のタイプと実際のトークンをクエリで確認する必要があります。

処理フロー

1. wiki.spaces.get_node を使用してノード情報をクエリします

   lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

2. 返された結果から重要な情報を抽出します

   • node.obj_type：ドキュメントタイプ（docx/doc/sheet/bitable/slides/file/mindnote）
   • node.obj_token：実際のドキュメントトークン（後続の操作に使用）
   • node.title：ドキュメントタイトル

3. obj_type に基づいて対応する API を使用します

   obj_type	説明	使用する API
   docx	新しいバージョンのクラウドドキュメント	drive file.comments.*、docx.*
   doc	古いバージョンのクラウドドキュメント	drive file.comments.*
   sheet	スプレッドシート	sheets.*
   bitable	多次元テーブル	bitable.*
   slides	スライド	drive.*
   file	ファイル	drive.*
   mindnote	マインドマップ	drive.*

クエリ例

# wiki ノードをクエリする
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

返された結果の例：

{
   "node": {
      "obj_type": "docx",
      "obj_token": "xxxx",
      "title": "タイトル",
      "node_type": "origin",
      "space_id": "12345678910"
   }
}

リソースの関係

Wiki Space (知識空間)
└── Wiki Node (知識庫ノード)
    ├── obj_type: docx (新しいバージョンのドキュメント)
    │   └── obj_token (実際のドキュメントトークン)
    ├── obj_type: doc (古いバージョンのドキュメント)
    │   └── obj_token (実際のドキュメントトークン)
    ├── obj_type: sheet (スプレッドシート)
    │   └── obj_token (実際のドキュメントトークン)
    ├── obj_type: bitable (多次元テーブル)
    │   └── obj_token (実際のドキュメントトークン)
    └── obj_type: file/slides/mindnote
        └── obj_token (実際のドキュメントトークン)

Drive Folder (クラウドスペースフォルダ)
└── File (ファイル/ドキュメント)
    └── file_token (直接使用)

操作フロー（重要）：

1. create — フィルターを作成します

   • 初めてフィルターを作成する場合に使用します
   • ⚠️ range は、フィルターを適用するすべての列をカバーする必要があります（例：B1:E200）
   • 既存のフィルターがある場合、create を再度使用するとフィルター全体が上書きされます

2. update — フィルターを更新します

   • 既存のフィルターに指定された列の条件を追加/更新する場合に使用します
   • col と condition のみを指定すればよく、range は不要です

3. delete — フィルターを削除します

4. get — フィルターの状態を取得します

複数列フィルターの例：

メディア名（B列）と感情分析（E列）の二重フィルターを作成します。

# 1. 既存のフィルターを削除します（もしあれば）
lark-cli sheets spreadsheet.sheet.filters delete \
  --params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}'

# 2. 最初のフィルターを作成します。range はフィルターを適用するすべての列をカバーします。
lark-cli sheets spreadsheet.sheet.filters create \
  --params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}' \
  --data '{"col":"B","condition":{"expected":["xx"],"filter_type":"multiValue"},"range":"<sheet_id>!B1:E200"}'

# 3. 2番目のフィルター条件を追加します
lark-cli sheets spreadsheet.sheet.filters update \
  --params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}' \
  --data '{"col":"E","condition":{"expected":["xx"],"filter_type":"multiValue"}}'

よくあるエラー：

• Wrong Filter Value：フィルターが既に存在する場合、まず delete してから create する必要があります
• Excess Limit：update 時に同じ列の条件を繰り返し追加した場合

Shortcuts（優先的に使用することを推奨）

Shortcut は、よく使用される操作を高度にカプセル化したものです（lark-cli sheets +<verb> [flags]）。Shortcut がある操作は優先的に使用してください。

API リソース

lark-cli schema sheets.<resource>.<method>   # API を呼び出す前に、まずパラメータ構造を確認する必要があります
lark-cli sheets <resource> <method> [flags] # API を呼び出します

重要：ネイティブ API を使用する場合、--data / --params パラメータ構造を確認するために、まず schema を実行する必要があります。フィールドの形式を推測しないでください。

spreadsheets

• create — スプレッドシートを作成します
• get — スプレッドシート情報を取得します
• patch — スプレッドシートのプロパティを変更します

spreadsheet.sheet.filters

• create — フィルターを作成します
• delete — フィルターを削除します
• get — フィルターを取得します
• update — フィルターを更新します

spreadsheet.sheets

• find — セルを検索します

権限表