tencent-docs

Tencent Docs（腾讯文档）

腾讯文档 Open API を curl + jq で操作します。すべてユーザー自身の Tencent Docs アカウント内で実行されます。対象はユーザーがアクセスできるファイルのみで、接続時に許可したスコープのみを使用します。

認証 — 3 つのヘッダー（単一の Bearer ではありません）

tencentdocs BYOC コネクターは 3 つの環境変数を注入します。すべての呼び出しで3 つすべてのヘッダーを送信します。

• TENCENTDOCS_ACCESS_TOKEN → Access-Token ヘッダー（OAuth2 アクセストークン）。シークレットです。
• TENCENTDOCS_CLIENT_ID → Client-Id ヘッダー（開発者アプリの Client ID）。
• TENCENTDOCS_OPEN_ID → Open-Id ヘッダー（トークンとともに返されるユーザー ID）。

すべてのエンドポイントは https://docs.qq.com/openapi の配下にあります。セッションごとに一度、再利用可能なヘッダーセットを定義します。

AUTH=(-H "Access-Token: $TENCENTDOCS_ACCESS_TOKEN" \
      -H "Client-Id: $TENCENTDOCS_CLIENT_ID" \
      -H "Open-Id: $TENCENTDOCS_OPEN_ID")

TENCENTDOCS_ACCESS_TOKEN をエコー、表示、またはログに出力しないでください。アカウントへのフルアクセスを許可する情報です。

レスポンス形式とエラー処理

すべてのレスポンスは {"ret": 0, "msg": "Succeed", "data": {…}} です。ret == 0 は成功を意味し、それ以外の ret はエラーです。msg をユーザーに伝えてください。必ず確認します。

resp=$(curl -sS "${AUTH[@]}" … )
echo "$resp" | jq 'if .ret == 0 then .data else error("Tencent Docs \(.ret): \(.msg)") end'

よくあるエラーコード：

code	意味	対応
400006	アクセストークンが無効、または期限切れです	https://studio.acedata.cloud/console/connectors で 腾讯文档 に再接続するようユーザーに伝えてください。再試行を繰り返してはいけません
400007	VIP（超级会员）特権が必要です	要求された機能には Tencent Docs の超级会员が必要です。その旨をユーザーに伝え、https://docs.qq.com/vip を案内してください
400008	积分（クレジット）が不足しています	AI 生成の利用枠を使い切っています。チャージするようユーザーに伝えてください
11607 / -32603	リクエストパラメーターが不正です	以下のレシピに照らして、fileID / type / body フィールドを再確認してください

ドキュメントの種類（作成時の type）

type	製品	備考
doc	在线文档（Word 形式）	従来型のリッチテキスト文書
sheet	在线表格（Excel）	データテーブル
slide	幻灯片（PPT）	プレゼンテーション
mind	思维导图	マインドマップ
flowchart	流程图	フローチャート
smartsheet	智能表格	構造化された複数ビューのテーブル
form	收集表	フォーム／アンケート

レシピ

認証を確認する（必ず最初に実行）

簡単な確認として、アプリの OpenAPI 利用回数カウンターを読み取ります。

curl -sS "${AUTH[@]}" "https://docs.qq.com/openapi/drive/v2/util/resource-use" \
  | jq 'if .ret == 0 then .data else "ERR \(.ret): \(.msg)" end'

これが 400006 を返した場合、接続の有効期限が切れています。ユーザーに再接続してもらってください。

フォルダーを一覧表示する（ルート = /）

curl -sS "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/folders/%2F?listType=folder&sortType=browse&asc=0" \
  | jq 'if .ret == 0 then [.data.list[]? | {ID, title, type, url}] else . end'

%2F は URL エンコードされたルートフォルダー ID です。サブフォルダーの場合は、パスにそのフォルダー ID を指定します。

キーワードでファイルを検索する

curl -sS -G "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/search" \
  --data-urlencode "searchName=Q1 预算" \
  | jq 'if .ret == 0 then [.data.list[]? | {ID, title, type, url}] else . end'

ファイルのメタデータを読み取る

fileID は https://docs.qq.com/doc/<id>（または /sheet/、/slide/ など）の URL の末尾のパス要素です。

