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

# 使用信標
<a name="using-beacons"></a>


****  

|  | 
| --- |
| 我們的用戶端加密程式庫已重新命名為 AWS 資料庫加密 SDK。此開發人員指南仍提供有關 [DynamoDB 加密用戶端](legacy-dynamodb-encryption-client.md)的資訊。 | 

Beacons 可讓您搜尋加密的記錄，而不會解密要查詢的整個資料庫。信標設計為在新的未填入資料庫中實作。在現有資料庫中設定的任何信標只會映射寫入資料庫的新記錄。信標是根據欄位的純文字值計算，一旦欄位加密，信標就無法映射現有資料。使用信標撰寫新記錄之後，您就無法更新信標的組態。不過，您可以為新增至記錄的新欄位新增新信標。

設定信標之後，您必須先完成下列步驟，才能開始填入資料庫並對信標執行查詢。

1. **建立 AWS KMS 階層 keyring**

   若要使用可搜尋加密，您必須使用[AWS KMS 階層式 keyring](use-hierarchical-keyring.md) 來產生、加密和解密用於保護記錄[的資料金鑰](concepts.md#data-key)。

   設定信標之後，請組合[階層式 keyring 先決條件](use-hierarchical-keyring.md#hierarchical-keyring-prereqs)並[建立階層式 keyring](use-hierarchical-keyring.md#initialize-hierarchical-keyring)。

   如需為何需要階層式 keyring 的詳細資訊，請參閱[使用階層式 keyring 進行可搜尋加密](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings)。

1. 

   **定義信標版本 **

   指定您的 `keyStore`、`keySource`、您設定的所有標準信標清單、您設定的所有複合信標清單、加密組件清單、已簽署組件清單，以及信標版本。您必須`1`為信標版本指定 。如需定義 的指引`keySource`，請參閱 [定義您的信標金鑰來源](use-hierarchical-keyring.md#beacon-key-source)。

   下列 Java 範例定義單一租戶資料庫的信標版本。如需定義多租戶資料庫信標版本的說明，請參閱[多租戶資料庫的可搜尋加密](searchable-encryption-multitenant.md)。

------
#### [ Java ]

   ```
    List<BeaconVersion> beaconVersions = new ArrayList<>();
   beaconVersions.add(
       BeaconVersion.builder()
           .standardBeacons(standardBeaconList)
           .compoundBeacons(compoundBeaconList)
           .encryptedParts(encryptedPartsList)
           .signedParts(signedPartsList)
           .version(1) // MUST be 1
           .keyStore(keyStore)
           .keySource(BeaconKeySource.builder()
               .single(SingleKeyStore.builder()
                   .keyId(branchKeyId)
                   .cacheTTL(6000)
                   .build())
               .build())
           .build()
   );
   ```

------
#### [ C\$1 / .NET ]

   ```
   var beaconVersions = new List<BeaconVersion>
   {
       new BeaconVersion
       {
           StandardBeacons = standardBeaconList,
           CompoundBeacons = compoundBeaconList,
           EncryptedParts = encryptedPartsList,
           SignedParts = signedPartsList,
           Version = 1, // MUST be 1
           KeyStore = branchKeyStoreName,
           KeySource = new BeaconKeySource
           {
               Single = new SingleKeyStore
               {
                   KeyId = branch-key-id,
                   CacheTTL = 6000
               }
           }
       }
   };
   ```

------
#### [ Rust ]

   ```
   let beacon_version = BeaconVersion::builder()
       .standard_beacons(standard_beacon_list)
       .compound_beacons(compound_beacon_list)
       .version(1) // MUST be 1
       .key_store(key_store.clone())
       .key_source(BeaconKeySource::Single(
           SingleKeyStore::builder()
               // `keyId` references a beacon key.
               // For every branch key we create in the keystore,
               // we also create a beacon key.
               // This beacon key is not the same as the branch key,
               // but is created with the same ID as the branch key.
               .key_id(branch_key_id)
               .cache_ttl(6000)
               .build()?,
       ))
       .build()?;
   let beacon_versions = vec![beacon_version];
   ```

------

1. **設定次要索引**

   [設定信標](configure-beacons.md)之後，您必須先設定反映每個信標的次要索引，才能搜尋加密的欄位。如需詳細資訊，請參閱[使用信標設定次要索引](ddb-searchable-encryption.md#ddb-beacon-indexes)。

1. **定義您的[密碼編譯動作](concepts.md#crypt-actions)**

   用於建構標準信標的所有欄位都必須標記為 `ENCRYPT_AND_SIGN`。用於建構信標的所有其他欄位都必須標示 `SIGN_ONLY`或 `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`。

1. **設定 AWS 資料庫加密 SDK 用戶端**

   若要設定 Database AWS Encryption SDK 用戶端來保護 DynamoDB 資料表中的資料表項目，請參閱適用於 [ DynamoDB 的 Java 用戶端加密程式庫](ddb-java.md)。

## 查詢信標
<a name="querying-beacons"></a>

您設定的信標類型會決定您可以執行的查詢類型。標準信標使用篩選條件表達式來執行等式搜尋。複合信標結合常值純文字字串和標準信標，以執行複雜的查詢。當您查詢加密的資料時，您會搜尋信標名稱。

您無法比較兩個標準信標的值，即使它們包含相同的基礎純文字。兩個標準信標將為相同的純文字值產生兩個不同的 HMAC 標籤。因此，標準信標無法執行下列查詢。
+ `beacon1 = beacon2`
+ `beacon1 IN (beacon2)`
+ `value IN (beacon1, beacon2, ...)`
+ `CONTAINS(beacon1, beacon2)`

複合信標可以執行下列查詢。
+ `BEGINS_WITH(a)`，其中 `a`會反映組合複合信標開頭之欄位的整個值。您無法使用 `BEGINS_WITH`運算子來識別以特定子字串開頭的值。不過，您可以使用 `BEGINS_WITH(S_)`，其中 `S_`會反映組合複合信標開頭的部分字首。
+ `CONTAINS(a)`，其中 `a`會反映組合複合信標包含之欄位的整個值。您無法使用 `CONTAINS`運算子來識別包含特定子字串或集合內值的記錄。

  例如，您無法執行查詢，`CONTAINS(path, "a"`其中 `a`會反映集合中的值。
+ 您可以比較複合信標的[簽章部分](configure-beacons.md#signed-parts)。當您比較已簽章的組件時，您可以選擇將[已加密組件](configure-beacons.md#encrypted-parts)的字首附加至一或多個已簽章的組件，但您無法在任何查詢中包含已加密欄位的值。

  例如，您可以在 `signedField1 = signedField2`或 上比較已簽章的組件和查詢`value IN (signedField1, signedField2, ...)`。

  您也可以在 上查詢，比較已簽章的組件和已加密組件的字首`signedField1.A_ = signedField2.B_`。
+ `field BETWEEN a AND b`，其中 `a`和 `b`是帶正負號的部分。您可以選擇將加密部分的字首附加至一或多個已簽章的組件，但您無法在任何查詢中包含加密欄位的值。

您必須在複合信標的查詢中包含每個部分的字首。例如，如果您從`compoundBeacon`兩個欄位 `encryptedField`和 建構複合信標 `signedField`，則必須在查詢信標時包含為這兩個部分設定的字首。

```
compoundBeacon = E_encryptedFieldValue.S_signedFieldValue
```