本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 交易支援 使用 Amazon Cloud Directory，您通常需要新增物件或新增新物件與現有物件之間的關係，來反映實際階層的變更。批次操作可提供下列好處，讓這類目錄任務更易於管理： + 批次操作可降低對您目錄寫入和讀取物件所需的往返數量，而提升應用程式的整體效能。 + 批次寫入提供與 SQL 資料庫同等的交易語意。所有操作皆會成功完成，如果任一項操作失敗，就不會套用這些操作。 + 使用批次參考，您可以建立物件，並使用對新物件的參考執行進一步的動作，例如將其新增至關係，以及先降低使用讀取操作的成本再執行寫入操作。 ## BatchWrite 使用 [BatchWrite](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_BatchWrite.html) 操作可對目錄執行多個寫入操作。所有批次寫入操作皆循序執行。其運作方式與 SQL 資料庫交易類似。如果批次寫入內其中一個操作失敗，對目錄執行的整個批次寫入就無效。如果批次寫入失敗，會發生批次寫入例外狀況。例外狀況包含失敗操作的索引，以及例外狀況類型和訊息。此資訊可協助您找出失敗的根本原因。 批次寫入支援下列 API 操作： + [AddFacetToObject](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_AddFacetToObject.html) + [AttachObject](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_AttachObject.html) + [AttachPolicy](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_AttachPolicy.html) + [AttachToIndex](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_AttachToIndex.html) + [AttachTypedLink](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_AttachTypedLink.html) + [CreateIndex](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_CreateIndex.html) + [CreateObject](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_CreateObject.html) + [DeleteObject](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_DeleteObject.html) + [DetachFromIndex](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_DetachFromIndex.html) + [DetachObject](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_DetachObject.html) + [DetachTypedLink](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_DetachTypedLink.html) + [RemoveFacetFromObject](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_RemoveFacetFromObject.html) + [UpdateObjectAttributes](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_UpdateObjectAttributes.html) ### 批次參考名稱 當您需要在中介批次操作中參考物件時，僅批次寫入支援批次參考名稱。例如，假設在指定的批次寫入中，先分離 10 個不同的物件，再將其連接到目錄的不同部分。如果沒有批次參考，您就必須讀取所有 10 個物件參考，再於批次寫入中提供該參考作為重新連接過程中的輸入。您可以在連接的過程中使用批次參考識別分離的資源。批次參考可以是任一種開頭為井字號 (\$1) 的一般字串。 例如，在下列程式碼範本中，連結名稱為 `"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](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_BatchRead.html) 操作可對目錄執行多個讀取操作。例如，在下列程式碼範本中，我們讀取了參考為 `“/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 操作： + [GetObjectInformation](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_GetObjectInformation.html) + [ListAttachedIndices](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListAttachedIndices.html) + [ListIncomingTypedLinks](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListIncomingTypedLinks.html) + [ListIndex](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListIndex.html) + [ListObjectAttributes](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListObjectAttributes.html) + [ListObjectChildren](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListObjectChildren.html) + [ListObjectParentPaths](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListObjectParentPaths.html) + [ListObjectPolicies](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListObjectPolicies.html) + [ListOutgoingTypedLinks](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListOutgoingTypedLinks.html) + [ListPolicyAttachments](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListPolicyAttachments.html) + [LookupPolicy](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_LookupPolicy.html) ## 批次操作的限制 無論請求內含多少操作數，向伺服器發出的每個請求 (包括批次請求) 均有可操作的資源數上限。這可讓您極彈性地撰寫批次請求，只要不超過資源上限即可。如需資源上限的詳細資訊，請參閱「[Amazon Cloud Directory 限制](limits.md)」。 限制的計算方式為將批次中各個操作的寫入或讀取相加。例如，目前每個 API 呼叫的讀取操作限制為 200 個物件。假如您想撰寫新增 9 個 [ListObjectChildren](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListObjectChildren.html) API 呼叫的批次，且每個呼叫均需讀取 20 個物件。由於讀取物件總數 (9 x 20 = 180) 未超過 200 個，因此批次操作會成功。 計算寫入操作的概念也是如此。例如，目前的寫入操作限制為 20。如果您將批次設定為新增 2 個 [UpdateObjectAttributes](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_UpdateObjectAttributes.html) API 呼叫，且每個呼叫均執行 9 個寫入操作，這也會成功。無論哪一種情況，只要批次操作超出限制，操作就會失敗，並會拋出 `LimitExceededException`。 計算批次內物件數的正確方式是同時包含實際的節點或 leaf\$1node 物件，如果使用路徑型方法來反覆操作您的樹狀目錄，您還需要包含批次內反覆操作的每個路徑。例如，下圖所示為基本樹狀目錄，若要讀取物件 `003` 的屬性值，則物件的總讀取計數為 3。 ![\[Simple directory tree with root node 001 connected to leaf nodes 002 and 003 via paths 1 and 2.\]](http://docs.aws.amazon.com/zh_tw/clouddirectory/latest/developerguide/images/limits.png) 沿著樹狀目錄向下周遊讀取的運作方式如下： 1. 讀取物件的 `001` 物件，以判斷物件 `003`​ 的路徑。 2. 沿著 `Path 2` 向下移動​ 3. 讀取物件 `003` 同樣地，在屬性數量方面，我們也需計算物件 `001` 和 `003` 中的屬性數量，以確保不會達到限制。 ## 例外狀況處理 Cloud Directory 中的 Batch 操作有時會失敗。在這些情況下，了解如何處理這類失敗非常重要。解決寫入操作失敗的方法與解決讀取操作失敗的方法不同。 ### 批次寫入操作失敗 如果批次寫入操作失敗，Cloud Directory 就無法執行整個批次操作，並會傳回例外狀況。例外狀況內含失敗操作的索引，以及例外狀況類型和訊息。若發生 `RetryableConflictException`，您可以使用指數退避重試。執行此作業的簡單方式是在每次收到例外狀況或失敗後，加倍等待的時間。例如，如果您的第一個批次寫入操作失敗，請等待 100 毫秒後，再重試請求。如果第二個請求失敗，請等待 200 毫秒後再重試。如果第三個請求失敗，請等待 400 毫秒後再重試。 ### 批次讀取操作失敗 如果批次讀取操作失敗，回應會包含成功回應或例外狀況回應。個別批次讀取操作失敗並不會導致整個批次讀取操作失敗，Cloud Directory 會針對每個操作，傳回個別的成功或失敗回應。 **相關 Cloud Directory 部落格文章** + [使用 Batch 操作在 Amazon Cloud Directory 中寫入和讀取多個物件](https://aws.amazon.com/blogs/security/write-and-read-multiple-objects-in-amazon-cloud-directory-by-using-batch-operations/) + [如何在 Amazon Cloud Directory 中使用 Batch 參考來參考 Batch 請求中的新物件](https://aws-preview.aka.amazon.com/blogs/security/how-to-use-batch-references-in-amazon-cloud-directory-to-refer-to-new-objects-in-a-batch-request/)