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

# 屬性參考
<a name="schemas_attributereferences"></a>

Amazon Cloud Directory 的面向包含屬性。屬性可以是屬性定義或屬性參考。屬性定義是宣告其名稱和基本類型 (string、binary、Boolean、DateTime 或 number) 的屬性。該屬性也可選擇性地宣告面向的必要行為、預設值、不可變標記和屬性規則 (例如長度下限/上限)。

屬性參考則是從其他既有的屬性定義衍生其基本類型、預設值、不可變標記和屬性規則的屬性。屬性參考本身不具基本類型、預設值、不可變標記或規則，因為這些屬性皆衍生自目標屬性定義。

屬性參考可覆寫目標定義的必要行為 (以下會詳細說明)。

當您建立屬性參考時，您只需提供屬性名稱和目標屬性定義 (包含目標屬性定義的面向名稱和屬性名稱)。屬性參考不可參考其他屬性參考。另外，此時屬性參考也不可以其他結構描述的屬性定義為目標。

當您希望物件的兩個或多個屬性都參考同一個儲存位置時，您可以使用屬性參考。例如，假設有個套用了 User 面向和 EnterpriseUser 面向的物件。User 面向具有 FirstName 屬性定義，而 EnterpriseUser 面向具有指向 User.FirstName 的屬性參考。由於這兩種 FirstName 屬性都參考物件的同一個儲存位置，因此變更 User.FirstName 或 EnterpriseUser.FirstName 的效果皆相同。

## API 範例
<a name="schemas_referenceapiexample"></a>

下列範例示範如何透過 Cloud Directory API 使用屬性參考。在這個範例中，基礎面向包含屬性定義，而另一個面向則包含參考該基礎面向中屬性的屬性。請注意，雖然基礎面向為 Not Required，參考屬性仍可標示為 Required。

```
    // create base facet
    CreateFacetRequest req1 = new CreateFacetRequest()
      .withSchemaArn(devSchemaArn)
      .withName("baseFacet")
      .withAttributes(List(
        new FacetAttribute()
          .withName("baseAttr")
          .withRequiredBehavior(RequiredAttributeBehavior.NOT_REQUIRED)
          .withAttributeDefinition(new FacetAttributeDefinition().withType(FacetAttributeType.STRING))))
      .withObjectType(ObjectType.DIRECTORY)
    cloudDirectoryClient.createFacet(req1)

    // create another facet that refers to the base facet
    CreateFacetRequest req2 = new CreateFacetRequest()
      .withSchemaArn(devSchemaArn)
      .withName("facetA")
      .withAttributes(List(
        new FacetAttribute()
          .withName("ref")
          .withRequiredBehavior(RequiredAttributeBehavior.REQUIRED_ALWAYS)
          .withAttributeReference(new FacetAttributeReference()
            .withTargetFacetName("baseFacet")
            .withTargetAttributeName("baseAttr"))))
      .withObjectType(ObjectType.DIRECTORY)
    cloudDirectoryClient.createFacet(req2)
```

## JSON 範例：
<a name="schemas_referencejsonexample"></a>

下列範例示範如何在 JSON 模型中使用屬性參考。此模型呈現的結構描述與上述模型相同。

```
 {
  "facets" : {
    "baseFacet" : {
      "facetAttributes" : {
        "baseAttr" : {
          "attributeDefinition" : {
            "attributeType" : "STRING"
          },
          "requiredBehavior" : "NOT_REQUIRED"
        }
      },
      "objectType" : "DIRECTORY"
    },
    "facetA" : {
      "facetAttributes" : {
        "ref" : {
          "attributeReference" : {
            "targetFacetName" : "baseFacet",
            "targetAttributeName" : "baseAttr"
          },
          "requiredBehavior" : "REQUIRED_ALWAYS"
        }
      },
      " objectType" : "DIRECTORY"
    }
}
```

### 屬性參考考量
<a name="schemas_attributerefconsiderations"></a>

屬性參考必須以同一個結構描述中的既有屬性定義為目標。
+ 屬性參考可以同一個面向或不同面向中的既有屬性定義為目標。
+ 屬性參考不可以其他屬性參考為目標。
+ 若面向包含的屬性定義為另一個面向的屬性參考目標，則在所有參考刪除前，該面向不可刪除。

您可以像使用傳統屬性定義一樣，透過建立物件或將面向套用到現有物件來使用屬性參考。

**注意**  
您可以套用參考其他面向的面向，而不必直接套用目標面向。若未套用目標面向，屬性參考的行為就不會變更。(只有當您想要物件上存在目標面向的其他屬性時，才要套用該目標面向。)

### 設定屬性參考值
<a name="schemas_settingattributerefvalues"></a>

當您想要變更屬性值時，可以呼叫 [UpdateObjectAttributes](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_UpdateObjectAttributes.html) API 動作。更新 (或刪除) 該物件之定義或對同一個定義的任何其他參考皆具有相同效果。

### 取得屬性參考值
<a name="schemas_gettingattributerefvalues"></a>

您可以呼叫 [ListObjectAttributes](https://docs.aws.amazon.com/clouddirectory/latest/APIReference/API_ListObjectAttributes.html) API 動作來擷取儲存別名。此呼叫會傳回元組清單，每個清單都包含屬性鍵及其關聯的值。屬性鍵會對應到該物件上存在的儲存別名清單。

**注意**  
若面向未明確套用到物件，屬性鍵仍可能傳回。若屬性參考以未套用到物件的面向為目標，就可能發生這種情況。

例如，假設您具有 User 面向和 EnterpriseUser 面向。EnterpriseUser.FirstName 屬性參考 User.FirstName。接著您將 User 面向和 EnterpriseUser 面向皆套用到物件，並將 User.FirstName 設定為 Robert，再將 EnterpriseUser.FirstName 設定為 Bob。當您呼叫 ListObjectAttributes 時，您只會看到 "User.FirstName = Bob"，因為這兩個 FirstName 屬性只有一個儲存別名。

### 搭配屬性參考使用索引
<a name="schemas_usingindexeswithattributeref"></a>

您只可用屬性定義建立索引，而不可用參考。列出索引並不會傳回屬性參考的屬性鍵。但會傳回索引物件上存在的參考作為目標之任何屬性定義的屬性鍵。換言之，在索引層，屬性參考僅作為屬性的替代識別符，其會在執行時間解析為正確的屬性定義識別符。

例如，假設您具有面向為 User 且屬性為 FirstName 的索引。您先連接僅套用 EnterpriseUser 面向的物件。再將該物件的 EnterpriseUser.FirstName 屬性值設定為 Bob。最後呼叫 ListIndex 動作。結果僅會包含 "User.FirstName = Bob"。

### 屬性參考的必要行為
<a name="schemas_requiredbehaviorattributeref"></a>

屬性參考可以具有與其目標屬性定義不同的必要行為。這讓基礎定義可為選用項，而對同一個定義的參考則可為必要項。當物件具有基礎定義及對該相同基礎定義的一或多個參考時，該基礎定義和所有參考皆必須遵循所有相關屬性存在的最強大必要行為。
+ 與屬性定義一樣，當您建立物件或將面向新增至現有物件時，必須為任何必要屬性定義提供值。
+ 為方便起見，當物件的多個屬性參考相同儲存位置時，您只需為該儲存位置提供一個屬性的值。
+ 同樣地，如果您為相同儲存位置提供多個值，這些值也都必須相等。