本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 設定信標 **** | | | --- | | 我們的用戶端加密程式庫已重新命名為 AWS 資料庫加密 SDK。此開發人員指南仍提供有關 [DynamoDB 加密用戶端](legacy-dynamodb-encryption-client.md)的資訊。 | 支援可搜尋加密的信標有兩種類型。標準信標會執行相等性搜尋。它們是在資料庫中實作可搜尋加密的最簡單方法。複合信標結合文字純文字字串和標準信標，以執行更複雜的查詢。 信標設計為在新的未填入資料庫中實作。在現有資料庫中設定的任何信標只會映射寫入資料庫的新記錄。信標是根據欄位的純文字值計算，一旦欄位加密，信標就無法映射現有資料。使用信標撰寫新記錄之後，您就無法更新信標的組態。不過，您可以為新增至記錄的新欄位新增新信標。 決定您的存取模式之後，設定信標應該是資料庫實作的第二個步驟。然後，設定所有信標之後，您需要建立[AWS KMS 階層式 keyring](use-hierarchical-keyring.md)、定義信標版本、[為每個信標設定次要索引](ddb-searchable-encryption.md#ddb-beacon-indexes)、定義[密碼編譯動作](concepts.md#crypt-actions)，以及設定資料庫和 AWS 資料庫加密 SDK 用戶端。如需詳細資訊，請參閱[使用信標](using-beacons.md)。 為了更輕鬆地定義信標版本，建議您為標準信標和複合信標建立清單。在您設定每個信標時，將您建立的每個信標新增至個別的標準或複合信標清單。 **Topics** + [設定標準信標](#config-standard-beacons) + [設定複合信標](#config-compound-beacons) + [範例組態](beacon-config-examples.md) ## 設定標準信標 [標準信標](beacons.md#standard-beacon-overview)是在資料庫中實作可搜尋加密的最簡單方法。他們只能對單一加密或虛擬欄位執行等式搜尋。 ### 組態語法範例 ------ #### [ Java ] ``` List standardBeaconList = new ArrayList<>(); StandardBeacon exampleStandardBeacon = StandardBeacon.builder() .name("beaconName") .length(beaconLengthInBits) .build(); standardBeaconList.add(exampleStandardBeacon); ``` ------ #### [ C\$1 / .NET ] ``` var standardBeaconList = new List(); StandardBeacon exampleStandardBeacon = new StandardBeacon { Name = "beaconName", Length = 10 }; standardBeaconList.Add(exampleStandardBeacon); ``` ------ #### [ Rust ] ``` let standard_beacon_list = vec![ StandardBeacon::builder().name("beacon_name").length(beacon_length_in_bits).build()?, ``` ------ 若要設定標準信標，請提供下列值。 **信標名稱** 您在查詢加密欄位時使用的名稱。 信標名稱可與加密欄位或虛擬欄位的名稱相同，但不能與未加密欄位的名稱相同。我們強烈建議盡可能使用標準信標建構來源的加密欄位或[虛擬欄位](beacons.md#virtual-field)的名稱。兩個不同的信標不能有相同的信標名稱。如需判斷實作最佳信標名稱的說明，請參閱[選擇信標名稱](choosing-beacon-name.md)。 **信標長度** 截斷後保留的信標雜湊值位元數。 信標長度決定指定信標產生的平均誤報數。如需詳細資訊並協助判斷適合您實作的信標長度，請參閱[判斷信標長度](choosing-beacon-length.md)。 **信標來源 （選用）** 標準信標的建構來源欄位。 信標來源必須是參照巢狀欄位值的欄位名稱或索引。當您的信標名稱與信標來源相同時，您可以從組態省略信標來源， AWS 資料庫加密 SDK 會自動使用信標名稱做為信標來源。 ### 建立虛擬欄位 若要建立[虛擬欄位](beacons.md#virtual-field)，您必須提供虛擬欄位的名稱和來源欄位的清單。您新增來源欄位至虛擬組件清單的順序會決定它們串連以建置虛擬欄位的順序。下列範例會串連兩個來源欄位，以建立虛擬欄位。 **注意** 我們建議您先驗證虛擬欄位是否產生預期結果，再填入資料庫。如需詳細資訊，請參閱[測試信標輸出](ddb-searchable-encryption.md#ddb-beacon-testing)。 ------ #### [ Java ] **請參閱完整的程式碼範例**：[VirtualBeaconSearchableEncryptionExample.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/searchableencryption/VirtualBeaconSearchableEncryptionExample.java) ``` List virtualPartList = new ArrayList<>(); virtualPartList.add(sourceField1); virtualPartList.add(sourceField2); VirtualField virtualFieldName = VirtualField.builder() .name("virtualFieldName") .parts(virtualPartList) .build(); List virtualFieldList = new ArrayList<>(); virtualFieldList.add(virtualFieldName); ``` ------ #### [ C\$1 / .NET ] **請參閱完整的程式碼範例**：[VirtualBeaconSearchableEncryptionExample.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/VirtualBeaconSearchableEncryptionExample.cs) ``` var virtualPartList = new List { sourceField1, sourceField2 }; var virtualFieldName = new VirtualField { Name = "virtualFieldName", Parts = virtualPartList }; var virtualFieldList = new List { virtualFieldName }; ``` ------ #### [ Rust ] **請參閱完整的程式碼範例**： [virtual\$1beacon\$1searchable\$1encryption.rs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/virtual_beacon_searchable_encryption.rs) ``` let virtual_part_list = vec![source_field_one, source_field_two]; let state_and_has_test_result_field = VirtualField::builder() .name("virtual_field_name") .parts(virtual_part_list) .build()?; let virtual_field_list = vec![virtual_field_name]; ``` ------ 若要使用來源欄位的特定區段建立虛擬欄位，您必須先定義轉換，才能將來源欄位新增至虛擬組件清單。 #### 虛擬欄位的安全考量 信標不會變更 欄位的加密狀態。不過，當您使用信標時，查詢的效率與資料分佈的公開資訊量之間存在固有權衡。您設定信標的方式會決定該信標所保留的安全層級。 避免使用與現有標準信標重疊的來源欄位建立虛擬欄位。建立包含已用於建立標準信標之來源欄位的虛擬欄位，可以降低兩個信標的安全層級。安全性降低的程度取決於其他來源欄位新增的熵層級。熵程度取決於額外來源欄位中唯一值的分佈，以及額外來源欄位對虛擬欄位整體大小貢獻的位元數。 您可以使用人口和[信標長度](choosing-beacon-length.md)來判斷虛擬欄位的來源欄位是否保留資料集的安全性。人口是欄位中唯一值的預期數量。您的人口不需要精確。如需估算欄位人口的說明，請參閱[估算人口](choosing-beacon-length.md#estimate-population)。 在檢閱虛擬欄位的安全性時，請考慮下列範例。 + Beacon1 由 建構`FieldA`。 `FieldA` 的人口大於 **2 (Beacon1 長度）**。 + Beacon2 由 建構`VirtualField`，其由 `FieldA`、`FieldC`、 `FieldB`和 建構`FieldD`。、`FieldC`、 `FieldB`和 共同`FieldD`擁有大於 **2N** 的人口 如果下列陳述式為 true，Beacon2 會同時保留 Beacon1 和 Beacon2 的安全性： ``` N ≥ (Beacon1 length)/2 ``` 及 ``` N ≥ (Beacon2 length)/2 ``` ### 定義信標樣式 標準信標可用於對加密或虛擬欄位執行等式搜尋。或者，它們可用來建構複合信標，以執行更複雜的資料庫操作。為了協助您組織和管理標準信標， AWS 資料庫加密 SDK 提供下列選用*信標樣式*，可定義標準信標的預期用途。 **注意** 若要定義信標樣式，您必須使用 3.2 版或更新版本的 AWS 資料庫加密 SDK。將信標樣式新增至信標組態之前，先將新版本部署至所有讀取器。 ------ #### [ PartOnly ] 定義為 的標準信標`PartOnly`只能用來定義複合信標的[加密部分](#encrypted-parts)。您無法直接查詢`PartOnly`標準信標。 **Java** ``` List standardBeaconList = new ArrayList<>(); StandardBeacon exampleStandardBeacon = StandardBeacon.builder() .name("beaconName") .length(beaconLengthInBits) .style( BeaconStyle.builder() .partOnly(PartOnly.builder().build()) .build() ) .build(); standardBeaconList.add(exampleStandardBeacon); ``` **C\$1 / .NET** ``` new StandardBeacon { Name = "beaconName", Length = beaconLengthInBits, Style = new BeaconStyle { PartOnly = new PartOnly() } } ``` **Rust** ``` StandardBeacon::builder() .name("beacon_name") .length(beacon_length_in_bits) .style(BeaconStyle::PartOnly(PartOnly::builder().build()?)) .build()? ``` ------ #### [ Shared ] 根據預設，每個標準信標都會產生唯一的 HMAC 金鑰來計算信標。因此，您無法從兩個不同的標準信標對加密的欄位執行等式搜尋。定義為 的標準信標`Shared`會使用另一個標準信標的 HMAC 金鑰進行計算。 例如，如果您需要將`beacon1`欄位與`beacon2`欄位進行比較，請將 `beacon2`定義為使用來自 的 HMAC 金鑰`beacon1`進行計算的`Shared`信標。 **注意** 在設定任何`Shared`信標之前，請考慮您的安全和效能需求。 `Shared`信標可能會增加有關資料集分佈的統計資訊量。例如，它們可能會顯示哪些共用欄位包含相同的純文字值。 **Java** ``` List standardBeaconList = new ArrayList<>(); StandardBeacon exampleStandardBeacon = StandardBeacon.builder() .name("beacon2") .length(beaconLengthInBits) .style( BeaconStyle.builder() .shared(Shared.builder().other("beacon1").build()) .build() ) .build(); standardBeaconList.add(exampleStandardBeacon); ``` **C\$1 / .NET** ``` new StandardBeacon { Name = "beacon2", Length = beaconLengthInBits, Style = new BeaconStyle { Shared = new Shared { Other = "beacon1" } } } ``` **Rust** ``` StandardBeacon::builder() .name("beacon2") .length(beacon_length_in_bits) .style(BeaconStyle::Shared( Shared::builder().other("beacon1").build()?, )) .build()? ``` ------ #### [ AsSet ] 根據預設，如果欄位值是集合， AWS 資料庫加密 SDK 會計算集合的單一標準信標。因此，您無法執行 `CONTAINS(a, :value)` `a`為加密欄位的查詢。定義為 的標準信標會`AsSet`計算集合中每個個別元素的個別標準信標值，並將信標值以集合形式存放在項目中。這可讓 AWS 資料庫加密 SDK 執行查詢 `CONTAINS(a, :value)`。 若要定義`AsSet`標準信標，集合中的元素必須來自相同的人口，以便它們都可以使用相同的[信標長度](choosing-beacon-length.md)。如果在計算信標值時發生衝突，信標集的元素可能少於純文字集。 **注意** 在設定任何`AsSet`信標之前，請考慮您的安全和效能需求。 `AsSet`信標可能會增加有關資料集分佈的統計資訊量。例如，它們可能會顯示純文字集的大小。 **Java** ``` List standardBeaconList = new ArrayList<>(); StandardBeacon exampleStandardBeacon = StandardBeacon.builder() .name("beaconName") .length(beaconLengthInBits) .style( BeaconStyle.builder() .asSet(AsSet.builder().build()) .build() ) .build(); standardBeaconList.add(exampleStandardBeacon); ``` **C\$1 / .NET** ``` new StandardBeacon { Name = "beaconName", Length = beaconLengthInBits, Style = new BeaconStyle { AsSet = new AsSet() } } ``` **Rust** ``` StandardBeacon::builder() .name("beacon_name") .length(beacon_length_in_bits) .style(BeaconStyle::AsSet(AsSet::builder().build()?)) .build()? ``` ------ #### [ SharedSet ] 定義為 的標準信標`SharedSet`結合了 `Shared`和 `AsSet`函數，讓您可以對集合和欄位的加密值執行相等性搜尋。這可讓 AWS 資料庫加密 SDK 執行查詢，`CONTAINS(a, b)`其中 `a` 是加密集，而 `b`是加密欄位。 **注意** 在設定任何`Shared`信標之前，請考慮您的安全和效能需求。 `SharedSet`信標可能會增加有關資料集分佈的統計資訊量。例如，它們可能會顯示純文字集的大小，或哪些共用欄位包含相同的純文字值。 **Java** ``` List standardBeaconList = new ArrayList<>(); StandardBeacon exampleStandardBeacon = StandardBeacon.builder() .name("beacon2") .length(beaconLengthInBits) .style( BeaconStyle.builder() .sharedSet(SharedSet.builder().other("beacon1").build()) .build() ) .build(); standardBeaconList.add(exampleStandardBeacon); ``` **C\$1 / .NET** ``` new StandardBeacon { Name = "beacon2", Length = beaconLengthInBits, Style = new BeaconStyle { SharedSet = new SharedSet { Other = "beacon1" } } } ``` **Rust** ``` StandardBeacon::builder() .name("beacon2") .length(beacon_length_in_bits) .style(BeaconStyle::SharedSet( SharedSet::builder().other("beacon1").build()?, )) .build()? ``` ------ ## 設定複合信標 複合信標結合文字純文字字串和標準信標來執行複雜的資料庫操作，例如從單一索引查詢兩種不同的記錄類型，或查詢具有排序索引鍵的欄位組合。複合信標可以從 `ENCRYPT_AND_SIGN`、 `SIGN_ONLY`和 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` 欄位建構。您必須為複合信標中包含的每個加密欄位建立標準信標。 **注意** 我們建議您先驗證複合信標是否產生預期結果，再填入資料庫。如需詳細資訊，請參閱[測試信標輸出](ddb-searchable-encryption.md#ddb-beacon-testing)。 ### 組態語法範例 ------ #### [ Java ] **複合信標組態** 下列範例會在複合信標組態內於本機定義加密和簽章的組件清單。 ``` List compoundBeaconList = new ArrayList<>(); CompoundBeacon exampleCompoundBeacon = CompoundBeacon.builder() .name("compoundBeaconName") .split(".") .encrypted(encryptedPartList) .signed(signedPartList) .constructors(constructorList) .build(); compoundBeaconList.add(exampleCompoundBeacon); ``` **信標版本定義** 下列範例會在信標版本中全域定義加密和已簽章的組件清單。如需定義信標版本的詳細資訊，請參閱[使用信標](using-beacons.md)。 ``` List beaconVersions = new ArrayList<>(); beaconVersions.add( BeaconVersion.builder() .standardBeacons(standardBeaconList) .compoundBeacons(compoundBeaconList) .encryptedParts(encryptedPartList) .signedParts(signedPartList) .version(1) // MUST be 1 .keyStore(keyStore) .keySource(BeaconKeySource.builder() .single(SingleKeyStore.builder() .keyId(branchKeyId) .cacheTTL(6000) .build()) .build()) .build() ); ``` ------ #### [ C\$1 / .NET ] **請參閱完整的程式碼範例**：[BeaconConfig.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/complexexample/BeaconConfig.cs) **複合信標組態** 下列範例會在複合信標組態內於本機定義加密和簽章的組件清單。 ``` var compoundBeaconList = new List(); var exampleCompoundBeacon = new CompoundBeacon { Name = "compoundBeaconName", Split = ".", Encrypted = encryptedPartList, Signed = signedPartList, Constructors = constructorList }; compoundBeaconList.Add(exampleCompoundBeacon); ``` **信標版本定義** 下列範例會在信標版本中全域定義加密和已簽章的組件清單。如需定義信標版本的詳細資訊，請參閱[使用信標](using-beacons.md)。 ``` var beaconVersions = new List { new BeaconVersion { StandardBeacons = standardBeaconList, CompoundBeacons = compoundBeaconList, EncryptedParts = encryptedPartsList, SignedParts = signedPartsList, Version = 1, // MUST be 1 KeyStore = keyStore, KeySource = new BeaconKeySource { Single = new SingleKeyStore { KeyId = branchKeyId, CacheTTL = 6000 } } } }; ``` ------ #### [ Rust ] **請參閱完整的程式碼範例**： [beacon\$1config.rs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/complexexample/beacon_config.rs) **複合信標組態** 下列範例會在複合信標組態內於本機定義加密和簽章的組件清單。 ``` let compound_beacon_list = vec![ CompoundBeacon::builder() .name("compound_beacon_name") .split(".") .encrypted(encrypted_parts_list) .signed(signed_parts_list) .constructors(constructor_list) .build()? ``` **信標版本定義** 下列範例會在信標版本中全域定義加密和已簽章的組件清單。如需定義信標版本的詳細資訊，請參閱[使用信標](using-beacons.md)。 ``` let beacon_versions = BeaconVersion::builder() .standard_beacons(standard_beacon_list) .compound_beacons(compound_beacon_list) .encrypted_parts(encrypted_parts_list) .signed_parts(signed_parts_list) .version(1) // MUST be 1 .key_store(key_store.clone()) .key_source(BeaconKeySource::Single( SingleKeyStore::builder() .key_id(branch_key_id) .cache_ttl(6000) .build()?, )) .build()?; let beacon_versions = vec![beacon_versions]; ``` ------ 您可以在本機或全域定義的清單中定義[加密的組件](#encrypted-parts)和[已簽章的組件](#signed-parts)。我們建議您盡可能在[信標版本](using-beacons.md#beacon-version)中的全域清單中定義加密和簽章的組件。透過全域定義加密和簽章的組件，您可以定義每個組件一次，然後在多個複合信標組態中重複使用這些組件。如果您只打算使用加密或簽署的部分一次，您可以在複合信標組態的本機清單中定義它。您可以在[建構函數清單中](#constructor-parts)參考本機和全域組件。 如果您全域定義加密和簽章的組件清單，則必須提供建構組件清單，以識別複合信標可以組合複合信標組態中欄位的所有可能方式。 **注意** 若要全域定義加密和已簽章的組件清單，您必須使用 3.2 版或更新版本的 AWS 資料庫加密 SDK。在全域定義任何新組件之前，將新版本部署到所有讀者。 您無法更新現有的信標組態，以全域定義加密和已簽章的組件清單。 若要設定複合信標，請提供下列值。 **信標名稱** 您在查詢加密欄位時使用的名稱。 信標名稱可與加密欄位或虛擬欄位的名稱相同，但不能與未加密欄位的名稱相同。兩個信標不能有相同的信標名稱。如需判斷實作最佳信標名稱的說明，請參閱[選擇信標名稱](choosing-beacon-name.md)。 **分割字元** 用來分隔組成複合信標之部分的字元。 分割字元無法出現在複合信標建構來源之任何欄位的純文字值中。 **加密的組件清單** 識別複合信標中包含`ENCRYPT_AND_SIGN`的欄位。 每個部分都必須包含名稱和字首。部分名稱必須是從加密欄位建構的標準信標名稱。字首可以是任何字串，但必須是唯一的。加密的組件不能具有與已簽署組件相同的字首。建議使用短值來區分部分與複合信標提供的其他部分。 我們建議您盡可能全域定義您的加密組件。如果您只打算在一個複合信標中使用加密部分，您可以考慮在本機定義加密部分。本機定義的加密部分不能具有與全域定義的加密部分相同的字首或名稱。 ``` List encryptedPartList = new ArrayList<>(); EncryptedPart encryptedPartExample = EncryptedPart.builder() .name("standardBeaconName") .prefix("E-") .build(); encryptedPartList.add(encryptedPartExample); ``` ``` var encryptedPartList = new List(); var encryptedPartExample = new EncryptedPart { Name = "compoundBeaconName", Prefix = "E-" }; encryptedPartList.Add(encryptedPartExample); ``` ``` let encrypted_parts_list = vec![ EncryptedPart::builder() .name("standard_beacon_name") .prefix("E-") .build()? ]; ``` **已簽章的組件清單** 識別複合信標中包含的已簽章欄位。 簽章部分是選用的。您可以設定不參考任何已簽章部分的複合信標。 每個部分都必須包含名稱、來源和字首。來源是組件識別的 `SIGN_ONLY`或 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` 欄位。來源必須是參照巢狀欄位值的欄位名稱或索引。如果您的組件名稱識別來源，您可以省略來源， AWS 資料庫加密 SDK 會自動使用該名稱做為來源。我們建議您盡可能將來源指定為組件名稱。字首可以是任何字串，但必須是唯一的。已簽章的部分不能具有與已加密部分相同的字首。建議使用短值來區分部分與複合信標提供的其他部分。 我們建議您盡可能全域定義您的已簽署組件。如果您只打算在一個複合信標中使用已簽署的組件，您可以考慮在本機定義該組件。本機定義的已簽章部分不能具有與全域定義的已簽章部分相同的字首或名稱。 ``` List signedPartList = new ArrayList<>(); SignedPart signedPartExample = SignedPart.builder() .name("signedFieldName") .prefix("S-") .build(); signedPartList.add(signedPartExample); ``` ``` var signedPartsList = new List { new SignedPart { Name = "signedFieldName1", Prefix = "S-" }, new SignedPart { Name = "signedFieldName2", Prefix = "SF-" } }; ``` ``` let signed_parts_list = vec![ SignedPart::builder() .name("signed_field_name_1") .prefix("S-") .build()?, SignedPart::builder() .name("signed_field_name_2") .prefix("SF-") .build()?, ]; ``` **建構器清單** 識別建構*函數*，這些建構函數定義了由複合信標組合加密和簽章組件的不同方式。您可以在建構函數清單中參考本機和全域組件。 如果您從全域定義的加密和簽章組件建構複合信標，則必須提供建構器清單。 如果您未使用任何全域定義的加密或簽章組件來建構複合信標，則建構器清單是選用的。如果您未指定建構函數清單， AWS 資料庫加密 SDK 會組合複合信標與下列預設建構函數。 + 所有已簽章組件依其新增至已簽章組件清單的順序進行 + 依其新增至加密組件清單的順序排列的所有加密組件 + 需要所有組件 **建構函式** 每個建構函數都是*建構函數組件*的排序清單，可定義複合信標的組合方式。建構函數部分會依新增至清單的順序聯結在一起，每個部分以指定的分割字元分隔。 每個建構函數組件都會命名加密的組件或已簽章的組件，並定義該組件在建構函數中為必要或選用。例如，如果您想要在 `Field1`、 `Field1.Field2`和 上查詢複合信標`Field1.Field2.Field3`，請將 `Field2`和 標記為`Field3`選用，並建立一個建構函數。 每個建構函數必須至少有一個必要的部分。我們建議您讓每個建構函數的第一部分成為必要項目，以便在查詢中使用`BEGINS_WITH`運算子。 如果記錄中存在所有必要的組件，建構函數就會成功。當您撰寫新記錄時，複合信標會使用建構函數清單來判斷信標是否可以從提供的值組合。它會嘗試依建構函數新增至建構函數清單的順序組合信標，並使用第一個成功的建構函數。如果沒有建構函數成功，則不會將信標寫入記錄。 所有讀者和寫入者都應指定相同的建構函數順序，以確保其查詢結果正確。 使用以下程序來指定您自己的建構函數清單。 1. 為每個加密的組件和已簽章的組件建立建構組件，以定義是否需要該組件。 建構函數部分名稱必須是其代表的標準信標或已簽章欄位的名稱。 ------ #### [ Java ] ``` ConstructorPart field1ConstructorPart = ConstructorPart.builder() .name("Field1") .required(true) .build(); ``` ------ #### [ C\$1 / .NET ] ``` var field1ConstructorPart = new ConstructorPart { Name = "Field1", Required = true }; ``` ------ #### [ Rust ] ``` let field_1_constructor_part = ConstructorPart::builder() .name("field_1") .required(true) .build()?; ``` ------ 1. 使用您在**步驟 1** 中建立的建構函式部分，為每個可能的複合信標組合方式建立建構函式。 例如，如果您想要在 `Field1.Field2.Field3`和 上查詢 `Field4.Field2.Field3`，則必須建立兩個建構函數。 `Field1`和 `Field4`都可能是必要的，因為它們是在兩個不同的建構函數中定義。 ------ #### [ Java ] ``` // Create a list for Field1.Field2.Field3 queries List field123ConstructorPartList = new ArrayList<>(); field123ConstructorPartList.add(field1ConstructorPart); field123ConstructorPartList.add(field2ConstructorPart); field123ConstructorPartList.add(field3ConstructorPart); Constructor field123Constructor = Constructor.builder() .parts(field123ConstructorPartList) .build(); // Create a list for Field4.Field2.Field1 queries List field421ConstructorPartList = new ArrayList<>(); field421ConstructorPartList.add(field4ConstructorPart); field421ConstructorPartList.add(field2ConstructorPart); field421ConstructorPartList.add(field1ConstructorPart); Constructor field421Constructor = Constructor.builder() .parts(field421ConstructorPartList) .build(); ``` ------ #### [ C\$1 / .NET ] ``` // Create a list for Field1.Field2.Field3 queries var field123ConstructorPartList = new Constructor { Parts = new List { field1ConstructorPart, field2ConstructorPart, field3ConstructorPart } }; // Create a list for Field4.Field2.Field1 queries var field421ConstructorPartList = new Constructor { Parts = new List { field4ConstructorPart, field2ConstructorPart, field1ConstructorPart } }; ``` ------ #### [ Rust ] ``` // Create a list for field1.field2.field3 queries let field1_field2_field3_constructor = Constructor::builder() .parts(vec![ field1_constructor_part, field2_constroctor_part.clone(), field3_constructor_part, ]) .build()?; // Create a list for field4.field2.field1 queries let field4_field2_field1_constructor = Constructor::builder() .parts(vec![ field4_constructor_part, field2_constroctor_part.clone(), field1_constructor_part, ]) .build()?; ``` ------ 1. 建立建構函數清單，其中包含您在**步驟 2** 中建立的所有建構函數。 ------ #### [ Java ] ``` List constructorList = new ArrayList<>(); constructorList.add(field123Constructor); constructorList.add(field421Constructor); ``` ------ #### [ C\$1 / .NET ] ``` var constructorList = new List { field123Constructor, field421Constructor }; ``` ------ #### [ Rust ] ``` let constructor_list = vec![ field1_field2_field3_constructor, field4_field2_field1_constructor, ]; ``` ------ 1. 當您建立複合信標`constructorList`時，請指定 。 # 範例組態 **** | | | --- | | 我們的用戶端加密程式庫已重新命名為 AWS 資料庫加密 SDK。此開發人員指南仍提供有關 [DynamoDB 加密用戶端](legacy-dynamodb-encryption-client.md)的資訊。 | 下列範例示範如何設定標準和複合信標。下列組態不提供信標長度。如需判斷組態適當信標長度的說明，請參閱[選擇信標長度](choosing-beacon-length.md)。 若要查看示範如何設定和使用信標的完整程式碼範例，請參閱 GitHub 上 aws-database-encryption-sdk-dynamodb 儲存庫中的 [Java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/searchableencryption)、.[NET](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/) 和 [Rust](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/) 可搜尋加密範例。 **Topics** + [標準信標](#standard-config-examples) + [複合信標](#compound-config-examples) ## 標準信標 如果您想要查詢 `inspector_id_last4` 欄位是否完全相符，請使用下列組態建立標準信標。 ------ #### [ Java ] ``` List standardBeaconList = new ArrayList<>(); StandardBeacon exampleStandardBeacon = StandardBeacon.builder() .name("inspector_id_last4") .length(beaconLengthInBits) .build(); standardBeaconList.add(exampleStandardBeacon); ``` ------ #### [ C\$1 / .NET ] ``` var standardBeaconList = new List>); StandardBeacon exampleStandardBeacon = new StandardBeacon { Name = "inspector_id_last4", Length = 10 }; standardBeaconList.Add(exampleStandardBeacon); ``` ------ #### [ Rust ] ``` let last4_beacon = StandardBeacon::builder() .name("inspector_id_last4") .length(10) .build()?; let unit_beacon = StandardBeacon::builder().name("unit").length(30).build()?; let standard_beacon_list = vec![last4_beacon, unit_beacon]; ``` ------ ## 複合信標 如果您想要查詢 `inspector_id_last4`和 上的`UnitInspection`資料庫`inspector_id_last4.unit`，請使用下列組態建立複合信標。此複合信標只需要[加密的部分](configure-beacons.md#encrypted-parts)。 ------ #### [ Java ] ``` // 1. Create standard beacons for the inspector_id_last4 and unit fields. List standardBeaconList = new ArrayList<>(); StandardBeacon inspectorBeacon = StandardBeacon.builder() .name("inspector_id_last4") .length(beaconLengthInBits) .build(); standardBeaconList.add(inspectorBeacon); StandardBeacon unitBeacon = StandardBeacon.builder() .name("unit") .length(beaconLengthInBits) .build(); standardBeaconList.add(unitBeacon); // 2. Define the encrypted parts. List encryptedPartList = new ArrayList<>(); // Each encrypted part needs a name and prefix // The name must be the name of the standard beacon // The prefix must be unique // For this example we use the prefix "I-" for "inspector_id_last4" // and "U-" for "unit" EncryptedPart encryptedPartInspector = EncryptedPart.builder() .name("inspector_id_last4") .prefix("I-") .build(); encryptedPartList.add(encryptedPartInspector); EncryptedPart encryptedPartUnit = EncryptedPart.builder() .name("unit") .prefix("U-") .build(); encryptedPartList.add(encryptedPartUnit); // 3. Create the compound beacon. // This compound beacon only requires a name, split character, // and list of encrypted parts CompoundBeacon inspectorUnitBeacon = CompoundBeacon.builder() .name("inspectorUnitBeacon") .split(".") .sensitive(encryptedPartList) .build(); ``` ------ #### [ C\$1 / .NET ] ``` // 1. Create standard beacons for the inspector_id_last4 and unit fields. StandardBeacon inspectorBeacon = new StandardBeacon { Name = "inspector_id_last4", Length = 10 }; standardBeaconList.Add(inspectorBeacon); StandardBeacon unitBeacon = new StandardBeacon { Name = "unit", Length = 30 }; standardBeaconList.Add(unitBeacon); // 2. Define the encrypted parts. var last4EncryptedPart = new EncryptedPart // Each encrypted part needs a name and prefix // The name must be the name of the standard beacon // The prefix must be unique // For this example we use the prefix "I-" for "inspector_id_last4" // and "U-" for "unit" var last4EncryptedPart = new EncryptedPart { Name = "inspector_id_last4", Prefix = "I-" }; encryptedPartList.Add(last4EncryptedPart); var unitEncryptedPart = new EncryptedPart { Name = "unit", Prefix = "U-" }; encryptedPartList.Add(unitEncryptedPart); // 3. Create the compound beacon. // This compound beacon only requires a name, split character, // and list of encrypted parts var compoundBeaconList = new List>); var inspectorCompoundBeacon = new CompoundBeacon { Name = "inspector_id_last4", Split = ".", Encrypted = encryptedPartList }; compoundBeaconList.Add(inspectorCompoundBeacon); ``` ------ #### [ Rust ] ``` // 1. Create standard beacons for the inspector_id_last4 and unit fields. let last4_beacon = StandardBeacon::builder() .name("inspector_id_last4") .length(10) .build()?; let unit_beacon = StandardBeacon::builder().name("unit").length(30).build()?; let standard_beacon_list = vec![last4_beacon, unit_beacon]; // 2. Define the encrypted parts. // The name must be the name of the standard beacon // The prefix must be unique // For this example we use the prefix "I-" for "inspector_id_last4" // and "U-" for "unit" let encrypted_parts_list = vec![ EncryptedPart::builder() .name("inspector_id_last4") .prefix("I-") .build()?, EncryptedPart::builder().name("unit").prefix("U-").build()?, ]; // 3. Create the compound beacon // This compound beacon only requires a name, split character, // and list of encrypted parts let compound_beacon_list = vec![CompoundBeacon::builder() .name("last4UnitCompound") .split(".") .encrypted(encrypted_parts_list) .build()?]; ``` ------