軟體功能授權與使用次數限制
“允許匯出”與“每月允許匯出 500 次”是兩條不同的規則。RunFeature 只檢查權限；RunMeteredFeature 在業務成功后確認次數。
設定每月 500 次匯出
在策略的功能清單中添加 export，再增加一條功能額度：功能 export、額度 500、周期“每月”。預設用完就拒絕。允許額外使用時，填寫最多額外次數；系統會記錄超出量，供你的訂單系統處理。
每天和每月額度按 UTC 零點重設；累計額度不重設。修改額度不會刪除已經使用的次數。
匯出成功后，才確認扣次
把自己的業務函數傳給對應 SDK 方法。新任務使用新編號，同一任務重試使用原編號、功能和數量；不同處理程序不要同時執行同一編號。
| 語言 | 計次業務呼叫 |
|---|---|
| Go | client.RunMeteredFeature(ctx, "export", 1, jobID, exportReport) |
| Java | client.runMeteredFeature("export", 1, jobID, this::exportReport) |
| Node.js | await client.runMeteredFeature("export", 1, jobID, exportReport) |
| Python | client.run_metered_feature("export", 1, job_id, export_report) |
| C# | await client.RunMeteredFeature("export", 1, jobID, ExportReport) |
| C++ | client.RunMeteredFeature("export", 1, jobID, exportReport) |
| Rust | client.run_metered_feature("export", 1, &job_id, || export_report())? |
| Ruby | client.run_metered_feature("export", 1, job_id) { export_report } |
| C | ln_run_metered_feature(client, "export", 1, job_id, export_report, context) |
先在策略中為實際功能設定次數規則，再按 AI 接入流程產生提示詞。AI 應使用對應語言的 RunMeteredFeature 和穩定工作編號接入真實業務，重試同一工作時保留原編號。
業務成功而確認失敗時，再次呼叫同一任務只重試確認，不重復執行業務。若程式在業務執行中途崩潰，SDK 會停止自動重做；核對自己的持久業務結果后，用 ResolveMeteredFeature 確認或取消。遠端扣次和本機業務不構成同一個事務。
需要自己控制預留流程時
- 為這次匯出生成并儲存一個業務編號。
- Reserve 預留 1 次額度，返回 pending 后再匯出。返回 committed 表示已完成過，不能再次執行。
- 匯出成功并儲存結果后，Commit 確認扣次。
- 匯出失敗且沒有完成業務時，Cancel 取消預留，不扣次數。
預留預設有效 15 分鐘，遇到 UTC 周期重設會提前結束。直接呼叫 API 可用 reservation_seconds 設定 30–3600 秒。
| 語言 | 預留 | 確認 / 取消 |
|---|---|---|
| Go | Reserve(ctx, "export", 1, jobID) | Commit / Cancel(ctx, hold.ID, jobID) |
| Java / Node.js | reserve("export", 1, jobID) | commit / cancel(id, jobID) |
| C | ln_reserve(client, "export", 1, jobID) | ln_commit / ln_cancel(client, id, jobID) |
| C++ / C# | Reserve("export", 1, jobID) | Commit / Cancel(id, jobID) |
| Python | reserve("export", 1, jobID) | commit / cancel(id, jobID) |
返回欄位怎么讀？
| 欄位 | 含義 |
|---|---|
| reservation_id / operation_id | 預留編號與原業務編號，重試繼續使用原值。 |
| status / expires_at | 預留狀態和截止時間；pending 待完成，committed 已扣次，canceled 已取消，expired 已過期。 |
| consumption.used / reserved | 本周期已確認次數 / 所有有效任務正在預留的次數。 |
| consumption.limit / remaining | 基礎額度 / 可用基礎次數。remaining = max(0, limit - used - reserved)，不包含允許超出的部分。 |
| consumption.quantity / overage | 本任務次數 / 已確認的基礎額度超出量；不會替廠商向客戶收款。 |
| consumption.period / reset_at | UTC 用量周期 / 下次重設時間；終身額度的 reset_at 為 null。 |
傳送什么、返回什么和每個欄位的類型，見授權驗證介面中的預留、確認和取消。
業務已成功時，不取消預留，也不重新匯出。儲存原編號和結果，繼續呼叫 Commit；若預留已過期，保留任務供人工核對。遠端扣次無法與你本機業務組成同一個事務。
Consume 仍可用于直接記賬，但會立即扣次。需要避免業務失敗仍扣次時，請用預留流程。所有計次介面都需要聯網，不計入平臺四類 API 呼叫額度。