本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 格式化規格
Cloud Directory 結構描述會將結構新增至您資料目錄的資料中。Cloud Directory 為您提供兩種定義結構描述的機制。開發人員可以使用特定的 API 操作來建構結構描述，或者他們可以使用結構描述上傳功能來完整上傳結構描述。結構描述文件可以透過 API 呼叫或主控台上傳。本節說明當您上傳整份結構描述文件時要使用的格式。
## JSON 結構描述格式
結構描述文件是使用以下整體格式的 JSON 文件。
```
{
"facets": {
"facet name": {
"facetAttributes": {
"attribute name": Attribute JSON Subsection
}
}
}
}
```
結構描述文件包含面向的面向名稱對應圖。因此每個面向又包含一個屬性對應圖。結構描述內的所有面向名稱必須是唯一的。面向內的所有屬性名稱必須是唯一的。
### 屬性 JSON 子區塊
面向包含屬性。每個屬性定義可存放在屬性的值類型。以下 JSON 格式說明一個屬性。
```
{
"attributeDefinition": Attribute Definition Subsection,
"attributeReference": Attribute Reference Subsection,
"requiredBehavior": "REQUIRED_ALWAYS" or "NOT_REQUIRED"
}
```
您必須提供屬性定義或屬性參考。如需各自的詳細資訊，請參閱相關子區塊。
必要的行為欄位會指出此屬性是否為必要。您必須提供此欄位。可能的值如下：
+ `REQUIRED_ALWAYS`：建立物件或將面向新增到物件時，必須提供此屬性。您不能移除此屬性。
+ `NOT_REQUIRED`：此屬性可能出現，也可能不出現。
### 屬性定義子區塊
屬性會定義與屬性值相關聯的類型和規則。以下 JSON 配置說明格式。
```
{
"attributeType": One of "STRING", "NUMBER", "BINARY", "BOOLEAN" or "DATETIME",
"defaultValue": Default Value Subsection,
"isImmutable": true or false,
"attributeRules": "Attribute Rules Subsection"
}
```
### 預設值子區塊
確實指定下列預設值的其中之一。長值和布林值應位在引號外 (為其各自的 Javascript 類型而不是字串)。使用 URL 安全的 Base64 編碼字串提供二元值 (如 RFC 4648 中所述)。日期時間以自 epoch (1970 年 1 月 1 日 00:00:00 UTC) 起算的毫秒數表示。
```
{
"stringValue": "a string value",
"longValue": an integer value,
"booleanValue": true or false,
"binaryValue": a URL-safe Base64 encoded string,
"datetimeValue": an integer value representing milliseconds since epoch
}
```
### 屬性規則子區塊
屬性規則定義屬性值限制。您可以為每個屬性定義多個規則。屬性規則包含規則的規則類型和一組參數。您可以在「[屬性規則](schemas_attributerules.md)」一節找到詳細資訊。
```
{
"rule name": {
"parameters": {
"rule parameter key 1": "value",
"rule parameter key 2": "value"
},
"ruleType": "rule type value"
}
}
```
### 屬性參考子區塊
屬性參考是進階功能。它們允許多個面向共用屬性定義和存放的值。如需詳細資訊，請參閱[屬性參考](schemas_attributereferences.md)一節。您可以使用以下範本在 JSON 結構描述中定義屬性參考。
```
{
"targetSchemaArn": "schema ARN"
"targetFacetName": "facet name"
"targetAttributeName": "attribute name"
}
```
## 結構描述文件範例
下列結構描述文件範例顯示有效的 JSON 格式。
**注意**
以 `allowedValues` 字串表示的所有值都必須以逗號分隔，且不含空格。例如，`"SENSITIVE,CONFIDENTIAL,PUBLIC"`。
### 基本結構描述文件
```
{
"facets": {
"Employee": {
"facetAttributes": {
"Name": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": false,
"attributeRules": {
"NameLengthRule": {
"parameters": {
"min": "3",
"max": "100"
},
"ruleType": "STRING_LENGTH"
}
}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"EmailAddress": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {
"EmailAddressLengthRule": {
"parameters": {
"min": "3",
"max": "100"
},
"ruleType": "STRING_LENGTH"
}
}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"Status": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": false,
"attributeRules": {
"rule1": {
"parameters": {
"allowedValues": "ACTIVE,INACTIVE,TERMINATED"
},
"ruleType": "STRING_FROM_SET"
}
}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "LEAF_NODE"
},
"DataAccessPolicy": {
"facetAttributes": {
"AccessLevel": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {
"rule1": {
"parameters": {
"allowedValues": "SENSITIVE,CONFIDENTIAL,PUBLIC"
},
"ruleType": "STRING_FROM_SET"
}
}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "POLICY"
},
"Group": {
"facetAttributes": {
"Name": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "NODE"
}
}
}
```
### 使用類型連結的結構描述文件
```
{
"sourceSchemaArn": "",
"facets": {
"employee_facet": {
"facetAttributes": {
"employee_login": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"employee_id": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"employee_name": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"employee_role": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "LEAF_NODE"
},
"device_facet": {
"facetAttributes": {
"device_id": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"device_type": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "NODE"
},
"region_facet": {
"facetAttributes": {},
"objectType": "NODE"
},
"group_facet": {
"facetAttributes": {
"group_type": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "NODE"
},
"office_facet": {
"facetAttributes": {
"office_id": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"office_type": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"office_location": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": true,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"objectType": "NODE"
}
},
"typedLinkFacets": {
"device_association": {
"facetAttributes": {
"device_type": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": false,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
},
"device_label": {
"attributeDefinition": {
"attributeType": "STRING",
"isImmutable": false,
"attributeRules": {}
},
"requiredBehavior": "REQUIRED_ALWAYS"
}
},
"identityAttributeOrder": [
"device_label",
"device_type"
]
}
}
}
```