curl -sS "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID/metadata" \
  | jq 'if .ret == 0 then .data else . end'

オンライン文書の内容を読み取る

curl -sS "${AUTH[@]}" \
  "https://docs.qq.com/openapi/document/v3/files/FILE_ID/export?exportType=text" \
  | jq 'if .ret == 0 then .data else . end'

シートのセル範囲を読み取る

最初にメタデータからシートの sheetId 一覧を取得し、次に範囲（A1:D10）を読み取ります。

curl -sS "${AUTH[@]}" \
  "https://docs.qq.com/openapi/spreadsheet/v2/files/FILE_ID/sheets/SHEET_ID/values?range=A1:D10" \
  | jq 'if .ret == 0 then .data.values else . end'

ファイルを作成する

POST /openapi/drive/v2/files に、フォーム URL エンコード形式で title と type を送信します。新しいファイルの ID と url が返されます。

curl -sS -X POST "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files" \
  --data-urlencode "title=会议纪要 2026-07-03" \
  --data-urlencode "type=doc" \
  | jq 'if .ret == 0 then {ID: .data.ID, url: .data.url} else . end'

他の種類のドキュメントを作成するには、type=sheet / slide / mind / flowchart / smartsheet / form に置き換えます。ルートではなくフォルダー内に作成する場合は、--data-urlencode "folderID=<id>" を指定します。

画像をアップロードする（ドキュメントへの埋め込み用）

curl -sS -X POST "${AUTH[@]}" \
  "https://docs.qq.com/openapi/resources/v2/images" \
  -F "file=@./cover.png" \
  | jq 'if .ret == 0 then .data else . end'

ファイル名を変更する — 要確認、事前に確認する

現在の title と url、および新しいタイトルをユーザーに提示し、明示的な「はい」を得てから実行します。

curl -sS -X PATCH "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID" \
  --data-urlencode "title=新的标题" \
  | jq 'if .ret == 0 then "renamed" else . end'

ファイルを移動する — 要確認、事前に確認する

ファイルの現在の title と場所、および移動先のフォルダーをユーザーに提示し、明示的な「はい」を得てから実行します。folderID=/ を指定すると、ルートに戻します。

curl -sS -X PATCH "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID/move" \
  --data-urlencode "folderID=DEST_FOLDER_ID" \
  | jq 'if .ret == 0 then "moved" else . end'

ファイルをコピーする

curl -sS -X POST "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID/copy" \
  --data-urlencode "title=副本 - 项目计划" \
  | jq 'if .ret == 0 then {ID: .data.ID, url: .data.url} else . end'

ファイルを削除する — 要確認、事前に確認する

削除するとファイルはごみ箱に移動しますが、破壊的な操作であることに変わりはありません。正確な title と url をユーザーに提示し、明示的な「はい」を得てから実行します。

curl -sS -X DELETE "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID" \
  | jq 'if .ret == 0 then "deleted" else . end'

メモ

• 書き込みは必ず確認してください。 名前の変更、移動、削除、コピー、および共有権限の変更は、ユーザーの実際のファイルに対して実行されます。実行前に、対象が間違いなくそのファイルであることを確認してください。
• リンクから ID を抽出してください。 ユーザーが docs.qq.com/doc/<id>（または /sheet/、/slide/、/mind/、/flowchart/、/form/、/smartsheet/）の URL を貼り付けた場合、 ID を尋ねずに、パスから ID を取得してください。
• ページネーション。 リスト／検索エンドポイントは、data 内にカーソル／next マーカーを返します。次のページを取得するために、この値を渡してください。マーカーが空になったら終了してください。
• レート制限／クォータ。 無料アプリでは、API 呼び出しを月あたり 20,000 回まで利用できます（超级会员は 1 日あたり 20,000 回、Plus は 1 日あたり 40,000 回）。AI 生成機能では、さらに积分を消費するため、超级会员が必要な場合があります。400007／400008 が返された場合、リクエストの不具合ではなく、アカウントのプランまたはクレジットが原因です。
• API 全体のインデックス。 上記のレシピ以外にも、Open API はスマートテーブルのレコード、フォーム収集、フォルダーの CRUD、権限、インポート／エクスポートに対応しています。接口索引を参照してください。