跳到正文
LICENTIVO / INTEGRATION

以每月功能次數限制軟體匯出

設定每個 UTC 月 500 次匯出,讓 SDK 自動預留、執行與結算。保留穩定的業務編號,避免重試重複扣次或重複執行已完成的工作。

功能流程 · 九種 SDK 通用更新日期

1. 設定功能次數規則

在授權策略啟用 export 功能,設定每月上限 500 次,並決定額度耗盡後拒絕,或依該功能的超額規則允許。

功能次數屬於客戶授權,與廠商工作空間方案的裝置額度、API 呼叫額度分開計算。每日與每月功能週期採 UTC,每月於下個 UTC 曆月開始時重設。

2. 啟動一個 SDK 用戶端

依 SDK 文件安裝所用語言,以 product.json 與客戶授權金鑰啟動。九種 SDK 皆有相同計次業務流程;以下展示 Go 呼叫,放入應用程式既有的回傳 error 函式。

一般權益使用 RunFeature,計次操作使用 RunMeteredFeature。本機權益檢查成功,不代表線上剩餘次數足夠。

3. 將業務放入計次回呼

呼叫前持久儲存唯一工作編號,重試相同工作沿用該編號。SDK 先預留一次,再執行回呼,業務成功後確認,確定失敗時取消預留。

Go · 放入回傳 error 的函式
// client was opened once at application startup.
// jobID comes from your durable business task record.
jobID := os.Getenv("LICENTIVO_OPERATION_ID")
if jobID == "" {
    return fmt.Errorf("persist a unique task ID before exporting")
}
err := client.RunMeteredFeature(ctx, "export", 1, jobID, func() error {
    // Return success only after the output has been saved.
    return os.WriteFile("licensed-report.txt", []byte("Metered export\n"), 0600)
})
if err != nil {
    return err
}

4. 恢復中斷的工作

工作已記錄為業務成功時,重試相同編號可繼續結算,無須重新執行回呼。但若程序在業務執行途中結束,SDK 無法判斷外部操作是否已完成。

先檢查業務儲存的結果;確認成功呼叫 ResolveMeteredFeature(ctx, jobID, true),確認失敗則傳 false。此介面只處理計次結算,不執行業務。不可盲目重複付款、交付檔案或其他不可逆操作。

預設預留 15 分鐘,並受 UTC 週期重設邊界限制,必須在到期前完成與結算。可能超過預留時間的長工作不宜直接使用簡單回呼封裝。已取消工作若由客戶重新發起,應使用新工作編號。

5. 驗證計次行為

  1. 先用較小測試額度,成功匯出後已用次數應增加一。
  2. 讓回呼在完成前回傳錯誤,預留應取消。
  3. 重試已記錄成功的編號,確認業務回呼未重複執行。
  4. 耗盡拒絕超額的額度,確認回呼未執行,並顯示下次重設時間。
  5. 在測試環境模擬工作中斷,依儲存的業務紀錄恢復結算。

常見誤用

預留與確認需要連線。離線快取授權不允許離線計次,計次操作被拒絕後不可改成一般權益操作繼續執行。

直接 Consume 會立即扣次。若需要業務成功後才計次,使用計次回呼。業務完成後連線失敗屬於結算恢復問題,不能直接認定業務失敗。

穩定工作編號與 SDK 紀錄有助重試,但不能取代業務交易及結果持久儲存。恢復時需保留業務結果與 SDK 私有快取。