ソフトウェア機能のライセンスと利用回数制限
「エクスポートを許可する」と「月に 500 回までエクスポートできる」は別のルールです。RunFeature は機能の利用権限を確認し、RunMeteredFeature は処理が成功した後に利用回数を確定します。
毎月 500 件のエクスポートを許可する
ポリシーの機能一覧に export を追加し、回数制限の機能名を export、上限を 500、期間を monthly に設定します。標準では枠を使い切ると拒否します。超過を許可する場合は超過上限を設定してください。システムは超過利用を記録し、販売者の注文システムで扱えるようにします。
daily と monthly の利用枠は UTC の日付・月の境界でリセットされます。lifetime はリセットされません。上限を変更しても、すでに使用した回数は消去されません。
エクスポート成功後に利用回数を確定する
ビジネス コールバックを SDK に渡します。新しいジョブには新しい ID が必要です。再試行では ID、機能、数量が保持されます。異なるプロセスが同じジョブを同時に実行してはなりません。
| 言語 | 従量制のビジネス呼び出し |
|---|---|
| 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 相当メソッドを使い、永続化した業務タスク ID を渡します。同じタスクを再試行する場合は ID を変えてはいけません。
業務処理が成功して確定通信だけが失敗した場合、同じタスクの再試行は確定処理のみを補完し、業務処理を繰り返しません。処理中に異常終了した場合は自動再実行を止め、保存済みの結果を確認して ResolveMeteredFeature で確定または取消を行います。サーバー側の利用回数とローカルの業務処理は、単一のトランザクションではありません。
予約を自分で制御する必要がある場合
- このエクスポートのジョブ ID を作成して保存します。
- 1 回分を予約し、status が 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 | 予約 ID と元のジョブ 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 です。 |
リクエスト本文、レスポンス、およびフィールド タイプについては、ランタイム API リファレンスの「予約、コミット、およびキャンセル」を参照してください。
業務処理が成功している場合は、予約の取消やエクスポートの再実行を行いません。元の ID と結果を保存し、Commit を再試行します。予約期限が切れた場合は、手動確認できるようタスクを残してください。サーバー側の回数計上とローカルの業務処理は、単一のトランザクションにはなりません。
Consume で直接計上することもできますが、利用回数は直ちに消費されます。業務処理の失敗時に回数を消費したくない場合は、予約・確定の手順を使います。利用回数を扱う API はすべてオンライン接続が必要で、プラットフォームの 4 種類の API 呼び出し枠には含まれません。