交易支援 - Amazon Cloud Directory
BatchWriteBatchRead批次操作的限制例外狀況處理

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

交易支援

使用 Amazon Cloud Directory，您通常需要新增物件或新增新物件與現有物件之間的關係，來反映實際階層的變更。批次操作可提供下列好處，讓這類目錄任務更易於管理：

  • 批次操作可降低對您目錄寫入和讀取物件所需的往返數量，而提升應用程式的整體效能。

  • 批次寫入提供與 SQL 資料庫同等的交易語意。所有操作皆會成功完成，如果任一項操作失敗，就不會套用這些操作。

  • 使用批次參考，您可以建立物件，並使用對新物件的參考執行進一步的動作，例如將其新增至關係，以及先降低使用讀取操作的成本再執行寫入操作。

BatchWrite

使用 BatchWrite 操作可對目錄執行多個寫入操作。所有批次寫入操作皆循序執行。其運作方式與 SQL 資料庫交易類似。如果批次寫入內其中一個操作失敗，對目錄執行的整個批次寫入就無效。如果批次寫入失敗，會發生批次寫入例外狀況。例外狀況包含失敗操作的索引，以及例外狀況類型和訊息。此資訊可協助您找出失敗的根本原因。

批次寫入支援下列 API 操作：

批次參考名稱

當您需要在中介批次操作中參考物件時，僅批次寫入支援批次參考名稱。例如，假設在指定的批次寫入中，先分離 10 個不同的物件，再將其連接到目錄的不同部分。如果沒有批次參考，您就必須讀取所有 10 個物件參考，再於批次寫入中提供該參考作為重新連接過程中的輸入。您可以在連接的過程中使用批次參考識別分離的資源。批次參考可以是任一種開頭為井字號 (#) 的一般字串。

例如，在下列程式碼範本中，連結名稱為 "this-is-a-typo" 的物件會與根分離，其批次參考名稱為 "ref"。接著同一個物件會連接到連結名稱為 "correct-link-name" 的根。並將子參考設定為批次參考來識別該物件。如果沒有批次參考，您需要先取得分離的 objectIdentifier，然後在連接過程中提供給子參考。您可以使用批次參考名稱避免這種額外讀取的情況。

BatchDetachObject batchDetach = new BatchDetachObject()
        .withBatchReferenceName("ref")
        .withLinkName("this-is-a-typo")
        .withParentReference(new ObjectReference().withSelector("/"));
BatchAttachObject batchAttach = new BatchAttachObject()
        .withParentReference(new ObjectReference().withSelector("/"))
        .withChildReference(new ObjectReference().withSelector("#ref"))
        .withLinkName("correct-link-name");
BatchWriteRequest batchWrite = new BatchWriteRequest()
        .withDirectoryArn(directoryArn)
        .withOperations(new ArrayList(Arrays.asList(batchDetach, batchAttach)));

BatchRead

使用 BatchRead 操作可對目錄執行多個讀取操作。例如，在下列程式碼範本中，我們讀取了參考為 “/managers” 之物件的子系，同時在單一批次讀取中讀取了參考為 “/managers/bob” 之物件的屬性。

BatchListObjectChildren listObjectChildrenRequest = new BatchListObjectChildren()
        .withObjectReference(new ObjectReference().withSelector("/managers"));
BatchListObjectAttributes listObjectAttributesRequest = new BatchListObjectAttributes()
        .withObjectReference(new ObjectReference().withSelector("/managers/bob"));
BatchReadRequest batchRead = new BatchReadRequest()
        .withConsistencyLevel(ConsistencyLevel.SERIALIZABLE)
        .withDirectoryArn(directoryArn)
        .withOperations(new ArrayList(Arrays.asList(listObjectChildrenRequest, listObjectAttributesRequest)));
BatchReadResult result = cloudDirectoryClient.batchRead(batchRead);

BatchRead 支援下列 API 操作：

批次操作的限制

無論請求內含多少操作數，向伺服器發出的每個請求 (包括批次請求) 均有可操作的資源數上限。這可讓您極彈性地撰寫批次請求，只要不超過資源上限即可。如需資源上限的詳細資訊，請參閱「Amazon Cloud Directory 限制」。

限制的計算方式為將批次中各個操作的寫入或讀取相加。例如，目前每個 API 呼叫的讀取操作限制為 200 個物件。假如您想撰寫新增 9 個 ListObjectChildren API 呼叫的批次，且每個呼叫均需讀取 20 個物件。由於讀取物件總數 (9 x 20 = 180) 未超過 200 個，因此批次操作會成功。

計算寫入操作的概念也是如此。例如，目前的寫入操作限制為 20。如果您將批次設定為新增 2 個 UpdateObjectAttributes API 呼叫，且每個呼叫均執行 9 個寫入操作，這也會成功。無論哪一種情況，只要批次操作超出限制，操作就會失敗，並會拋出 LimitExceededException。

計算批次內物件數的正確方式是同時包含實際的節點或 leaf_node 物件，如果使用路徑型方法來反覆操作您的樹狀目錄，您還需要包含批次內反覆操作的每個路徑。例如，下圖所示為基本樹狀目錄，若要讀取物件 003 的屬性值，則物件的總讀取計數為 3。

Simple directory tree with root node 001 connected to leaf nodes 002 and 003 via paths 1 and 2.

沿著樹狀目錄向下周遊讀取的運作方式如下：

1. 讀取物件的 001 物件，以判斷物件 003​ 的路徑。

2. 沿著 Path 2 向下移動​

3. 讀取物件 003

同樣地，在屬性數量方面，我們也需計算物件 001 和 003 中的屬性數量，以確保不會達到限制。

例外狀況處理

Cloud Directory 中的 Batch 操作有時會失敗。在這些情況下，了解如何處理這類失敗非常重要。解決寫入操作失敗的方法與解決讀取操作失敗的方法不同。

批次寫入操作失敗

如果批次寫入操作失敗，Cloud Directory 就無法執行整個批次操作，並會傳回例外狀況。例外狀況內含失敗操作的索引，以及例外狀況類型和訊息。若發生 RetryableConflictException，您可以使用指數退避重試。執行此作業的簡單方式是在每次收到例外狀況或失敗後，加倍等待的時間。例如，如果您的第一個批次寫入操作失敗，請等待 100 毫秒後，再重試請求。如果第二個請求失敗，請等待 200 毫秒後再重試。如果第三個請求失敗，請等待 400 毫秒後再重試。

批次讀取操作失敗

如果批次讀取操作失敗，回應會包含成功回應或例外狀況回應。個別批次讀取操作失敗並不會導致整個批次讀取操作失敗，Cloud Directory 會針對每個操作，傳回個別的成功或失敗回應。

相關 Cloud Directory 部落格文章