Steamworks 文獻庫
TradeSetUnowned/v0001
於 Steam 經濟體伺服器需要從使用者處移除資產或貨幣,並將之更改為無主狀態時呼叫。 資產伺服器將驗證對此資產或貨幣的更改是否符合規定。 需要檢查資產確實屬於該指定的擁有者、資產或貨幣是否可以交易,以及是否擁有要求的數量。

呼叫方: 交易系統

HTTP 方法: POST

參數:

名稱型別必要說明
keystring此為在夥伴網站上,您在您應用程式的 Steam 經濟設定中提供的「資產伺服器金鑰」。
appiduint32與資產關聯之應用程式的 32 位元 App ID。
owneruint64資產或貨幣的目前擁有者的 64 位元 Steam ID。
contextiduint64資產或貨幣所在的 64 位元脈絡 ID。
assetiduint64要移除的資產的 64 位元 ID。 assetid 或 currencyid 之一將用來表示何種物件應被設為無主。
currencyiduint32要移除的貨幣的 32 位元 ID。 assetid 或 currencyid 之一將用來表示何種物件應被設為無主。
amountuint32要移除的資產或貨幣數量。 如果是不可堆疊的資產,此數字應永遠為 1。
此數字應永遠小於或等於 Steam 經濟體伺服器認為此資產或貨幣在此脈絡中應有的數量, 預設為 1。
trade_start_timeuint32此動作的交易階段的開始時間,表示方法為自 1970 年 1 月 1 日以來的秒數。
audit_actionuint32指定哪種動作導致此資產或貨幣被設為無主的 32 位元數字。
audit_referenceuint64表示此動作與哪項事件關聯的 64 位元數字。 資產伺服器可能會希望紀錄數字,用於稽核或偵錯。
leave_originalbool若將此布林值設為 1(代表 True),便會要求資產伺服器複製物品,並建立新的無主物品,作為指定資產的副本。 只有在客服人員單方面復原交易時才會為 true, 預設為 0(False)。
request_repeatedbool若為 1(代表 True),則代表 Steam 經濟體表示伺服器過去曾做出一模一樣的要求,但未收到明確的成功或失敗的回應。 如果同樣的 audit_action 和 audit_reference 的資產和貨幣已被設為無主,則資產伺服器應該傳回成功,並將 set new_assetid 和 new_contextid 設定為對第一個要求所傳回的值。
is_marketbool如果將其設為 1(代表 True),則要求正在執行,以回應 Steam 社群市集上的某些活動。

傳回

此方法的輸出應以 JSON 格式編碼。

回應:
  • result
    • success - 若方法成功,則為 True。 如果資產伺服器傳回 False,則應將 error 設為解釋原因的字串。

      備註:若 success 被設為 False ,或回應無效或逾時,Steam 將在成功前不斷重試 TradeSetUnowned 要求。 如果錯誤為永久失敗(意即物品已不存在),則應將 should_retry 設為 0。
    • should_retry - 預設狀態下,Steam 將在要求成功前不斷嘗試 TradeSetUnowned 呼叫。 這麼做是為了先確保物品的狀態一致,再決定下一步要做什麼。 然而,如果您知道此為永久性失敗,就算重試回應也不會改變(如物品不存在),便可將此欄位的值設為 0。

      如果您希望明確告知 Steam 錯誤為暫時的(例如您無法查看或修改資料庫),也可將此值設為1。

      由於資產伺服器可能會收到 assetid 相同但 audit_reference 值不同的兩個不同的 TradeSetUnowned 要求,因此必須設定此欄位。 例如,一位使用者也許會嘗試在交易一項物品的同時將該物品上架至社群市集。
      資產伺服器應接受第一個 TradeSetUnowned 要求,然後既然使用者不再擁有該物品,再拒絕第二個要求。 在這個例子裡,由於第二個要求絕不會成功也從未成功,因此 should_retry 應設為 0。

      重要須知:當此值為 0 時,Steam 會假設您的資產伺服器從未應 TradeSetUnowned 要求對此資產進行任何修改。
      因此,請務必記住,只有在您十分確定 TradeSetUnowned 要求絕不會被處理時,才能將此欄位設為 0。 如果設定錯誤,可能會導致使用者丟失物品。
      例如,如果您有處理重複要求,以及檢察該資產是否仍存在的邏輯,那麼最好先處理重複要求。 否則,若為重複要求,您的資產伺服器將傳回表示物品不再存在,並通知 Steam 不再重試,而非正確傳回上一個呼叫的結果。
    • error - 說明呼叫失敗原因的字串。 此訊息將儲存於錯誤紀錄中。錯誤紀錄位於 Steamworks 網站中的「經濟」分頁之下。
    • new_assetid(可選用)- 此資產的無主版本的 64 位元資產 ID, 僅有在轉移資產時設定。 根據資產伺服器實作方法的不同,此值可以是新的資產 ID,也可以與回應中指定的資產 ID 一致。
      預設為與傳入的資產 ID 一致。
    • new_contextid(可選用)- 此資產或貨幣的無主版本的 64 位元脈絡 ID。 根據資產伺服器實作方法的不同,此值可以為不同的脈絡 ID,也可以與回應中指定的脈絡 ID 相同。 預設為傳入的脈絡 ID。

稽核動作

此為目前可以通過此方法傳入的稽核動作列表。 隨時皆可將新的稽核類型加入此列表,因此資產伺服器應準備好處理任何代表稽核動作的無正負號的 32 位元數字。
  • 101 - 提出交易 - 要求為交易提出程序的一部分。 audit_reference 為交易 ID。
  • 102 - 交易復原 - 要求為交易復原程序的一部分。 audit_reference 為交易 ID。