本指南提供架構和實作指南，協助開發人員建構 Universal Ledger API 用戶端。您可以瞭解如何執行下列作業：
- 運用網路拓撲，確保高可用性。
- 提交交易並瞭解執行結果。
- 實作輪詢、逾時和重試策略。
連線至 Universal Ledger API 端點
要求會透過 Universal Ledger API 轉送至特定網路端點。網路端點是區域性 Cloud 資源，可將要求分配給該區域內的驗證者。如要連線至網路端點，用戶端必須連線至與該網路端點所在 Cloud 區域相符的區域性 API 端點 (REP)。
區域端點名稱的格式如下：
universalledger.REGION.rep.googleapis.com
將 REGION 替換為網路端點所在的支援區域。
網路拓撲和高可用性
Universal Ledger 網路包含多個驗證器，分布在多個可用區和區域，確保整個網路的高可用性。
可用區故障：如果 Cloud 可用區內有單一驗證器故障，同一區域內的其他驗證器會繼續處理要求，不會中斷。
區域服務中斷：如果整個區域無法使用，其他區域的驗證節點仍可運作。如要繼續提交交易，用戶端可以安全地回復，並嘗試透過其他端點重新提交交易。
交易執行特性
不可分割執行：交易不是完全成功，就是完全失敗。系統絕不會執行部分交易，例如因餘額不足而僅轉移部分要求的資金。這包括交易鏈，可讓您將多個任意交易合併為單一原子序列。
不自動重試：網路會嘗試執行提交的交易，且只執行一次。如果執行失敗，總帳不會自動將交易排入佇列或重試。
冪等重新提交：每筆提交的交易都會根據其確切的序列化酬載 (包括序號和傳送者)，產生專屬交易 ID。多次提交完全相同的酬載，會產生相同的交易 ID。總帳可確保交易最多執行一次，因此如果其中一個端點無法使用，可以安全地將相同的交易酬載重新提交至其他端點。
詳情請參閱
SubmitTransactionRequest參考資料頁面。
延遲、輪詢和重試策略
提交交易時，驗證者會先快速檢查，確保簽章和序號有效。如果成功，Universal Ledger API 會立即回應 SubmitTransactionResponse，包括指派的交易 ID。
大多數交易會在 3 秒內完成。如要查看交易狀態，請使用提供的交易 ID 輪詢 QueryTransactionState 方法。
如果交易狀態仍為
PENDING，請使用指數輪詢策略再次擷取狀態。例如，以 3 秒、9 秒、27 秒和 60 秒的間隔查詢。如果
QueryTransactionState傳回NOT_FOUND，請重新提交交易。
交易嘗試FINALIZED後，回應也會包含 TransactionCertificate，其中包含各種詳細資料，例如：
- 交易完成時的回合 ID。
- 執行狀態 (正常或失敗)。
- 交易事件，包括任何交易輸出。
逾時通訊協定
如果交易在 60 秒後仍處於 PENDING 或 NOT_FOUND 狀態 (這種情況不太可能發生)，請假設處理要求的驗證器無法跟上網路中的其他驗證器。請完成下列步驟：
- 請選取其他網路區域中的其他端點。
- 重新提交完全相同的已簽署交易酬載。
- 請使用本頁頂端的「提供意見」按鈕回報問題，讓 Universal Ledger 團隊調查。
檢查交易狀態時，如果您多次提交相同的酬載，回應可能會包含多個 TransactionAttempt 訊息。最多只有一次嘗試會以 OK 交易狀態完成，可在 TransactionEffects 中找到，而其他嘗試則會處於待處理或失敗狀態。這是預期行為；總帳已成功執行其中一項交易提交作業，並正確拒絕 (或最終會拒絕) 重複提交的作業。
網路一致性
敲定交易：當某個驗證者回報交易已敲定，同一網路上的所有其他驗證者最終都會處理該交易，並產生完全相同的結果。使用交易完成時的回合 ID 提交
QueryAccountRequest(可在TransactionCertificate中找到)，會在所有同步驗證器上產生相同的結果。未完成的交易：由於交易在網路上以非同步方式傳播，因此不同驗證者回報的交易完成狀態可能有所不同。
驗證器從中斷狀態復原或發生同步延遲時，可能會暫時將已完成的交易回報為
PENDING或NOT_FOUND。驗證器趕上進度後，交易狀態就會解決。
用戶端責任和錯誤處理
交易追蹤：用戶端應用程式必須追蹤所有已提交交易的狀態，直到交易完成。
錯誤處理：如果交易失敗，請擷取並檢查
TransactionCertificate中包含的失敗詳細資料，觸發適當的業務層級補救措施。
後續步驟
- 瞭解如何向 Universal Ledger API 傳送 RPC 要求。
- 請參閱 Universal Ledger API 參考資料。