本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 模型工業資產
## 資產概觀
您可以使用 AWS IoT SiteWise 資產建立工業操作的虛擬表示法。**資產**代表裝置、設備片段或將一或多個資料串流上傳至 AWS 雲端的程序。例如，資產裝置可以是風力渦輪機，將空氣溫度、螺旋槳旋轉速度和功率輸出時間序列測量傳送至 AWS IoT SiteWise中的資產屬性。
![\[AWS IoT SiteWise 資產代表工業操作中的裝置。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/sitewise-asset.png)
## 屬性別名可識別設備資料串流
每個資料串流都會對應到唯一的屬性別名。例如，別名 `/company/windfarm/3/turbine/7/temperature` 僅辨識風力發電廠 \$13 中渦輪 \$17 的溫度資料流。您可以設定 AWS IoT SiteWise 資產，以使用數學表達式轉換傳入的測量資料，例如將溫度資料從攝氏轉換為華氏。
## 資產階層代表設備關係
資產也可以代表裝置的邏輯分組，例如整個風力發電場。您可以將資產與其他資產建立關聯，以建立代表複雜工業操作的資產階層。資產可以存取其相關聯子資產中的資料。如此一來，您可以使用 AWS IoT SiteWise 表達式來計算彙總指標，例如風力發電廠的淨功率輸出。
![\[AWS IoT SiteWise 代表裝置關係的資產階層。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/sitewise-asset-hierarchy.png)
## 資產模型會將設備呈現標準化
您必須從資產**模型建立每個資產**。資產模型是宣告式結構，可將資產格式標準化。資產模型會跨相同類型的多個資產強制執行一致的資訊，以便您可以在代表裝置群組的資產中處理資料。例如，製造工廠可能具有 CNC 機器的資產模型，定義屬性，例如溫度、停機時間和生產速率。在上圖中，您會針對所有三個渦輪使用相同的資產模型，因為它們共用一組常見的屬性。
## 工業設備的建模選項
設計工業資產表示法時，請考慮下列選項：
+ **資產模型**代表特定類型的設備或程序。您必須從資產模型建立每個實體資產。例如，化學處理廠可能針對反應堆、混音器和儲存槽有不同的資產模型。
+ **元件模型**定義可重複使用的子組件，您可以包含在資產模型或其他元件模型中。例如，您可以在工廠的多個設備資產模型中包含溫度感應器元件模型。
+ **資產模型界面**會將標準套用至不同的資產模型。例如，「輪換設備」界面可以定義適用於幫浦、渦輪機和馬達的振動、溫度和 RPM 的標準屬性，儘管每個介面都有自己的唯一資產模型。
## 建立和管理資產
定義資產模型後，您可以建立工業操作。若要建立資產，請選取 `ACTIVE` 資產模型以從該模型建立資產。然後，您可以填入資產特定資訊，例如資料串流別名和屬性。在上圖中，您可以從一個資產模型建立三個渦輪資產，然後將資料串流別名，如 `/company/windfarm/3/turbine/7/temperature`，和每個渦輪建立關聯。
您也可以更新和刪除現有的資產、資產模型和元件模型。更新資產模型時，以該資產模型為基礎的每個資產都會反映您對基礎模型所做的任何變更。當您更新元件模型時，這會根據參考元件模型的每個資產模型，套用至每個資產。
## 管理複雜的資產模型
您的資產模型可能非常複雜，例如在建模具有許多子元件的複雜設備時。為了協助讓這類資產模型保持組織和可維護，您可以使用自訂複合模型來將相關屬性分組，或重複使用共用元件。如需詳細資訊，請參閱[自訂複合模型 （元件）](custom-composite-models.md)。
**Topics**
# 資產和模型狀態
當您建立、更新或刪除資產、資產模型或元件模型時，變更需要一些時間才能傳播。 AWS IoT SiteWise 會以非同步方式解決這些操作，並更新每個資源的狀態。每個資產、資產模型和元件模型都有一個狀態欄位，其中包含資源的狀態和任何錯誤訊息，如果適用的話。狀態可以是下列其中一個值：
+ `ACTIVE` – 資源處於作用中狀態。這是您可以查詢資產、資產模型和元件模型並與之互動的唯一狀態。
+ `CREATING` – 正在建立資源。
+ `UPDATING` – 正在更新資源。
+ `DELETING` – 正在刪除資源。
+ `PROPAGATING` – （僅限資產模型和元件模型） 變更正在傳播到所有相依資源 （從資產模型到資產，或從元件模型到資產模型）。
+ `FAILED` – 資源無法在建立或更新操作期間驗證，可能是因為表達式中有循環參考。您可以刪除處於 `FAILED` 狀態的資源。
有些建立、更新和刪除操作會將資產、資產模型或元件模型 AWS IoT SiteWise 置於 操作解析`ACTIVE`時以外的狀態。若要在執行其中一個操作後查詢資源或與之互動，您必須等到狀態變更為 `ACTIVE`。否則，您的請求會失敗。
**Topics**
+ [檢查資產的狀態](check-asset-status.md)
+ [檢查資產或元件模型的狀態](check-model-status.md)
# 檢查資產的狀態
您可以使用 AWS IoT SiteWise 主控台或 API 來檢查資產的狀態。
**Topics**
+ [檢查資產的狀態 （主控台）](#check-asset-status-console)
+ [檢查資產的狀態 (AWS CLI)](#check-asset-status-cli)
## 檢查資產的狀態 （主控台）
使用下列程序來檢查 AWS IoT SiteWise 主控台中資產的狀態。
**檢查資產的狀態 (主控台)**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Assets (資產)**。
1. 選擇要檢查的資產。
**提示**
您可以選擇箭頭圖示來展開資產階層，以尋找您的資產。
1. 在**資產詳細資訊**面板中尋找**狀態**。
![\[AWS IoT SiteWise 狀態為作用中的資產詳細資訊面板。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/sitewise-view-asset-status-console.png)
## 檢查資產的狀態 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 來檢查資產的狀態。
若要檢查資產狀態，請使用 [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html) 操作搭配 `assetId` 參數。
**檢查資產的狀態 (AWS CLI)**
+ 輸入以下命令以描述 Pod。將 *asset-id* 取代為資產的 ID 或外部 ID。外部 ID 是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
```
aws iotsitewise describe-asset --asset-id asset-id
```
此操作會傳回包含資產詳細資料的回應。回應包含具有下列結構的`assetStatus`物件：
```
{
...
"assetStatus": {
"state": "String",
"error": {
"code": "String",
"message": "String"
}
}
}
```
資產的狀態在 JSON 物件的 `assetStatus.state` 中。
# 檢查資產或元件模型的狀態
您可以使用 AWS IoT SiteWise 主控台或 API 來檢查資產模型或元件模型的狀態。
**Topics**
+ [檢查資產模型或元件模型的狀態 （主控台）](#check-model-status-console)
+ [檢查資產模型或元件模型的狀態 (AWS CLI)](#check-model-status-cli)
## 檢查資產模型或元件模型的狀態 （主控台）
使用下列程序在 AWS IoT SiteWise 主控台中檢查資產模型或元件模型的狀態。
**提示**
資產模型和元件模型都列在導覽窗格中**的模型**下。所選資產模型或元件模型**的詳細資訊**面板會指出其類型。
**檢查資產模型或元件模型的狀態 （主控台）**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Models (模型)**。
1. 選擇要檢查的模型。
1. 在**詳細資訊**面板中尋找**狀態**。
![\[AWS IoT SiteWise 「資產模型」頁面螢幕擷取畫面，並反白顯示資產模型狀態。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/sitewise-view-model-status-console.png)
## 檢查資產模型或元件模型的狀態 (AWS CLI)
您可以使用 AWS CLI 來檢查資產模型或元件模型的狀態。
若要檢查資產模型或元件模型的狀態，請使用 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) 操作搭配 `assetModelId` 參數。
**提示**
將元件模型 AWS CLI 定義為資產模型的類型。因此，您針對這兩種類型的模型使用相同的 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) 操作。回應中的 `assetModelType` 欄位指出它是 `ASSET_MODEL`或 `COMPONENT_MODEL`。
**檢查資產模型或元件模型的狀態 (AWS CLI)**
+ 執行下列命令來描述模型。以資產模型或元件模型的 ID 或外部 ID 取代 *asset-model-id*。外部 ID 是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
```
aws iotsitewise describe-asset-model --asset-model-id asset-model-id
```
操作會傳回包含模型詳細資訊的回應。回應包含具有以下結構的 `assetModelStatus` 物件。
```
{
...
"assetModelStatus": {
"state": "String",
"error": {
"code": "String",
"message": "String"
}
}
}
```
模型的狀態在 JSON 物件`assetModelStatus.state`中為 。
# 資產模型版本
AWS IoT SiteWise 支援非同步處理資產模型和元件模型上的建立和更新操作。它也會更新模型的狀態。
AWS IoT SiteWise 傳播有效模型在建立中的變更，並將請求更新至其相依資源 （從資產模型到資產，或從元件模型到資產模型）。然後，它會將模型置於 `ACTIVE` 狀態。
如果提供的模型定義無效， 會將模型 AWS IoT SiteWise 置於 `FAILED` 狀態。變更不會傳播到相依資源。相依資源是指模型處於 `ACTIVE` 狀態時傳播的最後一個模型定義。
根據上述資訊，模型定義有兩種類型的模型版本：
1. **最新版本 –** 在建立或更新請求中接受的最新定義。
1. **作用中版本 –** 最新定義已成功處理，模型狀態為 `ACTIVE`。
根據預設，當在資產模型或元件模型上呼叫描述 APIs時，會傳回模型最新版本的詳細資訊。在某些情況下，需要資產模型或元件模型的作用中版本。請參閱以下範例案例：
+ 具有無效定義的更新操作會使您的資產模型處於 `FAILED` 狀態。您必須擷取資產模型的作用中版本，並建立參考此有效定義的另一個更新請求，以還原變更。
+ 上的應用程式 AWS IoT SiteWise 存在，客戶可以在其中檢視資產及其對應的資產模型。當使用者參考對應至特定資產的資產模型定義，且資產模型處於暫時性 `UPDATING`、 `PROPAGATING`或 `FAILED` 狀態時，最新版本會傳回尚未傳播至其資產的資產模型定義。在此情況下，您必須將資產模型的作用中版本擷取給客戶。
**Topics**
+ [擷取資產模型或元件模型的作用中版本 （主控台）](#active-console)
+ [擷取資產模型或元件模型的作用中版本 (AWS CLI)](#active-cli)
## 擷取資產模型或元件模型的作用中版本 （主控台）
請依照此程序，在 AWS IoT SiteWise 主控台中擷取資產模型或元件模型的作用中版本。
**提示**
資產模型和元件模型都列在導覽窗格中**的模型**下。所選資產模型或元件模型**的詳細資訊**面板會指出其類型。
**擷取資產模型或元件模型的作用中版本 （主控台）**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Models (模型)**。
1. 選擇模型以擷取其作用中版本。
1. 如果模型處於 `ACTIVE` 狀態，則您正在檢視其作用中版本。
1. 如果模型處於暫時性 `UPDATING`、 `PROPAGATING`或 `FAILED` 狀態，請在**詳細資訊**面板中的**狀態**下尋找**作用中版本**。
## 擷取資產模型或元件模型的作用中版本 (AWS CLI)
使用 AWS CLI 擷取資產模型或元件模型的作用中版本。
若要擷取資產模型或元件模型的作用中版本，請使用 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) 操作搭配 `assetModelVersion` 參數。
**提示**
將元件模型 AWS CLI 定義為資產模型的類型。因此，您對這兩種類型的模型使用相同的 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) 操作。回應中的 `assetModelType` 欄位指出它是 `ASSET_MODEL`或 `COMPONENT_MODEL`。
**擷取資產模型或元件模型的作用中版本 (AWS CLI)**
+ 執行下列命令來描述模型。以資產模型或元件模型的 ID 或外部 ID 取代 *asset-model-id*。外部 ID 是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
```
aws iotsitewise describe-asset-model --asset-model-id asset-model-id --asset-model-version ACTIVE
```
操作會傳回包含模型詳細資訊的回應。回應包含具有下列結構的 `assetModelStatus` 物件。
```
{
...
"assetModelName": "string",
"assetModelProperties": [ ... ],
...,
"assetModelVersion": "string"
}
```
# 自訂複合模型 （元件）
當您為特別複雜的工業資產建模時，例如具有許多部分的複雜機器，讓資產模型保持井然有序且可維護可能成為一項挑戰。
在這種情況下，如果您使用 主控台，您可以將自訂複合模型或元件新增至現有的資產模型和元件模型。這些可協助您將相關屬性分組並重新使用子元件定義，以保持組織狀態。
自訂複合模型有兩種類型：
+ **內嵌**自訂複合模型定義一組分組屬性，適用於自訂複合模型所屬的資產模型或元件模型。您可以使用它們來分組相關屬性。它們由名稱、描述和一組資產模型屬性組成。它們不可重複使用。
+ **Component-model-based**自訂複合模型會參考您想要包含在資產模型或元件模型中的元件模型。您可以使用它們在模型中包含標準子組件。它們由名稱、描述及其參考的元件模型 ID 組成。它們沒有自己的屬性；參考的元件模型會將其關聯的屬性提供給任何建立的資產。
以下各節說明如何在設計中使用自訂複合模型。
**Topics**
+ [內嵌自訂複合模型](#inline-composite-models)
+ [Component-model-based自訂複合模型](#component-based-custom-composite-models)
+ [使用路徑來參考自訂複合模型屬性](#property-paths)
## 內嵌自訂複合模型
內嵌自訂複合模型提供透過分組相關屬性來組織資產模型的方法。
例如，假設您想要建立機器人資產的模型。機器人包含伺服馬達、電源供應器和電池。每個元件都有自己的屬性，您想要包含在模型中。您可以定義名為 的資產模型`robot_model`，其屬性如下。
****
| |
| --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/custom-composite-models.html) |
不過，在某些情況下，可能有許多子組件，或者子組件本身可能有許多屬性。在這些情況下，可能會有太多屬性，使其變得難以在模型根目錄的單一平面清單中參考和維護，如上述範例所示。
若要處理這類情況，您可以使用內嵌自訂複合模型來將屬性分組。內嵌自訂複合模型是一種自訂複合模型，可定義自己的屬性。例如，您可以建立機器人的模型，如下所示。
****
| |
| --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/custom-composite-models.html) |
在上述範例中，`servo`、 `powersupply`和 `battery`是`robot_model`資產模型中定義的內嵌自訂複合模型名稱。然後，每個複合模型都會定義自己的屬性。
**注意**
在此情況下，每個自訂複合模型都會定義自己的屬性，因此所有屬性都是資產模型本身的一部分 (`robot_model`在此案例中為 )。這些屬性不會與任何其他資產模型或元件模型共用。例如，如果您建立的其他一些資產模型也有稱為 的內嵌自訂複合模型`servo`，則在 `servo`內變更 `robot_model` 不會影響其他資產模型`servo`的定義。
如果您想要實作這類共用 （例如，對於所有資產模型都可以共用的伺服只有一個定義），您可以改為為其建立元件模型，然後建立參考該模型的**component-model-based**複合模型。如需詳細資訊，請參閱下一節。
如需如何建立內嵌自訂複合模型的詳細資訊，請參閱 [建立自訂複合模型 （元件）](create-custom-composite-models.md)。
## Component-model-based自訂複合模型
您可以在 中建立元件模型， AWS IoT SiteWise 以定義標準的可重複使用子組件。建立元件模型後，您可以在其他資產模型和元件模型中為其新增參考。您可以透過將**component-model-based自訂複合模型**新增至您想要參考元件的任何模型來執行此操作。您可以從許多模型或相同模型中多次新增元件的參考。
透過這種方式，您可以避免跨模型複製相同的定義。它還簡化了維護模型，因為您對元件模型所做的任何變更都會反映在使用該模型的所有資產模型中。
例如，假設您的工業安裝有許多類型的設備，而這些設備都使用相同類型的伺服馬達。其中一些在單一設備中有許多 伺服馬達。您可以為每個設備類型建立資產模型，但不想`servo`每次都重複 的定義。您想要將其建模一次，並在各種資產模型中使用。如果您稍後變更 的定義`servo`，則會在所有模型和資產中更新。
若要以這種方式建立上一個範例中的機器人模型，您可以將 伺服馬達、電源供應器和電池定義為元件模型，如下所示。
****
| |
| --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/custom-composite-models.html) |
****
| |
| --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/custom-composite-models.html) |
****
| |
| --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/custom-composite-models.html) |
然後，您可以定義參考這些元件的資產模型`robot_model`，例如 。多個資產模型可以參考相同的元件模型。您也可以在一個資產模型中多次參考相同的元件模型，例如，如果您的機器人在其中有多個伺服馬達。
****
| |
| --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/custom-composite-models.html) |
如需如何建立元件模型的資訊，請參閱 [建立元件模型](create-component-models.md)。
如需如何在其他模型中參考元件模型的資訊，請參閱[建立自訂複合模型 （元件）](create-custom-composite-models.md)。
## 使用路徑來參考自訂複合模型屬性
當您在資產模型、元件模型或自訂複合模型上建立屬性時，您可以從使用其值的其他屬性參考它，例如[轉換](transforms.md)和[指標](metrics.md)。
AWS IoT SiteWise 提供不同的方法來參考您的 屬性。最簡單的方式通常是使用其屬性 ID。不過，如果您要參考的 屬性位於自訂複合模型上，您可能會發現改為透過*路徑*參考它更有用。
路徑是*路徑區段*的排序序列，根據其在資產模型和複合模型中巢狀複合模型之間的位置指定屬性。
### 取得屬性路徑
您可以從其 [AssetModelProperty](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetModelProperty.html) 的 `path` 欄位取得屬性的路徑。
例如，假設您有一個資產模型`robot_model`，其中包含具有屬性 `servo`的自訂複合模型 `position`。如果您在 上呼叫 [DescribeAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModelCompositeModel.html)`servo`，則 `position` 屬性會列出如下所示`path`的欄位：
```
"path": [
{
"id": "asset model ID",
"name": "robot_model"
},
{
"id": "composite model ID",
"name": "servo"
},
{
"id": "property ID",
"name": "position"
}
]
```
### 使用屬性路徑
當您定義參考其他屬性的屬性時，可以使用屬性路徑，例如轉換或指標。
屬性使用*變數*來參考另一個屬性。如需使用變數的詳細資訊，請參閱 [在公式表達式中使用變數](expression-variables.md)。
當您定義變數以參考屬性時，您可以使用屬性的 ID 或其路徑。
若要定義使用參考屬性路徑的變數，請指定其值`propertyPath`的欄位。
例如，若要定義具有使用路徑參考屬性之指標的資產模型，您可以像這樣將承載傳遞給 [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html)：
```
{
...
"assetModelProperties": [
{
...
"type": {
"metric": {
...
"variables": [
{
"name": "variable name",
"value": {
"propertyPath": [
path segments
]
}
}
],
...
}
},
...
},
...
],
...
}
```
# 資產模型界面
AWS IoT SiteWise 介面設定不同資產模型的標準。它們定義了一個共同的結構，可確保一致性，同時允許實作的變化。
介面與資產模型 （屬性、複合模型和階層） 共用相同的結構，但您無法直接從它們建立資產。相反地，界面會套用至現有的資產模型，以確保標準化。介面不支援元件模型。
使用界面有幾個優點：
+ 不同資產模型變化的標準化屬性和指標
+ 簡化界面層級的指標定義
+ 更有效率地管理複雜的資產階層
+ 每個資產模型變化的獨立屬性生命週期管理
+ 增強跨團隊協作，其中營運團隊專注於實體資產呈現，同時資料團隊跨設備建立標準
建議您先建立資產模型，以建立真實世界工業設備的模型。每個設備類型都有自己的一組屬性，都可以由自己的資產模型表示。
## 資產模型標準化使用案例
介面有助於標準化不同資產模型的屬性，同時保留其唯一特性。
例如，動力傳動車間有四個站點：引擎、傳輸、差異和組件。每個工作站都包含各種設備類型。例如，引擎工作站包含 CNC 機器，但規格不同：有些是 3 軸，其他則是 5 軸。
![\[圖表顯示僅使用資產模型和資產的動力傳動站設備階層。動力傳動車間位於頂端，接著是引擎、傳輸、差異和組裝站在第二層上的每個資產模型。在第三個關卡下，有個別的 CNC 機器透過來自引擎站資產模型的軸進行細分。相反地，也有資產模型源自於組合工作站模型。在第四層， 是以名稱表示個別 CNC 機器或機器人機臂的每個資產。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/models-interface-hierarchy.png)
不過，介面可讓您建立 CNC 機器中常見性的標準。您可以在 界面中使用可重複的屬性，而不是為每個屬性建立資產模型。
例如，您可以：
1. 為每個機器類型類別建立個別的資產模型。在此範例中，這是「CNC 3 軸機器」和「CNC 5 軸機器」。
1. 定義具有常見屬性和指標的標準界面。在此範例中，`Temperature-in-C`、 `Down-time`和 `Running-time`都是套用至兩個 CNC 機器的常見屬性。
1. 將此界面套用至所有 CNC 機器資產模型，仍然允許個別資產模型上的裝置特定屬性。
![\[顯示介面如何簡化上圖中資產模型組織的圖表。它顯示引擎站 CNC 機器的數個可重複參數，現在由傳遞至 3 軸和 5 軸 CNC 機器資產模型的各種屬性的介面所管理，同時還允許每個機器上的裝置特定屬性。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/models-interface-to-asset-models.png)
您也可以在介面層級定義可用性指標。例如， 會根據停機時間和執行時間值來`Avail = avg(Down-time, Running-time)`計算可用性。
使用界面可跨適用設備確保一致的屬性定義和指標，同時維持每個機器類型的獨特特性，以簡化您的資產模型管理。
## 結構和元件
介面包含與資產模型相同的屬性類型：屬性、測量、轉換和指標。在資產模型上疊加時，您可以將現有屬性映射至其介面對等。未映射的界面屬性會在資產模型中自動建立。
介面階層定義彙總指標，而資產模型階層則啟用資產關聯。當您使用 界面時，服務會在運算彙總指標時，自動將資產模型階層映射至界面階層。套用界面後，彙總指標會透過界面階層而非資產模型自己的階層來定義。
## 考量事項
使用介面時，請謹記下列考量事項：
+ 資產模型和界面屬性可以依名稱自動映射或手動映射。計算彙總指標時，服務會自動映射階層。
+ 您無法在連結的資產模型中定義使用界面指標做為輸入的其他指標。
+ 資產模型只能連結到一個界面。不過，您可以將多個資產模型套用至相同的界面。
+ 介面不支援警示。
+ 介面不支援元件模型。
**Topics**
+ [資產模型標準化使用案例](#interface-powertrain-shop-example)
+ [結構和元件](#interface-structure)
+ [考量事項](#interface-considerations)
+ [了解界面資產模型關係](interface-asset-model-relationship.md)
+ [建立界面](interface-create.md)
+ [將界面套用至資產模型](interfaces-link-asset-model.md)
+ [管理介面、連結的資產模型和屬性](interfaces-manage.md)
+ [其他界面範例](interface-additional-examples.md)
# 了解界面資產模型關係
介面和資產模型以互補關係一起運作：
**介面與資產模型**
| 面向 | 介面 | 資產模型 |
| --- | --- | --- |
| 用途 | 定義標準並套用一致性 | 代表實體或邏輯資產 |
| 資產建立 | 無法直接建立資產 | 用來建立資產 |
| Properties | 定義必須在模型中實作的標準屬性 | 可以具有界面套用且唯一的屬性 |
| 指標 | 定義標準計算 | 實作界面指標，並可能有其他指標 |
| 階層 | 定義彙總指標的資料處理階層關係 | 定義資產關聯的實體階層關係 |
當您將界面套用至資產模型時：
+ 資產模型必須對應界面中定義的所有屬性。
+ 屬性映射會定義介面屬性如何對應至資產模型屬性。
+ 映射的資產模型屬性必須與其對應的介面屬性保持同步，且無法以會導致兩者之間不一致的方式修改。
+ 未映射的界面屬性會在資產模型中自動建立。
+ 資產模型可以具有超出界面中定義屬性的其他屬性。
+ 資產模型實作界面指標。界面指標的變更會使用界面傳播到所有資產模型。
+ 介面階層用於運算彙總指標。資產模型階層可以獨立定義，服務會在運算彙總指標時自動映射它們。
這種關係可確保標準化，同時允許代表各種設備類型所需的彈性。
## 標準化現有的資產模型
雖然介面在從頭開始設計新的資產模型時非常有用，但對於標準化可能隨時間獨立發展的現有資產模型也同樣強大。
使用現有的資產模型時，您可以套用界面來標準化指標和屬性：
1. 識別現有資產模型中的常見指標和屬性
1. 建立定義這些標準屬性和指標的界面
1. 使用屬性映射將界面套用至現有的資產模型
1. 使用彙總指標來彙總資產階層中的資料
例如，如果您現有的 CNC 機器資產模型具有不同的屬性名稱，但資料類似，例如 `temp_celsius`、`temperature_c`、`machine_temp`)，您可以：
1. `CNC-INTERFACE` 使用標準化`Temperature-in-C`屬性建立
1. 將此界面套用至每個 CNC 資產模型，將現有的溫度屬性映射至界面的 `Temperature-in-C` 屬性
1. 在計算所有機器統計資料的界面中定義彙總指標 （例如平均溫度）
此方法可讓您維護現有的資產模型，同時獲得標準化和簡化指標計算的優勢。
## 階層關係
介面階層
定義跨不同界面計算和彙總資料的關係。例如，在工廠設定中，界面階層可以連接不同層級的溫度監控界面，以計算平均溫度。例如：機器、生產線和設施。當您定義像 的彙總指標時`AverageTemperature`，界面階層會決定該指標如何將資料從較低層級彙總到較高層級。
資產模型階層
代表資產的實際實體或邏輯結構。例如，CNC 機器資產模型可能是生產線資產模型的一部分，而後者又屬於工廠資產模型。此階層會反映真實世界的關係，並協助以符合實體配置或業務結構的方式組織資產。與界面階層結合時，資產模型階層可協助系統了解彙總計算中應包含哪些資產。
這兩種階層類型一起運作：界面階層定義了如何運算彙總指標，而資產模型階層則定義哪些特定資產應包含在這些計算中。
## 介面指標和彙總計算
界面擅長定義可套用至不同資產模型的標準化指標。這對於彙總來自多個資產的資料的彙總指標特別有用。
當您在 界面中定義指標時，它們會自動套用至實作界面的所有資產模型。這些指標可以參考界面中定義的屬性、使用彙總函數來計算跨資產的統計資料，並確保所有實作資產模型的計算一致。例如，您可以在界面中定義可用性指標，以計算執行時間與總時間的比率：
```
{
"name": "Availability",
"dataType": "DOUBLE",
"type": {
"metric": {
"expression": "Running-time / (Running-time + Down-time) * 100",
"variables": [
{
"name": "Running-time",
"value": {
"propertyId": "${Running-time}"
}
},
{
"name": "Down-time",
"value": {
"propertyId": "${Down-time}"
}
}
],
"window": {
"tumbling": {
"interval": "1h"
}
}
}
},
"unit": "Percent"
}
```
將此界面套用至多個資產模型時，即使基礎屬性名稱不同 （感謝屬性映射），也會一致地計算所有這些模型的可用性指標。
如需定義指標和使用彙總函數的詳細資訊，請參閱 [從屬性和其他資產彙總資料 （指標）](metrics.md)。
### 使用界面彙總指標
介面也可以定義彙總指標，以彙總階層中跨資產的資料。當您在 界面中定義階層並將其套用至資產模型時，您可以建立從子資產彙總資料的指標。
例如，您可以定義指標，以計算工廠中所有 CNC 機器的平均溫度：
```
{
"name": "AverageTemperature",
"dataType": "DOUBLE",
"type": {
"metric": {
"expression": "avg(Temperature-in-C)",
"variables": [
{
"name": "Temperature-in-C",
"value": {
"propertyId": "${Temperature-in-C}",
"hierarchyId": "${CNC-machines}"
}
}
],
"window": {
"tumbling": {
"interval": "1h"
}
}
}
},
"unit": "Celsius"
}
```
此指標使用`avg()`彙總函數來計算階層中所有 CNC 機器的平均溫度。`hierarchyId` 參數指定要用於彙總的階層。
將此界面套用至資產模型時，彙總指標會自動彙總符合階層映射之所有子資產的資料。
# 建立界面
您可以使用 AWS IoT SiteWise 主控台或 建立介面 AWS CLI。
------
#### [ Console ]
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)，然後從導覽窗格中選擇**模型**。
1. 選擇**建立介面**。
1. 為您的界面輸入唯一的**名稱**和選用的**描述**。您也可以選擇性地新增您選擇的**外部 ID**。
1. 將屬性新增至您的界面。您可以新增屬性、測量、轉換和指標，就像使用資產模型一樣。如需詳細資訊，請參閱[建立資產模型 （主控台）](create-asset-models.md#create-asset-model-console)。
1. 選擇**建立界面**以建立界面。
1. 如果您有階層來定義界面之間的父子關係，請選擇**新增階層**並輸入相關詳細資訊。
------
#### [ AWS CLI ]
若要建立介面，請使用 `assetModelType` 參數設定為 的 `CreateAssetModel`操作`INTERFACE`：
```
aws iotsitewise create-asset-model \
--asset-model-name "CNC-INTERFACE" \
--asset-model-description "Standard interface for CNC machines" \
--asset-model-type "INTERFACE" \
--asset-model-properties '[
{
"name": "Temperature-in-C",
"dataType": "DOUBLE",
"type": {
"measurement": {}
},
"unit": "Celsius"
},
{
"name": "Down-time",
"dataType": "DOUBLE",
"type": {
"measurement": {}
},
"unit": "Minutes"
},
{
"name": "Running-time",
"dataType": "DOUBLE",
"type": {
"measurement": {}
},
"unit": "Minutes"
},
{
"name": "Availability",
"dataType": "DOUBLE",
"type": {
"metric": {
"expression": "Running-time / (Running-time + Down-time) * 100",
"variables": [
{
"name": "Running-time",
"value": {
"propertyId": "${Running-time}"
}
},
{
"name": "Down-time",
"value": {
"propertyId": "${Down-time}"
}
}
],
"window": {
"tumbling": {
"interval": "1h"
}
}
}
},
"unit": "Percent"
}
]'
```
------
# 將界面套用至資產模型
將界面套用至資產模型時，您可以將資產模型屬性和階層映射至其界面對等項目。對於未映射的介面屬性，會在資產模型中自動建立對應的屬性。連結後，服務可防止變更會違反界面標準的資產模型。
您一次可以將一個資產模型新增至 界面。不過，多個資產模型可以連結到單一界面。
------
#### [ Console ]
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)，然後從導覽窗格中選擇**模型**。
1. 選取您要套用界面的資產模型。
1. 在**連結資產模型**區段中選擇**連結資產模型**。這會顯示**連結界面**頁面。
1. 在**資產模型和界面**區段中，從選取要**連結的模型下拉式功能表中選取資產模型**。
1. 在**屬性映射**區段中，將每個介面屬性對應至現有的資產模型屬性或建立新的屬性。 AWS IoT SiteWise 會自動在資產模型和介面中連結具有相符名稱的屬性。
1. 檢閱屬性映射，然後選擇**連結界面**。
------
#### [ AWS CLI ]
若要將界面套用至資產模型，請使用 `PutAssetModelInterfaceRelationship`操作：
```
aws iotsitewise put-asset-model-interface-relationship \
--asset-model-id "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
--interface-asset-model-id "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE" \
--property-mapping-configuration '{
"createMissingProperty": true,
"matchByPropertyName": true,
"overrides": [
{
"assetModelPropertyId": "a1b2c3d4-5678-90ab-cdef-44444EXAMPLE",
"interfaceAssetModelPropertyId": "a1b2c3d4-5678-90ab-cdef-33333EXAMPLE"
}
]
}'
```
若要擷取介面關係的相關資訊，請使用 `DescribeAssetModelInterfaceRelationship`操作：
```
aws iotsitewise describe-asset-model-interface-relationship \
--asset-model-id "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
--interface-asset-model-id "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE"
```
若要列出已套用特定界面的所有資產模型，請使用 `ListInterfaceRelationships`操作：
```
aws iotsitewise list-interface-relationships \
--interface-asset-model-id "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE" \
--max-results 10
```
若要刪除介面關係，請使用 `DeleteAssetModelInterfaceRelationship`操作：
```
aws iotsitewise delete-asset-model-interface-relationship \
--asset-model-id "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
--interface-asset-model-id "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE"
```
------
# 管理介面、連結的資產模型和屬性
建立界面並將其連結至資產模型後，您可以透過 主控台或 管理關係、編輯和刪除界面 AWS CLI。
## 修改界面和資產模型關係
若要變更介面與資產模型的關係，請在 AWS IoT SiteWise 主控台或透過 執行下列動作 AWS CLI：
------
#### [ Console ]
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)，然後從導覽窗格中選擇**模型**。
1. 選取您要修改的界面。
1. 選擇要修改和編輯的資產模型。
您可以依照[將界面套用至資產模型](interfaces-link-asset-model.md)指示連結不同的資產模型。
1. 選擇**套用界面**以儲存變更。
------
#### [ AWS CLI ]
若要編輯介面和資產模型關係，請使用 `PutAssetModelInterfaceRelationship`動作。使用您自己的值取代 *your-asset-model-id* 和 *your-interface-asset-model-id*。如需詳細資訊，請參閱《 *AWS IoT SiteWise API 參考*》中的 [PutAssetModelInterfaceRelationship](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetModelInterfaceRelationship.html)。
```
aws iotsitewise put-asset-model-interface-relationship \
--asset-model-id your-asset-model-id \
--interface-asset-model-id your-interface-asset-model-id
```
------
## 修改介面屬性映射
若要變更介面的 屬性，請在 AWS IoT SiteWise 主控台或透過 執行下列動作 AWS CLI：
------
#### [ Console ]
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)，然後從導覽窗格中選擇**模型**。
1. 選取您要修改屬性映射的界面。編輯**屬性映射**頁面隨即出現。
1. 在**屬性映射**區段中，篩選清單以尋找適當的屬性映射。
1. 使用**模型屬性欄變更屬性**。
------
#### [ AWS CLI ]
若要編輯介面和資產模型關係，請使用 `PutAssetModelInterfaceRelationship`動作。使用您自己的值取代 *your-asset-model-id* 和 *your-interface-asset-model-id*。如需詳細資訊，請參閱《 *AWS IoT SiteWise API 參考*》中的 [PutAssetModelInterfaceRelationship](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetModelInterfaceRelationship.html)。
```
aws iotsitewise put-asset-model-interface-relationship \
--asset-model-id your-asset-model-id \
--interface-asset-model-id your-interface-asset-model-id \
```
------
## 列出連結至資產模型的界面
若要取得套用至資產模型的界面清單，請在 AWS IoT SiteWise 主控台中或透過 執行下列動作 AWS CLI：
------
#### [ Console ]
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)，然後從導覽窗格中選擇**模型**。
1. 在**模型**區段中，選擇適當的資產模型或界面。您可以在模型的對應詳細資訊頁面上檢視已套用界面或連結資產模型的清單。
+ 檢視特定界面時，請參閱**連結資產模型**一節。
+ 檢視特定資產模型時，請參閱**已套用介面**一節。
------
#### [ AWS CLI ]
若要列出介面，您可以使用 `ListInterfaceRelationships`操作。將 *your-interface-asset-model-id* 取代為您自己的值。如需詳細資訊，請參閱《 *AWS IoT SiteWise API 參考*》中的 [ListInterfaceRelationships](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListInterfaceRelationships.html)。
```
aws iotsitewise list-interface-relationships \
--interface-asset-model-id your-interface-asset-model-id \
[--next-token your-next-token] \
[--max-results 20]
```
------
## 檢視介面和資產模型關係的詳細資訊
若要查看套用至資產模型之界面的詳細資訊，請在 AWS IoT SiteWise 主控台或透過 執行下列動作 AWS CLI：
------
#### [ Console ]
檢視已套用界面和連結資產模型的詳細資訊。
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)，然後從導覽窗格中選擇**模型**。
1. 在**模型**區段中，搜尋適當的資產模型或界面。選取模型或界面**的名稱**，以開啟包含更多詳細資訊的頁面。
------
#### [ AWS CLI ]
若要檢視介面和資產模型關係的介面詳細資訊，請使用 `DescribeAssetModelInterfaceRelationship`動作。使用您自己的值取代 *your-asset-model-id* 和 *your-interface-asset-model-id*。如需詳細資訊，請參閱《 *AWS IoT SiteWise API 參考*》中的 [DescribeAssetModelInterfaceRelationship](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModelInterfaceRelationship.html)。
```
aws iotsitewise describe-asset-model-interface-relationship \
--asset-model-id your-asset-model-id \
--interface-asset-model-id your-interface-asset-model-id
```
------
## 移除套用至資產模型的界面
若要移除套用至資產模型的界面，請在 AWS IoT SiteWise 主控台或透過 執行下列動作 AWS CLI：
------
#### [ Console ]
我們建議您透過資產模型移除 界面。您也可以刪除界面，或透過特定界面的頁面取消連結界面。
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)，然後從導覽窗格中選擇**模型**。
1. 選取要從中移除界面關係的適當資產模型。
1. 選擇**取消連結資產模型**。
------
#### [ AWS CLI ]
若要從資產模型中移除界面關係，您可以使用 `DeleteAssetModelInterfaceRelationship`動作。將 *your-interface-asset-model-id* 取代為您自己的值。如需詳細資訊，請參閱 *AWS IoT SiteWise API 參考*中的 [DeleteAssetModelInterfaceRelationship](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DeleteAssetModelInterfaceRelationship.html)。
```
aws iotsitewise delete-asset-model-interface-relationship \
--asset-model-id your-asset-model-id \
--interface-asset-model-id your-interface-asset-model-id
```
------
# 其他界面範例
以下是如何在不同的工業案例中使用界面的其他範例：
## 能源產生設備
發電公司可以使用界面來標準化不同類型發電設備的指標：
```
{
"assetModelName": "GENERATOR-INTERFACE",
"assetModelDescription": "Standard interface for power generators",
"assetModelType": "INTERFACE",
"assetModelProperties": [
{
"name": "ActivePower",
"dataType": "DOUBLE",
"type": { "measurement": {} },
"unit": "MW"
},
{
"name": "ReactivePower",
"dataType": "DOUBLE",
"type": { "measurement": {} },
"unit": "MVAR"
},
{
"name": "Frequency",
"dataType": "DOUBLE",
"type": { "measurement": {} },
"unit": "Hz"
},
{
"name": "PowerFactor",
"dataType": "DOUBLE",
"type": {
"metric": {
"expression": "cos(atan(ReactivePower / ActivePower))",
"variables": [
{
"name": "ActivePower",
"value": { "propertyId": "${ActivePower}" }
},
{
"name": "ReactivePower",
"value": { "propertyId": "${ReactivePower}" }
}
],
"window": { "tumbling": { "interval": "5m" } }
}
},
"unit": "None"
}
]
}
```
此界面可套用至各種發電機資產模型 （燃氣渦輪機、蒸汽渦輪機、風力渦輪機），以確保整個機群的電力指標一致。
## 水處理設施
水利公用程式可以使用界面來標準化跨處理廠的監控：
```
{
"assetModelName": "WATER-QUALITY-INTERFACE",
"assetModelDescription": "Standard interface for water quality monitoring",
"assetModelType": "INTERFACE",
"assetModelProperties": [
{
"name": "pH",
"dataType": "DOUBLE",
"type": { "measurement": {} },
"unit": "pH"
},
{
"name": "Turbidity",
"dataType": "DOUBLE",
"type": { "measurement": {} },
"unit": "NTU"
},
{
"name": "DissolvedOxygen",
"dataType": "DOUBLE",
"type": { "measurement": {} },
"unit": "mg/L"
},
{
"name": "QualityIndex",
"dataType": "DOUBLE",
"type": {
"metric": {
"expression": "(pH >= 6.5 && pH <= 8.5 ? 100 : 50) * (Turbidity < 1 ? 1 : 0.8) * (DissolvedOxygen > 5 ? 1 : 0.7)",
"variables": [
{
"name": "pH",
"value": { "propertyId": "${pH}" }
},
{
"name": "Turbidity",
"value": { "propertyId": "${Turbidity}" }
},
{
"name": "DissolvedOxygen",
"value": { "propertyId": "${DissolvedOxygen}" }
}
],
"window": { "tumbling": { "interval": "1h" } }
}
},
"unit": "Score"
}
]
}
```
此界面可確保在所有處理設施中一致地測量水質，無論其特定設備組態為何。
## 階層式界面
可以階層方式組織界面，以支援不同操作層級的彙總指標：
1. **設備層級界面** （例如 `PUMP-INTERFACE`)
+ 屬性：流量、壓力、耗電量、振動
+ 指標：效率、運作狀態分數
1. **程序層級界面** （例如 `PUMPING-STATION-INTERFACE`)
+ 屬性：總流量、平均壓力、總功率
+ 指標：工作站效率、每個磁碟區的營運成本
+ 階層：包含`PUMP-INTERFACE`設備
1. **設施層級界面** （例如 `WATER-FACILITY-INTERFACE`)
+ 屬性：設施輸送量、能源用量、化學用量
+ 指標：設施效率、每單位數量的成本、碳足跡
+ 階層：包含`PUMPING-STATION-INTERFACE`程序
這種階層方法允許在每個層級計算指標，同時在整個操作中保持一致性。
# 設定 AWS IoT SiteWise 物件 IDs
AWS IoT SiteWise 定義各種類型的持久性物件，例如資產、資產模型、屬性和階層。所有這類物件都有唯一識別符，您可以用來擷取、更新和刪除它們。
AWS IoT SiteWise 有不同的選項可供客戶建立 ID。預設會在物件建立時為您 AWS IoT SiteWise 產生一個選項。使用者也可以提供自己的 IDs給您的物件。
**Topics**
+ [使用物件 UUIDs](#object-uuids)
+ [使用外部 IDs](#external-ids)
## 使用物件 UUIDs
中的每個持久性物件 AWS IoT SiteWise 都有 [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) 來識別它。例如，資產模型具有資產模型 ID，資產具有資產 ID，以此類推。此 ID 會在您建立物件時指派，並在物件的生命週期內保持不變。
當您建立新的物件時， 預設會為您 AWS IoT SiteWise 產生唯一的 ID。您也可以在建立時以 UUID 格式提供自己的 ID。
**注意**
UUIDs建立該 UUID AWS 的區域中，以及針對相同物件類型，**必須是**全域唯一的。當 AWS IoT SiteWise 為您自動產生 ID 時，一律是唯一的。如果您選擇自己的 ID，請確定其是唯一的。
例如，如果您透過呼叫 [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html) 建立新的資產模型，您可以在請求的選用`assetModelId`欄位中提供自己的 UUID。
相反地，如果您`assetModelId`省略請求， 會為新的資產模型 AWS IoT SiteWise 產生 UUID。
## 使用外部 IDs
若要以 UUID 以外的某些格式定義您自己的 ID，您可以指派*外部 ID*。例如，如果您重複使用在非 系統中使用的 ID AWS，或更易於人類閱讀，則可以執行此操作。外部 IDs的格式更靈活。您可以使用它們在 API 操作中 AWS IoT SiteWise 參考物件，否則會使用 UUID。
如同 UUIDs，每個外部 ID 在其內容中必須是唯一的。例如，您不能有兩個具有相同外部 ID 的資產模型。此外，與 UUIDs一樣，物件在其生命週期內只能有一個外部 ID，這無法變更。
### 外部 IDs和 UUIDs之間的差異
外部 IDs與 UUIDs的差別如下：
+ 每個物件都有 UUID，但外部 IDs是選用的。
+ AWS IoT SiteWise 永遠不會產生外部 IDs。您自行提供這些項目。
+ 如果物件還沒有，您可以隨時指派外部 ID。
### 外部 IDs的格式
有效的外部 ID 具有下列屬性：
+ 長度介於 2 到 128 個字元之間。
+ 第一個和最後一個字元必須是英數字元 (A-Z、a-z、0-9)。
+ 第一個和最後一個以外的字元必須是英數字元，或下列其中一項： `_-.:`
例如，外部 ID 必須符合下列規則表達式：
`[a-zA-Z0-9][a-zA-Z0-9_\-.:]*[a-zA-Z0-9]+`
### 參考具有外部 IDs物件
在許多您可以使用其 UUID 參考物件的地方，您可以改用其外部 ID，如果有的話。若要這樣做，請將外部 ID 附加至字串 `externalId:`。
例如，假設您有 UUID （資產模型 ID) 為 的資產模型`a1b2c3d4-5678-90ab-cdef-11111EXAMPLE`，其外部 ID 也是 `myExternalId`。呼叫 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) 以取得詳細資訊。您可以使用下列其中一項做為 的值`assetModelId`：
+ 使用資產模型 ID (UUID) 本身： `a1b2c3d4-5678-90ab-cdef-11111EXAMPLE`
+ 使用外部 ID： `externalId:myExternalId`
```
aws iotsitewise describe-asset-model --asset-model-id a1b2c3d4-5678-90ab-cdef-11111EXAMPLE
aws iotsitewise describe-asset-model --asset-model-id externalId:myExternalId
```
**注意**
`externalId:` 字首本身不是外部 ID 的一部分。只有在您將外部 ID 提供給接受 UUIDs或外部 IDs 的 API 操作時，才需要提供 字首。例如，當您查詢或更新現有物件時，請提供 字首。
當您定義物件的外部 ID 時，例如當您建立資產模型時，請勿包含 字首。
對於 中的許多 API 操作，您可以使用外部 IDs 來取代 UUIDs AWS IoT SiteWise，但不是全部。例如，[GetAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValue.html) **必須使用** UUIDs它不支援外部 ID 用量。
若要判斷特定 API 操作是否支援此用量，請參閱 [API 參考](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_Operations.html)。
# 建立 的資產模型、元件模型和界面 AWS IoT SiteWise
AWS IoT SiteWise 資產模型、元件模型和界面可推動工業資料的標準化。資產模型定義整體資產，例如風力渦輪機或生產線。元件模型代表組成資產的個別元件，例如葉片、產生器或感應器。界面可跨不同的資產模型強制執行標準。透過建立這些模型，您可以透過反映工業設備真實世界關係和階層的方式組織和建構資產資料，讓您更輕鬆地監控、分析和維護。
資產模型或元件模型包含名稱、描述、資產屬性和 （選擇性） 自訂複合模型，可將屬性分組在一起，或參考子組件的元件模型。
在 中 AWS IoT SiteWise，您可以建立資產模型、元件模型和界面，以代表工業資產及其元件的結構和屬性。
+ 您可以使用**資產模型**來建立資產。除了上述功能之外，資產模型也可以包含階層定義，以定義資產之間的關係。
+ **元件模型**代表資產模型或其他元件模型中的子組件。當您建立元件模型時，您可以在資產模型和其他元件模型中為其新增參考。不過，您無法直接從元件模型建立資產。
+ **界面**會強制執行不同資產模型的標準。介面定義必須由資產模型實作的常見屬性、指標和階層。您無法直接從介面建立資產，但它們有助於確保類似資產類型的一致性。
建立資產模型或元件模型之後，您可以為其建立自訂複合模型，以將屬性分組在一起或參考現有的元件模型。您也可以將界面連結至資產模型，以強制執行標準化。
如需如何建立資產模型、元件模型和界面的詳細資訊，請參閱下列各節。
**Topics**
+ [在 中建立資產模型 AWS IoT SiteWise](create-asset-models.md)
+ [建立元件模型](create-component-models.md)
+ [定義資料屬性](asset-properties.md)
+ [建立自訂複合模型 （元件）](create-custom-composite-models.md)
# 在 中建立資產模型 AWS IoT SiteWise
AWS IoT SiteWise 資產模型可推動工業資料的標準化。資產模型包含名稱、說明、資產屬性和資產階層定義。例如，您可以定義具有溫度、每分鐘旋轉次數 (RPM) 和功率屬性的風力渦輪機模型。然後，您可以使用淨功率輸出性質和風力發電機階層定義來定義風力發電場模型。
**注意**
建議您從最低層級的節點開始建立操作模型。例如，在建立風力發電場模型之前，先建立風力發電機模型。資產階層定義包含現有資產模型的參考。利用此方法，您可以在建立模型時定義資產階層。
資產模型不能包含其他資產模型。如果您必須將可參考的模型定義為另一個模型中的子組件，則應改為建立 component--> 模型。如需詳細資訊，請參閱[建立元件模型](create-component-models.md)。
下列各節說明如何使用 AWS IoT SiteWise 主控台或 API 來建立資產模型。下列各節也會說明您可用來建立模型的不同類型資產屬性和資產階層。
**Topics**
+ [建立資產模型 （主控台）](#create-asset-model-console)
+ [建立資產模型 (AWS CLI)](#create-asset-model-cli)
+ [範例資產模型](#asset-model-examples)
+ [定義資產模型階層](define-asset-hierarchies.md)
## 建立資產模型 （主控台）
您可以使用 AWS IoT SiteWise 主控台來建立資產模型。 AWS IoT SiteWise 主控台提供各種功能，例如公式自動完成，可協助您定義有效的資產模型。
**建立資產模型 (主控台)**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Models (模型)**。
1. 選擇**建立資產模型**。
1. 在 **Create model (建立模型)** 頁面上，執行下列動作：
1. 輸入資產模型的 **Name (名稱)**，例如 **Wind Turbine** 或 **Wind Turbine Model**。此名稱在您於此區域中帳戶的所有模型間都必須是唯一的。
1. （選用） 新增模型的**外部 ID**。這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
1. (選擇性) 新增模型的 **Measurement definitions (衡量值定義)**。測量代表來自您設備的資料串流。如需詳細資訊，請參閱[從設備定義資料串流 （度量）](measurements.md)。
1. (選擇性) 新增模型的 **Transform definitions (轉換定義)**。轉換是將資料從一個表單映射到另一個表單的公式。如需詳細資訊，請參閱[轉換資料 （轉換）](transforms.md)。
1. (選擇性) 新增模型的 **Metric definitions (指標定義)**。指標是跨時間間隔彙總資料的公式。指標可以從相關聯的資產輸入資料，讓您可以計算代表操作或操作子集的值。如需詳細資訊，請參閱[從屬性和其他資產彙總資料 （指標）](metrics.md)。
1. (選擇性) 新增模型的 **Hierarchy definitions (階層定義)**。階層是資產之間的關係。如需詳細資訊，請參閱[定義資產模型階層](define-asset-hierarchies.md)。
1. (選擇性) 新增資產模型的標籤。如需詳細資訊，請參閱[標記您的 AWS IoT SiteWise 資源](tag-resources.md)。
1. 選擇**建立模型**。
當您建立資產模型時， AWS IoT SiteWise 主控台會導覽至新模型的頁面。在此頁面上，您可以看到模型的 **Status (狀態)**，最初為 **CREATING (建立中)**。此頁面會自動更新，因此您可以等候模型的狀態更新。
**注意**
複雜模型的資產模型建立程序可能需要幾分鐘的時間。在資產模型狀態為 **ACTIVE** 之後，您可以使用資產模型來建立資產。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。
1. （選用） 建立資產模型後，您可以為邊緣設定資產模型。如需 SiteWise Edge 的詳細資訊，請參閱 [在 Edge 上設定 AWS IoT SiteWise 邊緣功能](edge-data-collection-and-processing.md)。
1. 在模型頁面上，選擇**設定邊緣**。
**注意**
資料處理套件 (DPP) 功能不再提供給新客戶使用。現有客戶可以繼續正常使用該服務。如需詳細資訊，請參閱[資料處理套件可用性變更](https://docs.aws.amazon.com/iot-sitewise/latest/appguide/iotsitewise-dpp-availability-change.html)。
1. 在模型組態頁面上，選擇模型的邊緣組態。這會控制 AWS IoT SiteWise 可以運算和存放與此資產模型相關聯屬性的位置。如需為邊緣設定模型的詳細資訊，請參閱 [在 SiteWise Edge 中設定 OPC UA 來源](configure-opcua-source.md)。
1. 針對**自訂節點組態**，選擇您要 AWS IoT SiteWise 運算的位置，並儲存每個資產模型屬性。
**注意**
必須針對相同的位置設定相關聯的轉換和指標。如需為邊緣設定模型的詳細資訊，請參閱 [在 SiteWise Edge 中設定 OPC UA 來源](configure-opcua-source.md)。
1. 選擇**儲存**。在模型頁面上，您的 **Edge 組態**現在應該已**設定**。
## 建立資產模型 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 來建立資產模型。
使用 [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html) 操作建立具有屬性和階層的資產模型。此操作預期會有具備下列結構的承載。
```
{
"assetModelType": "ASSET_MODEL",
"assetModelName": "String",
"assetModelDescription": "String",
"assetModelProperties": Array of AssetModelProperty,
"assetModelHierarchies": Array of AssetModelHierarchyDefinition
}
```
**建立資產模型 (AWS CLI)**
1. 建立名為 `asset-model-payload.json` 的檔案，然後將下列 JSON 物件複製到檔案。
```
{
"assetModelType": "ASSET_MODEL",
"assetModelName": "",
"assetModelDescription": "",
"assetModelProperties": [
],
"assetModelHierarchies": [
],
"assetModelCompositeModels": [
]
}
```
1. 使用您偏好的 JSON 文字編輯器來編輯下列項目的 `asset-model-payload.json` 檔案：
1. 輸入資產模型的名稱 (`assetModelName`)，例如 **Wind Turbine** 或 **Wind Turbine Model**。此名稱在帳戶中的所有資產模型和元件模型中必須是唯一的 AWS 區域。
1. （選用） 輸入資產模型的外部 ID (`assetModelExternalId`)。這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
1. (選擇性) 輸入資產模型的說明 (`assetModelDescription`)，或移除 `assetModelDescription` 鍵值組。
1. (選擇性) 定義模型的資產屬性 (`assetModelProperties`)。如需詳細資訊，請參閱[定義資料屬性](asset-properties.md)。
1. (選擇性) 定義模型的資產階層 (`assetModelHierarchies`)。如需詳細資訊，請參閱[定義資產模型階層](define-asset-hierarchies.md)。
1. （選用） 定義模型的警示。警示會監控其他屬性，讓您可以識別設備或程序何時需要注意。每個警示定義都是複合模型 (`assetModelCompositeModels`)，可標準化警示使用的屬性集。如需詳細資訊，請參閱[在 中使用警示監控資料 AWS IoT SiteWise](industrial-alarms.md)及[在 中定義資產模型的警示 AWS IoT SiteWise](define-alarms.md)。
1. (選擇性) 新增資產模型的標籤 (`tags`)。如需詳細資訊，請參閱[標記您的 AWS IoT SiteWise 資源](tag-resources.md)。
1. 執行以下命令，透過 JSON 文件中的定義建立資產模型。
```
aws iotsitewise create-asset-model --cli-input-json file://asset-model-payload.json
```
操作會傳回回應，其中包含建立資產時您參考的 `assetModelId`。回應還包含模型 (`assetModelStatus.state`) 的狀態，起初為 `CREATING`。在變更傳播之前，資產模型狀態會保持為 `CREATING`。
**注意**
複雜模型的資產模型建立程序可能需要幾分鐘的時間。若要檢查資產模型的目前狀態，請指定 來使用 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) 操作`assetModelId`。資產模型狀態變成 `ACTIVE` 後，您便能使用資產模型來建立資產。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。
1. （選用） 為您的資產模型建立自訂複合模型。使用自訂複合模型，您可以在模型中將屬性分組，或透過參考元件模型來包含子組件。如需詳細資訊，請參閱[建立自訂複合模型 （元件）](create-custom-composite-models.md)。
## 範例資產模型
本節包含資產模型定義範例，可用來使用 AWS CLI 和 AWS IoT SiteWise SDKs建立資產模型。這些資產模型代表風力渦輪機和風力發電廠。風力渦輪機資產會擷取原始感應器資料，並計算功率和平均風速等值。風力發電廠資產會計算數值，例如風力發電廠中所有風力發電機的總功率。
**Topics**
+ [風力發電機資產模型](#example-wind-turbine)
+ [風力發電場資產模型](#example-wind-farm)
### 風力發電機資產模型
下列資產模型可呈現風力發電場中的風力發電機。風力發電機會擷取感應器資料，以計算功率和平均風速等值。
**注意**
此範例模型類似於 AWS IoT SiteWise 示範中的風力渦輪機模型。如需詳細資訊，請參閱[使用 AWS IoT SiteWise 示範](getting-started-demo.md)。
```
{
"assetModelType": "ASSET_MODEL",
"assetModelName": "Wind Turbine Asset Model",
"assetModelDescription": "Represents a turbine in a wind farm.",
"assetModelProperties": [
{
"name": "Location",
"dataType": "STRING",
"type": {
"attribute": {
"defaultValue": "Renton"
}
}
},
{
"name": "Make",
"dataType": "STRING",
"type": {
"attribute": {
"defaultValue": "Amazon"
}
}
},
{
"name": "Model",
"dataType": "INTEGER",
"type": {
"attribute": {
"defaultValue": "500"
}
}
},
{
"name": "Torque (KiloNewton Meter)",
"dataType": "DOUBLE",
"unit": "kNm",
"type": {
"measurement": {}
}
},
{
"name": "Wind Direction",
"dataType": "DOUBLE",
"unit": "Degrees",
"type": {
"measurement": {}
}
},
{
"name": "RotationsPerMinute",
"dataType": "DOUBLE",
"unit": "RPM",
"type": {
"measurement": {}
}
},
{
"name": "Wind Speed",
"dataType": "DOUBLE",
"unit": "m/s",
"type": {
"measurement": {}
}
},
{
"name": "RotationsPerSecond",
"dataType": "DOUBLE",
"unit": "RPS",
"type": {
"transform": {
"expression": "rpm / 60",
"variables": [
{
"name": "rpm",
"value": {
"propertyId": "RotationsPerMinute"
}
}
]
}
}
},
{
"name": "Overdrive State",
"dataType": "DOUBLE",
"type": {
"transform": {
"expression": "gte(torque, 3)",
"variables": [
{
"name": "torque",
"value": {
"propertyId": "Torque (KiloNewton Meter)"
}
}
]
}
}
},
{
"name": "Average Power",
"dataType": "DOUBLE",
"unit": "Watts",
"type": {
"metric": {
"expression": "avg(torque) * avg(rps) * 2 * 3.14",
"variables": [
{
"name": "torque",
"value": {
"propertyId": "Torque (Newton Meter)"
}
},
{
"name": "rps",
"value": {
"propertyId": "RotationsPerSecond"
}
}
],
"window": {
"tumbling": {
"interval": "5m"
}
}
}
}
},
{
"name": "Average Wind Speed",
"dataType": "DOUBLE",
"unit": "m/s",
"type": {
"metric": {
"expression": "avg(windspeed)",
"variables": [
{
"name": "windspeed",
"value": {
"propertyId": "Wind Speed"
}
}
],
"window": {
"tumbling": {
"interval": "5m"
}
}
}
}
},
{
"name": "Torque (Newton Meter)",
"dataType": "DOUBLE",
"unit": "Nm",
"type": {
"transform": {
"expression": "knm * 1000",
"variables": [
{
"name": "knm",
"value": {
"propertyId": "Torque (KiloNewton Meter)"
}
}
]
}
}
},
{
"name": "Overdrive State Time",
"dataType": "DOUBLE",
"unit": "Seconds",
"type": {
"metric": {
"expression": "statetime(overdrive_state)",
"variables": [
{
"name": "overdrive_state",
"value": {
"propertyId": "Overdrive State"
}
}
],
"window": {
"tumbling": {
"interval": "5m"
}
}
}
}
}
],
"assetModelHierarchies": []
}
```
### 風力發電場資產模型
下列資產模型可呈現包括多個風力發電機的風力發電場。此資產模型會定義風力渦輪機模型的[階層](define-asset-hierarchies.md)。這可讓風力發電廠從風力發電廠中所有風力發電機的資料計算值 （例如平均功率）。
**注意**
此範例模型類似於 AWS IoT SiteWise 示範中的風力發電廠模型。如需詳細資訊，請參閱[使用 AWS IoT SiteWise 示範](getting-started-demo.md)。
此資產模型取決於 [風力發電機資產模型](#example-wind-turbine)。將 `propertyId` 和 `childAssetModelId` 值取代為來自現有風力發電機資產模型中的值。
```
{
"assetModelName": "Wind Farm Asset Model",
"assetModelDescription": "Represents a wind farm.",
"assetModelProperties": [
{
"name": "Code",
"dataType": "INTEGER",
"type": {
"attribute": {
"defaultValue": "300"
}
}
},
{
"name": "Location",
"dataType": "STRING",
"type": {
"attribute": {
"defaultValue": "Renton"
}
}
},
{
"name": "Reliability Manager",
"dataType": "STRING",
"type": {
"attribute": {
"defaultValue": "Mary Major"
}
}
},
{
"name": "Total Overdrive State Time",
"dataType": "DOUBLE",
"unit": "seconds",
"type": {
"metric": {
"expression": "sum(overdrive_state_time)",
"variables": [
{
"name": "overdrive_state_time",
"value": {
"propertyId": "ID of Overdrive State Time property in Wind Turbine Asset Model",
"hierarchyId": "Turbine Asset Model"
}
}
],
"window": {
"tumbling": {
"interval": "5m"
}
}
}
}
},
{
"name": "Total Average Power",
"dataType": "DOUBLE",
"unit": "Watts",
"type": {
"metric": {
"expression": "sum(turbine_avg_power)",
"variables": [
{
"name": "turbine_avg_power",
"value": {
"propertyId": "ID of Average Power property in Wind Turbine Asset Model",
"hierarchyId": "Turbine Asset Model"
}
}
],
"window": {
"tumbling": {
"interval": "5m"
}
}
}
}
}
],
"assetModelHierarchies": [
{
"name": "Turbine Asset Model",
"childAssetModelId": "ID of Wind Turbine Asset Model"
}
]
}
```
# 定義資產模型階層
您可以定義資產模型階層，在工業操作中的資產模型之間建立邏輯關聯。例如，您可以定義由陸上和海上風力發電廠組成的風力發電廠。陸上風力發電廠包含渦輪機和陸上位置。海上風力發電廠包含渦輪機和海上位置。
![\[AWS IoT SiteWise 資產模型之間的風力發電廠階層。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/asset-model-hierarchies.png)
當您透過階層將子資產模型與父資產模型建立關聯時，父資產模型的指標可以從子資產模型的指標輸入資料。您可以使用資產模型階層和指標來計算統計資料，以深入了解您的操作或操作的子集。如需詳細資訊，請參閱[從屬性和其他資產彙總資料 （指標）](metrics.md)。
每個階層都會定義父資產模型與子資產模型之間的關係。在父資產模型中，您可以為相同的子資產模型定義多個階層。例如，如果您的風力發電廠中有兩個不同類型的風力發電機，其中所有風力發電機都由相同的資產模型表示，您可以為每個類型定義階層。然後，您可以在風力發電廠模型中定義指標，以計算每種風力發電機類型的獨立和合併統計資料。
父資產模型可以與多個子資產模型建立關聯。例如，如果您有由兩個不同的資產模型所代表的陸上風力發電廠和海上風力發電廠，您可以將這些資產模型與相同的父風力發電廠資產模型建立關聯。
子資產模型也可以與多個父資產模型建立關聯。例如，如果您有兩個不同類型的風力發電廠，其中所有風力發電機都由相同的資產模型表示，您可以將風力發電機資產模型與不同的風力發電廠資產模型建立關聯。
**注意**
當您定義資產模型階層時，子資產模型必須是`ACTIVE`或具有先前的`ACTIVE`版本。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。
定義階層式資產模型並建立資產之後，您可以將資產關聯，以完成父子關係。如需詳細資訊，請參閱[在 中建立資產模型的資產 AWS IoT SiteWise](create-assets.md)及[關聯和取消關聯資產](add-associated-assets.md)。
**Topics**
+ [定義資產模型階層 （主控台）](#define-asset-hierarchies-console)
+ [定義資產階層 (AWS CLI)](#define-asset-hierarchies-cli)
## 定義資產模型階層 （主控台）
當您在 AWS IoT SiteWise 主控台中定義資產模型的階層時，您可以指定下列參數：
+ **階層名稱** – 階層的名稱，例如 **Wind Turbines**。
+ **階層模型** – 子資產模型。
+ **階層外部 ID** （選用） – 這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
如需詳細資訊，請參閱[建立資產模型 （主控台）](create-asset-models.md#create-asset-model-console)。
## 定義資產階層 (AWS CLI)
當您使用 AWS IoT SiteWise API 定義資產模型的階層時，您可以指定下列參數：
+ `name` – 階層的名稱，例如 **Wind Turbines**。
+ `childAssetModelId` – 階層的子資產模型 ID 或外部 ID。您可以使用 [ListassetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssetModels.html) 操作來尋找現有資產模型的 ID。
**Example 範例階層定義**
下列範例示範資產模型階層，其代表風力發電廠與風力發電機的關係。此物件是 [AssetModelHierarchy](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetModelHierarchy.html) 的範例。如需詳細資訊，請參閱[建立資產模型 (AWS CLI)](create-asset-models.md#create-asset-model-cli)。
```
{
...
"assetModelHierarchies": [
{
"name": "Wind Turbines",
"childAssetModelId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE"
},
]
}
```
# 建立元件模型
使用 AWS IoT SiteWise 元件模型來定義您可以從資產模型或其他元件模型參考的子組件。如此一來，您可以在多個其他模型中重複使用元件的定義，或在相同的模型內多次使用元件。
定義元件模型的程序與定義資產模型非常類似。如同資產模型，元件模型具有名稱、描述和資產屬性。不過，元件模型不能包含資產階層定義，因為元件模型本身無法直接用來建立資產。元件模型也無法定義警示。
例如，您可以定義具有馬達溫度、編碼器溫度和隔離電阻屬性的 伺服馬達元件。然後，您可以為包含 伺服馬達的設備定義資產模型，例如 CNC 機器。
**注意**
建議您從最低層級的節點開始建立操作模型。例如，在建立 CNC 機器的資產模型之前，請先建立您的伺服馬達元件。資產模型包含現有元件模型的參考。
您無法直接從元件模型建立資產。若要建立使用您的元件的資產，您必須為資產建立資產模型。然後，您可以為其建立參考元件的自訂複合模型。如需建立資產模型的詳細資訊，請參閱[在 中建立資產模型 AWS IoT SiteWise](create-asset-models.md)。如需建立自訂複合模型的詳細資訊，請參閱[建立自訂複合模型 （元件）](create-custom-composite-models.md)。
下列各節說明如何使用 AWS IoT SiteWise API 建立元件模型。
**Topics**
+ [建立元件模型 (AWS CLI)](#create-component-model-cli)
+ [元件模型範例](#component-model-example)
## 建立元件模型 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 來建立元件模型。
使用 [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html) 操作建立具有 屬性的元件模型。此操作預期承載具有下列結構：
```
{
"assetModelType": "COMPONENT_MODEL",
"assetModelName": "String",
"assetModelDescription": "String",
"assetModelProperties": Array of AssetModelProperty,
}
```
**建立元件模型 (AWS CLI)**
1. 建立名為 的檔案，`component-model-payload.json`然後將下列 JSON 物件複製到 檔案：
```
{
"assetModelType": "COMPONENT_MODEL",
"assetModelName": "",
"assetModelDescription": "",
"assetModelProperties": [
]
}
```
1. 使用您偏好的 JSON 文字編輯器來編輯下列項目的 `component-model-payload.json` 檔案：
1. 輸入元件模型的名稱 (`assetModelName`)，例如 **Servo Motor**或 **Servo Motor Model**。此名稱在帳戶中的所有資產模型和元件模型中必須是唯一的 AWS 區域。
1. （選用） 輸入元件模型的外部 ID (`assetModelExternalId`)。這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
1. (選擇性) 輸入資產模型的說明 (`assetModelDescription`)，或移除 `assetModelDescription` 鍵值組。
1. （選用） 定義元件模型的資產屬性 (`assetModelProperties`)。如需詳細資訊，請參閱[定義資料屬性](asset-properties.md)。
1. (選擇性) 新增資產模型的標籤 (`tags`)。如需詳細資訊，請參閱[標記您的 AWS IoT SiteWise 資源](tag-resources.md)。
1. 執行下列命令，從 JSON 檔案中的定義建立元件模型。
```
aws iotsitewise create-asset-model --cli-input-json file://component-model-payload.json
```
操作會傳回回應，其中包含`assetModelId`您在資產模型或其他元件模型中將參考新增至元件模型時所參考的 。回應還包含模型 (`assetModelStatus.state`) 的狀態，起初為 `CREATING`。元件模型的狀態為 ，`CREATING`直到變更傳播為止。
**注意**
複雜模型的元件模型建立程序最多可能需要幾分鐘的時間。若要檢查元件模型的目前狀態，請指定 來使用 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) 操作`assetModelId`。在元件模型狀態為 之後`ACTIVE`，您可以在資產模型或其他元件模型中新增元件模型的參考。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。
1. （選用） 為您的元件模型建立自訂複合模型。使用自訂複合模型，您可以在模型中分組屬性，或透過參考另一個元件模型來包含子組件。如需詳細資訊，請參閱[建立自訂複合模型 （元件）](create-custom-composite-models.md)。
## 元件模型範例
本節包含元件模型定義範例，可用來建立具有 AWS CLI 和 AWS IoT SiteWise SDKs元件模型。此元件模型代表可在 CNC 機器等其他設備中使用的伺服馬達。
**Topics**
+ [伺服馬達元件模型](#example-servo-motor)
### 伺服馬達元件模型
下列元件模型代表可在 CNC 機器等設備中使用的伺服馬達。伺服馬達提供各種測量，例如溫度和電阻。這些衡量值可作為參考 伺服馬達元件模型之資產模型建立的資產屬性。
```
{
"assetModelName": "ServoMotor",
"assetModelType": "COMPONENT_MODEL",
"assetModelProperties": [
{
"dataType": "DOUBLE",
"name": "Servo Motor Temperature",
"type": {
"measurement": {}
},
"unit": "Celsius"
},
{
"dataType": "DOUBLE",
"name": "Spindle speed",
"type": {
"measurement": {}
},
"unit": "rpm"
}
]
}
```
# 定義資料屬性
*資產屬性*是每個資產中包含資產資料的結構。資產屬性可以是下列任一類型：
+ **屬性** – 資產的一般靜態屬性，例如裝置製造商或地理區域。如需詳細資訊，請參閱[定義靜態資料 （屬性）](attributes.md)。
+ **測量** – 資產的原始裝置感應器資料串流，例如時間戳記輪換速度值或時間戳記溫度值，以攝氏為單位。衡量值由資料串流別名定義。如需詳細資訊，請參閱[從設備定義資料串流 （度量）](measurements.md)。
+ **轉換** – 資產的轉換時間序列值，例如 Fahrenheit 中的時間戳記溫度值。轉換由表達式和變數定義，以使用該表達式。如需詳細資訊，請參閱[轉換資料 （轉換）](transforms.md)。
+ **指標** – 在指定時間間隔內彙總的資產資料，例如每小時平均溫度。指標由時間間隔、表達式以及與該表示式搭配使用的變數所定義。指標表達式可以輸入相關聯資產的指標屬性，讓您可以計算代表操作或操作子集的指標。如需詳細資訊，請參閱[從屬性和其他資產彙總資料 （指標）](metrics.md)。
如需詳細資訊，請參閱[在 中建立資產模型 AWS IoT SiteWise](create-asset-models.md)。
如需如何使用衡量值、轉換和指標來計算「整體設備效率」(OEE) 的範例，請參閱 [在 中計算 OEE AWS IoT SiteWise](calculate-oee.md)。
**Topics**
+ [定義靜態資料 （屬性）](attributes.md)
+ [從設備定義資料串流 （度量）](measurements.md)
+ [轉換資料 （轉換）](transforms.md)
+ [從屬性和其他資產彙總資料 （指標）](metrics.md)
+ [使用公式表達式](formula-expressions.md)
# 定義靜態資料 （屬性）
*資產屬性*代表通常為靜態的資訊，例如裝置製造商或地理位置。您從資產模型建立的每個資產，皆會包含該模型的屬性。
**Topics**
+ [定義屬性 （主控台）](#define-attributes-console)
+ [定義屬性 (AWS CLI)](#define-attributes-cli)
## 定義屬性 （主控台）
當您在 AWS IoT SiteWise 主控台中定義資產模型的屬性時，您可以指定下列參數：
+ **名稱** – 屬性的名稱。
+ **預設值** – （選用） 此屬性的預設值。從模型建立的資產具有 屬性的此值。對於從模型建立的資產，如需如何覆寫預設值的詳細資訊，請參閱 [更新屬性值](update-attribute-values.md)。
+ **資料類型** – 屬性的資料類型，其為下列其中一項：
+ **字串** – 最多 1024 個位元組的字串。
+ **整數** – 範圍為 【-2，147，483，648，2，147，483，647】 的帶正負號 32 位元整數。
+ **Double** – 範圍為 【-10^100、10^100】 和 IEEE 754 雙精度的浮點數。
+ **布林值** – `true`或 `false`。
+ **外部 ID** – （選用） 這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
如需詳細資訊，請參閱[建立資產模型 （主控台）](create-asset-models.md#create-asset-model-console)。
## 定義屬性 (AWS CLI)
當您使用 AWS IoT SiteWise API 定義資產模型的屬性時，您可以指定下列參數：
+ `name` – 屬性的名稱。
+ `defaultValue` – （選用） 此屬性的預設值。從模型建立的資產具有 屬性的此值。對於從模型建立的資產，如需如何覆寫預設值的詳細資訊，請參閱 [更新屬性值](update-attribute-values.md)。
+ `dataType` – 屬性的資料類型，其為下列其中一項：
+ `STRING` – 最多 1024 個位元組的字串。
+ `INTEGER` – 範圍為 【-2，147，483，648， 2，147，483，647】 的帶正負號 32 位元整數。
+ `DOUBLE` – 範圍為 【-10^100、10^100】 和 IEEE 754 雙精度的浮點數。
+ `BOOLEAN` – `true`或 `false`。
+ `externalId` – （選用） 這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
**Example 範例屬性定義**
下列範例示範會將資產的模型編號以預設值呈現的屬性。此物件是包含 [屬性](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_Attribute.html)的 [AssetModelProperty](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetModelProperty.html) 範例。您可以將此物件指定為 [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html) 請求承載的一部分，以建立 屬性。如需詳細資訊，請參閱[建立資產模型 (AWS CLI)](create-asset-models.md#create-asset-model-cli)。
```
{
...
"assetModelProperties": [
{
"name": "Model number",
"dataType": "STRING",
"type": {
"attribute": {
"defaultValue": "BLT123"
}
}
}
],
...
}
```
# 從設備定義資料串流 （度量）
*測量*代表裝置的原始感應器資料串流，例如時間戳記溫度值或每分鐘時間戳記輪換 (RPM) 值。
**Topics**
+ [定義測量 （主控台）](#define-measurements-console)
+ [定義測量 (AWS CLI)](#define-measurements-cli)
## 定義測量 （主控台）
當您在 AWS IoT SiteWise 主控台中定義資產模型的測量時，您可以指定下列參數：
+ **名稱** – 屬性的名稱。
+ **單位** – （選用） 屬性的科學單位，例如 mm 或 Celsius。
+ **資料類型** – 屬性的資料類型，其為下列其中一項：
+ **字串** – 最多 1024 個位元組的字串。
+ **整數** – 範圍為 【-2，147，483，648，2，147，483，647】 的帶正負號 32 位元整數。
+ **Double** – 範圍為 【-10^100、10^100】 和 IEEE 754 雙精度的浮點數。
+ **布林值** – `true`或 `false`。
+ **外部 ID** – （選用） 這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
如需詳細資訊，請參閱[建立資產模型 （主控台）](create-asset-models.md#create-asset-model-console)。
## 定義測量 (AWS CLI)
當您使用 AWS IoT SiteWise API 定義資產模型的測量時，您可以指定下列參數：
+ `name` – 屬性的名稱。
+ `dataType` – 屬性的資料類型，其為下列其中一項：
+ `STRING` – 最多 1024 個位元組的字串。
+ `INTEGER` – 範圍為 【-2，147，483，648， 2，147，483，647】 的帶正負號 32 位元整數。
+ `DOUBLE` – 範圍為 【-10^100、10^100】 和 IEEE 754 雙精度的浮點數。
+ `BOOLEAN` – `true`或 `false`。
+ `unit` – （選用） 屬性的科學單位，例如 mm 或 Celsius。
+ `externalId` – （選用） 這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
**Example 範例衡量值定義**
下列範例示範代表資產溫度感測器讀數的衡量值。此物件是包含[測量](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_Measurement.html)的 [AssetModelProperty](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetModelProperty.html) 範例。您可以將此物件指定為 [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html) 請求承載的一部分，以建立測量屬性。如需詳細資訊，請參閱[建立資產模型 (AWS CLI)](create-asset-models.md#create-asset-model-cli)。
當您定義資產模型時，[測量](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_Measurement.html)結構是空的結構，因為您稍後將每個資產設定為使用唯一的裝置資料串流。如需如何將資產的測量屬性連接至裝置感應器資料串流的詳細資訊，請參閱 [管理 的資料串流 AWS IoT SiteWise](manage-data-streams.md)。
```
{
...
"assetModelProperties": [
{
"name": "Temperature C",
"dataType": "DOUBLE",
"type": {
"measurement": {}
},
"unit": "Celsius"
}
],
...
}
```
# 轉換資料 （轉換）
*轉換*是數學表達式，可將資產屬性的資料點從一種形式映射到另一種形式。轉換表達式由資產屬性變數、常值、運算子和函數組成。轉換的資料點與輸入資料點保持one-to-one的關係。 會在每次任何輸入屬性接收到新的資料點時 AWS IoT SiteWise 計算新的轉換資料點。
**注意**
對於具有相同時間戳記的屬性更新，來自其他傳入屬性的更新可能會覆寫輸出值。
例如，如果您的資產具有名為 `Temperature_C`、以攝氏單位為單位的溫度衡量值串流，您可以使用公式 `Temperature_F = 9/5 * Temperature_C + 32` 將每個資料點轉換為華氏。每次在`Temperature_C`測量串流中 AWS IoT SiteWise 收到資料點時，都會在幾秒內計算對應的`Temperature_F`值，並以 `Temperature_F` 屬性的形式提供。
如果您的轉換包含多個變數，則稍早抵達的資料點會立即啟動運算。考慮一個零件製造商使用轉換來監控產品品質的範例。製造商會根據組件類型使用不同的標準，使用以下測量來代表程序：
+ `Part_Number` - 識別組件類型的字串。
+ `Good_Count` - 如果組件符合標準，則會增加 1 的整數。
+ `Bad_Count` - 如果組件不符合標準，則會增加 1 的整數。
製造商也會建立等於 `Quality_Monitor`的轉換 ` if(eq(Part_Number, "BLT123") and (Bad_Count / (Good_Count + Bad_Count) > 0.1), "Caution", "Normal")`。
此轉換會監控針對特定組件類型產生的不良組件百分比。如果組件編號為 BLT123，且不良組件的百分比超過 10% (0.1)，則轉換會傳回 `"Caution"`。否則，轉換會傳回 `"Normal"`。
**注意**
如果 在其他測量之前`Part_Number`收到新的資料點，`Quality_Monitor`轉換會使用新的`Part_Number`值和最新的 `Good_Count` 和 `Bad_Count`值。若要避免錯誤，請在下一次製造執行`Bad_Count`之前重設 `Good_Count`和 。
如果您只想在所有變數接收到新的資料點之後評估表達式，請使用 [指標](metrics.md)。
**Topics**
+ [定義轉換 （主控台）](#define-transforms-console)
+ [定義轉換 (AWS CLI)](#define-transform-cli)
## 定義轉換 （主控台）
當您在 AWS IoT SiteWise 主控台中定義資產模型的轉換時，您可以指定下列參數：
+ **名稱** – 屬性的名稱。
+ **單位** – （選用） 屬性的科學單位，例如 mm 或 Celsius。
+ **資料類型** – 轉換的資料類型，可以是 **Double** 或 **String**。
+ **外部 ID** – （選用） 這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
+ **公式** – 轉換表達式。轉換表達式無法使用彙總函數或暫時函數。若要開啟自動完成功能，請開始輸入或按向下箭頭鍵。如需詳細資訊，請參閱[使用公式表達式](formula-expressions.md)。
**重要**
轉換可以輸入整數、雙數、布林值或字串類型的屬性。布林值轉換為 `0`(false) 和 `1`(true)。
轉換必須輸入一或多個非屬性和任意數量屬性屬性的屬性。每次非 屬性的輸入屬性收到新的資料點時， 都會 AWS IoT SiteWise 計算新的轉換資料點。新的屬性值不會啟動轉換更新。資產屬性資料 API 操作的相同請求率適用於轉換運算結果。
公式表達式只能輸出雙值或字串值。巢狀運算式可以輸出其他資料類型，例如字串，但整體公式必須評估為數字或字串。您可以使用 [jp 函數](expression-string-functions.md#jp-definition)將字串轉換為數字。布林值必須為 1 (true) 或 0 (false)。如需詳細資訊，請參閱[未定義、無限和溢出值](expression-tutorials.md#undefined-values)。
如需詳細資訊，請參閱[建立資產模型 （主控台）](create-asset-models.md#create-asset-model-console)。
## 定義轉換 (AWS CLI)
當您使用 AWS IoT SiteWise API 定義資產模型的轉換時，您可以指定下列參數：
+ `name` – 屬性的名稱。
+ `unit` – （選用） 屬性的科學單位，例如 mm 或 Celsius。
+ `dataType` – 轉換的資料類型，必須是 `DOUBLE`或 `STRING`。
+ `externalId` – （選用） 這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
+ `expression` – 轉換表達式。轉換表達式無法使用彙總函數或暫時函數。如需詳細資訊，請參閱[使用公式表達式](formula-expressions.md)。
+ `variables` – 變數清單，定義要在表達式中使用的資產其他屬性。每個變數結構都包含可在表達式中使用的簡單名稱，以及一個 `value` 結構，用來識別要連結到該變數的屬性。`value` 結構包含以下資訊：
+ `propertyId` – 要輸入值之屬性的 ID。您可以使用屬性的名稱而非其 ID。
**重要**
轉換可以輸入整數、雙數、布林值或字串類型的屬性。布林值轉換為 `0`(false) 和 `1`(true)。
轉換必須輸入一或多個非屬性和任意數量屬性屬性的屬性。每次非 屬性的輸入屬性收到新的資料點時， 都會 AWS IoT SiteWise 計算新的轉換資料點。新的屬性值不會啟動轉換更新。資產屬性資料 API 操作的相同請求率適用於轉換運算結果。
公式表達式只能輸出雙值或字串值。巢狀運算式可以輸出其他資料類型，例如字串，但整體公式必須評估為數字或字串。您可以使用 [jp 函數](expression-string-functions.md#jp-definition)將字串轉換為數字。布林值必須為 1 (true) 或 0 (false)。如需詳細資訊，請參閱[未定義、無限和溢出值](expression-tutorials.md#undefined-values)。
**Example 轉換定義**
下列範例示範一種轉換屬性，可將資產的溫度衡量值從攝氏轉換為華氏。此物件是包含[轉換](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_Transform.html)的 [AssetModelProperty](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetModelProperty.html) 範例。您可以將此物件指定為 [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html) 請求承載的一部分，以建立轉換屬性。如需詳細資訊，請參閱[建立資產模型 (AWS CLI)](create-asset-models.md#create-asset-model-cli)。
```
{
...
"assetModelProperties": [
...
{
"name": "Temperature F",
"dataType": "DOUBLE",
"type": {
"transform": {
"expression": "9/5 * temp_c + 32",
"variables": [
{
"name": "temp_c",
"value": {
"propertyId": "Temperature C"
}
}
]
}
},
"unit": "Fahrenheit"
}
],
...
}
```
**Example 包含三個變數的轉換定義**
下列範例示範轉換屬性，如果超過 10% 的 BLT123 組件不符合標準，則會傳回警告訊息 (`"Caution"`)。否則，它會傳回資訊訊息 (`"Normal"`)。
```
{
...
"assetModelProperties": [
...
{
"name": "Quality_Monitor",
"dataType": "STRING",
"type": {
"transform": {
"expression": "if(eq(Part_Number,"BLT123") and (Bad_Count / (Good_Count + Bad_Count) > 0.1), "Caution", "Normal")",
"variables": [
{
"name": "Part_Number",
"value": {
"propertyId": "Part Number"
}
},
{
"name": "Good_Count",
"value": {
"propertyId": "Good Count"
}
},
{
"name": "Bad_Count",
"value": {
"propertyId": "Bad Count"
}
}
]
}
}
}
...
}
```
# 從屬性和其他資產彙總資料 （指標）
指標是數學表達式，使用彙總函數來處理所有輸入資料點，並在每個指定的時間間隔輸出單一資料點。例如，指標可以從溫度資料串流計算每小時平均溫度。
指標可以從關聯資產的指標輸入資料，因此您可以計算統計資料，以提供您的操作或操作子集的深入解析。例如，指標可以計算風力發電場中所有風力發電機的平均每小時溫度。如需如何定義資產之間關聯的詳細資訊，請參閱 [定義資產模型階層](define-asset-hierarchies.md)。
指標也可以從其他屬性輸入資料，而無需在每個時間間隔內彙總資料。如果您在公式中指定[屬性](attributes.md)， AWS IoT SiteWise 會在計算公式時使用該屬性[的最新](expression-temporal-functions.md#latest-definition)值。如果您在公式中指定指標， 會針對計算公式的時間間隔 AWS IoT SiteWise 使用[最後一個](expression-temporal-functions.md#last-definition)值。這表示您可以定義 等指標`OEE = Availability * Quality * Performance`，其中 `Availability`、 `Quality`和 `Performance`是相同資產模型上的所有其他指標。
AWS IoT SiteWise 也會自動運算所有資產屬性的一組基本彙總指標。若要降低運算成本，您可以使用這些彙總，而不要為基本運算定義自訂指標。如需詳細資訊，請參閱[在 中查詢資產屬性彙總 AWS IoT SiteWise](aggregates.md)。
**Topics**
+ [定義指標 （主控台）](#define-metrics-console)
+ [定義指標 (AWS CLI)](#define-metrics-cli)
## 定義指標 （主控台）
當您在 AWS IoT SiteWise 主控台中定義資產模型的指標時，您可以指定下列參數：
+ **名稱** – 屬性的名稱。
+ **資料類型** – 轉換的資料類型，可以是 **Double** 或 **String**。
+ **外部 ID** – （選用） 這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
+ **公式** – 指標表達式。指標表達[式可以使用彙總函數](expression-aggregation-functions.md)，從屬性輸入階層中所有相關聯資產的資料。開始輸入或按向下鍵開啟自動完成功能。如需詳細資訊，請參閱[使用公式表達式](formula-expressions.md)。
**重要**
指標只能是整數、雙數、布林值或字串類型的屬性。布林值轉換為 `0`(false) 和 `1`(true)。
如果您在指標表達式中定義任何指標輸入變數，則這些輸入必須和輸出指標有相同的時間間隔。
公式表達式只能輸出雙值或字串值。巢狀運算式可以輸出其他資料類型，例如字串，但整體公式必須評估為數字或字串。您可以使用 [jp 函數](expression-string-functions.md#jp-definition)將字串轉換為數字。布林值必須為 1 (true) 或 0 (false)。如需詳細資訊，請參閱[未定義、無限和溢出值](expression-tutorials.md#undefined-values)。
+ **時間間隔** – 指標時間間隔。 AWS IoT SiteWise 支援下列輪轉時段時間間隔，其中每個間隔會在前一個時間間隔結束時開始：
+ **1 分鐘** – 1 分鐘，在每分鐘結束時 （上午 12：00：00、上午 12：01：00、上午 12：02：00 等） 計算。
+ **5 分鐘** – 5 分鐘，從小時開始每 5 分鐘計算一次 （上午 12：00：00、上午 12：05：00、上午 12：10：00 等）。
+ **15 分鐘** – 15 分鐘，從小時開始每 15 分鐘的結尾開始計算 （上午 12：00：00、上午 12：15：00、上午 12：30：00 等）。
+ **1 小時** – 1 小時 (60 分鐘），每小時結束時以 UTC 計算 （上午 12：00：00、上午 01：00：00、上午 02：00：00 等）。
+ **1 天** – 1 天 (24 小時），在每天結束時以 UTC 計算 （星期一上午 12：00：00、星期二上午 12：00：00 等）。
+ **1 週** – 1 週 (7 天），在 UTC 的每個星期日結束時計算 （星期一上午 12：00：00)。
+ **自訂間隔** – 您可以輸入一分鐘到一週之間的任何時間間隔。
+ **位移日期** – （選用） 要彙總資料的參考日期。
+ **位移時間** – （選用） 要彙總資料的參考時間。偏移時間必須介於 00：00：00 和 23：59：59 之間。
+ **位移時區** – （選用） 位移的時區。如果未指定，則預設位移時區為國際標準時間 (UTC)。請參閱下列支援的時區。
### 支援的時區
+ (UTC\$100：00) 國際標準時間
+ (UTC\$101：00) 歐洲中部時間
+ (UTC\$102：00) 東歐
+ (UTC03\$1：00) 東非時間
+ (UTC\$104：00) 接近東部時間
+ (UTC\$105：00) 巴基斯坦拉合爾時間
+ (UTC\$105：30) 印度標準時間
+ (UTC\$106：00) 孟加拉標準時間
+ (UTC\$107：00) 越南標準時間
+ (UTC\$108：00) 中國台北時間
+ (UTC\$109：00) 日本標準時間
+ (UTC\$109：30) 澳洲中部時間
+ (UTC\$110：00) 澳洲東部時間
+ (UTC\$111：00) 索羅門標準時間
+ (UTC\$112：00) 紐西蘭標準時間
+ (UTC-11：00) 中途群島時間
+ (UTC-10：00) 夏威夷標準時間
+ (UTC-09：00) 阿拉斯加標準時間
+ (UTC-08：00) 太平洋標準時間
+ (UTC-07：00) 鳳凰城標準時間
+ (UTC-06：00) 中部標準時間
+ (UTC-05：00) 東部標準時間
+ (UTC-04：00) 波多黎各和美屬維京群島時間
+ (UTC-03：00) 阿根廷標準時間
+ (UTC-02：00) 南喬治亞時間
+ (UTC-01：00) 中非時間
**Example 具有位移的自訂時間間隔 （主控台）**
下列範例說明如何在 2021 年 2 月 20 日下午 6：30：30 (PST) 以偏移量定義 12 小時的時間間隔。
**定義具有位移的自訂間隔**
1. 針對**時間間隔**，選擇**自訂間隔**。
1. 針對**時間間隔**，執行下列其中一項操作：
+ 輸入 **12**，然後選擇**小時**。
+ 輸入 **720**，然後選擇**分鐘**。
+ 輸入 **43200**，然後選擇**秒**。
**重要**
無論單位為何，**時間間隔**都必須是整數。
1. 針對**位移日期**，選擇 **2021/02/20**。
1. 針對**位移時間**，輸入 **18:30:30**。
1. 針對**位移時區**，選擇 **(UTC-08：00) 太平洋標準時間**。
如果您在 2021 年 7 月 1 日下午 06：30：30 (PST) 之前或當天建立指標，您會在 2021 年 7 月 1 日下午 06：30：30 (PST) 取得第一個彙總結果。第二個彙總結果是 2021 年 7 月 2 日上午 06：30：30 (PST)，以此類推。
## 定義指標 (AWS CLI)
當您使用 AWS IoT SiteWise API 定義資產模型的指標時，您可以指定下列參數：
+ `name` – 屬性的名稱。
+ `dataType` – 指標的資料類型，可以是 `DOUBLE`或 `STRING`。
+ `externalId` – （選用） 這是使用者定義的 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
+ `expression` – 指標表達式。指標表達[式可以使用彙總函數](expression-aggregation-functions.md)，從屬性輸入階層中所有相關聯資產的資料。如需詳細資訊，請參閱[使用公式表達式](formula-expressions.md)。
+ `window` – 指標輪轉時段的時間間隔和位移，其中每個間隔會在前一個間隔結束時開始：
+ `interval` – 輪轉時段的時間間隔。時間間隔必須介於一分鐘和一週之間。
+ `offsets` – 輪轉時段的位移。
如需詳細資訊，請參閱 *AWS IoT SiteWise API 參考*中的 [TumblingWindow](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_TumblingWindow.html)。
**Example 具有位移的自訂時間間隔 (AWS CLI)**
下列範例說明如何在 2021 年 2 月 20 日下午 6：30：30 (PST) 定義偏移量的 12 小時時間間隔。
```
{
"window": {
"tumbling": {
"interval": "12h",
"offset": " 2021-07-23T18:30:30-08"
}
}
}
```
如果您在 2021 年 7 月 1 日下午 06：30：30 (PST) 之前或當天建立指標，您會在 2021 年 7 月 1 日下午 06：30：30 (PST) 取得第一個彙總結果。第二個彙總結果是 2021 年 7 月 2 日上午 06：30：30 (PST)，以此類推。
+ `variables` – 變數清單，定義要在表達式中使用的資產或子資產的其他屬性。每個變數結構都包含可在表達式中使用的簡單名稱，以及一個 `value` 結構，用來識別要連結到該變數的屬性。`value` 結構包含以下資訊：
+ `propertyId` – 要從中提取值的屬性 ID。如果屬性已在目前的模型中定義 (而非在階層中的模型內定義)，您可以使用屬性的名稱而非其 ID。
+ `hierarchyId` – （選用） 從中查詢屬性子資產的階層 ID。您可以使用階層定義的名稱，而非其 ID。如果您省略此值， 會在目前模型中 AWS IoT SiteWise 尋找 屬性。
**重要**
指標只能是整數、雙數、布林值或字串類型的屬性。布林值轉換為 `0`(false) 和 `1`(true)。
如果您在指標表達式中定義任何指標輸入變數，則這些輸入必須和輸出指標有相同的時間間隔。
公式表達式只能輸出雙值或字串值。巢狀運算式可以輸出其他資料類型，例如字串，但整體公式必須評估為數字或字串。您可以使用 [jp 函數](expression-string-functions.md#jp-definition)將字串轉換為數字。布林值必須為 1 (true) 或 0 (false)。如需詳細資訊，請參閱[未定義、無限和溢出值](expression-tutorials.md#undefined-values)。
+ `unit` – （選用） 屬性的科學單位，例如 mm 或 Celsius。
**Example 指標定義範例**
下列範例示範彙總資產溫度衡量值的指標屬性，以計算每小時華氏溫度上限。此物件是包含[指標](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_Metric.html)的 [AssetModelProperty](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetModelProperty.html) 範例。您可以將此物件指定為 [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html) 請求承載的一部分，以建立指標屬性。如需詳細資訊，請參閱[建立資產模型 (AWS CLI)](create-asset-models.md#create-asset-model-cli)。
```
{
...
"assetModelProperties": [
...
{
"name": "Max temperature",
"dataType": "DOUBLE",
"type": {
"metric": {
"expression": "max(temp_f)",
"variables": [
{
"name": "temp_f",
"value": {
"propertyId": "Temperature F"
}
}
],
"window": {
"tumbling": {
"interval": "1h"
}
}
}
},
"unit": "Fahrenheit"
}
],
...
}
```
**Example 從相關聯資產輸入資料的範例指標定義**
下列範例示範的指標屬性會彙總多個風力發電機的平均功率資料，以計算風力發電廠的總平均功率。此物件是包含[指標](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_Metric.html)的 [AssetModelProperty](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetModelProperty.html) 範例。您可以將此物件指定為 [CreateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModel.html) 請求承載的一部分，以建立指標屬性。
```
{
...
"assetModelProperties": [
...
{
"name": "Total Average Power",
"dataType": "DOUBLE",
"type": {
"metric": {
"expression": "avg(power)",
"variables": [
{
"name": "power",
"value": {
"propertyId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
"hierarchyId": "Turbine Asset Model"
}
}
],
"window": {
"tumbling": {
"interval": "5m"
}
}
}
},
"unit": "kWh"
}
],
...
}
```
# 使用公式表達式
使用公式表達式，您可以定義數學函數來轉換和彙整您的原始產業資料，以取得您操作的詳情。公式表達式結合常值、運算子、函數和變數來處理資料。如需如何定義使用公式表達式之資產屬性的詳細資訊，請參閱 [轉換資料 （轉換）](transforms.md)和 [從屬性和其他資產彙總資料 （指標）](metrics.md)。轉換和指標是公式屬性。
**Topics**
+ [在公式表達式中使用變數](expression-variables.md)
+ [在公式表達式中使用常值](expression-literals.md)
+ [在公式表達式中使用運算子](expression-operators.md)
+ [在公式表達式中使用常數](expression-constants.md)
+ [在公式表達式中使用函數](expression-functions.md)
+ [公式表達式教學課程](expression-tutorials.md)
# 在公式表達式中使用變數
變數代表公式表達式中的 AWS IoT SiteWise 資產屬性。使用變數來輸入表達式中其他資產屬性的值，以便處理來自常數屬性 ([屬性](attributes.md))、原始資料串流 ([度量](measurements.md)) 和其他公式屬性的資料。
變數可以代表來自相同資產模型或相關聯子資產模型的資產屬性。只有指標公式可以從子資產模型輸入變數。
您可以透過主控台和 API 中的不同名稱來識別變數。
+ **AWS IoT SiteWise 主控台** – 在表達式中使用資產屬性名稱做為變數。
+ **AWS IoT SiteWise API (AWS CLI， AWS SDKs)** – 使用 [ExpressionVariable](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ExpressionVariable.html) 結構定義變數，這需要變數名稱和資產屬性的參考。變數名稱可以包含小寫字母、數字和底線。然後，使用變數名稱來參考表達式中的資產屬性。
變數名稱區分大小寫。
如需詳細資訊，請參閱[定義轉換](transforms.md)和[定義指標](metrics.md)。
## 使用變數來參考屬性
變數*的值*會定義其參考的屬性。 AWS IoT SiteWise 提供不同的方法來執行此操作。
+ **依屬性 ID：**您可以指定屬性的唯一 ID (UUID) 來識別它。
+ **依名稱：**如果 屬性位於相同的資產模型上，您可以在屬性 ID 欄位中指定其名稱。
+ **依路徑：**變數值可以依其*路徑參考屬性。*如需詳細資訊，請參閱[使用路徑來參考自訂複合模型屬性](custom-composite-models.md#property-paths)。
**注意**
AWS IoT SiteWise 主控台不支援變數。 AWS IoT SiteWise API 會使用它們，包括 AWS Command Line Interface AWS CLI) 和 AWS SDKs。
您在 的回應中收到的變數 AWS IoT SiteWise 包含該值的完整資訊，包括 ID 和路徑。
不過，當您將變數傳遞至 AWS IoT SiteWise （例如，在「建立」或「更新」呼叫中） 時，您只需要指定其中一個。例如，如果您指定路徑，則不需要提供 ID。
# 在公式表達式中使用常值
AWS IoT SiteWise 支援在表達式和公式中使用常值。文字是代表特定資料類型的固定值。在 中 AWS IoT SiteWise，您可以在公式表達式中定義數字和字串常值。文字可用於各種內容，包括資料轉換、警示條件和視覺化計算。
+ **數字**
使用數字和科學記號來定義整數和雙數。您可以使用 [E 表示法](https://en.wikipedia.org/wiki/Scientific_notation#E_notation)來表達具有科學表示法的數字。
範例：`1`、`2.0`、`.9`、`-23.1`、`7.89e3`、 `3.4E-5`
+ **字串**
使用 `'`（引號） 和 `"`（雙引號） 字元來定義字串。開始和結束的引號類型必須相符。若要逸出與您用來宣告字串的引號相符的引號，請包含該引號字元兩次。這是 AWS IoT SiteWise 字串中唯一的逸出字元。
範例：`'active'`、`"inactive"`、`'{"temp": 52}'`、`"{""temp"": ""high""}"`
# 在公式表達式中使用運算子
您可以在公式表達式中使用下列常見運算子。
| 運算子 | Description |
| --- | --- |
| `+` | 如果兩個運算元都是數字，則此運算子會新增左側和右側運算元。 如果其中一個運算元是字串，此運算子會將左側和右側運算元串連為字串。例如，表達式會`1 + 2 + " is three"`評估為 `"3 is three"`。串連字串最多可有 1024 個字元。如果字串超過 1024 個字元，則 AWS IoT SiteWise 不會輸出該運算的資料點。 |
| `-` | 從左運算元中減去右運算元。 您只能將此運算子與數值運算元搭配使用。 |
| `/` | 將左運算元除以右運算元。 您只能將此運算子與數值運算元搭配使用。 |
| `*` | 將左側和右側的運算元相乘。 您只能將此運算子與數值運算元搭配使用。 |
| `^` | 將左側的運算元乘上右側運算元的次方數 (指數)。 您只能將此運算子與數值運算元搭配使用。 |
| `%` | 傳回左運算元除以右運算元的餘數。結果與左側運算元具有相同的符號。此行為與模數操作不同。 您只能將此運算子與數值運算元搭配使用。 |
| `x < y` | `1` 如果 小於 `x`，則傳回 `y`，否則傳回 `0`。 |
| `x > y` | `1` 如果 `x` 大於 ，則傳回 `y`，否則傳回 `0`。 |
| `x <= y` | `1` 如果 小於或等於 `x`，則傳回 `y`，否則傳回 `0`。 |
| `x >= y` | `1` 如果 `x`大於或等於 ，則傳回 `y`，否則傳回 `0`。 |
| `x == y` | `1` 如果 `x` 等於 ，則傳回 `y`，否則傳回 `0`。 |
| `x != y` | `1` 如果 `x` 不等於 ，則傳回 `y`，否則傳回 `0`。 |
| `!x` | `1` 如果評估`x`為 `0`(false)，則傳回 ，否則傳回 `0`。 `x` 評估為 false，如果： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-operators.html) |
| `x and y` | `0` 如果評估`x`為 `0`(false)，則傳回 。否則， 會傳回 的評估結果`y`。 `x` 或 `y` 評估為 false，如果： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-operators.html) |
| `x or y` | `1` 如果評估`x`為 `1`(true)，則傳回 。否則， 會傳回 的評估結果`y`。 `x` 或 `y` 評估為 false，如果： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-operators.html) |
| `not x` | `1` 如果評估`x`為 `0`(false)，則傳回 ，否則傳回 `0`。 `x` 評估為 false，如果： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-operators.html) |
| `[]` `s[index]` | 傳回字串 索引`index`的字元`s`。這相當於 Python 中的索引語法。
**Example 範例**
+ `"Hello!"[1]` 傳回：`e`
+ `"Hello!"[-2]` 傳回：`o` |
| `[]` `s[start:end:step]` | 傳回字串 的配量`s`。這相當於 Python 中的配量語法。此運算子具有下列引數： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-operators.html) 您可以省略引`step`數以使用其預設值。例如，`s[1:4:1]` 等同於 `s[1:4]`。 引數必須是整數或[無](expression-constants.md#none-definition)常數。如果您指定 `none`， AWS IoT SiteWise 會使用該引數的預設值。
**Example 範例**
+ `"Hello!"[1:4]` 傳回：`"ell"`
+ `"Hello!"[:2]` 傳回：`"He"`
+ `"Hello!"[3:]` 傳回：`"lo!"`
+ `"Hello!"[:-4]` 傳回：`"He"`
+ `"Hello!"[::2]` 傳回：`"Hlo"`
+ `"Hello!"[::-1]` 傳回：`"!olleH"` |
# 在公式表達式中使用常數
在 中 AWS IoT SiteWise，您可以在表達式和公式中使用常數來表示固定值或預先定義的參數。常數可用於各種內容，例如資料轉換、警示條件或視覺化計算。透過使用常數，您可以簡化表達式，使它們更易於讀取和維護。
您可以在您的表達式中使用下列常見的數學常數。所有常數不區分大小寫。
**注意**
如果您使用與常數相同的名稱定義變數，則變數會覆寫常數。
| 常數 | Description |
| --- | --- |
| `pi` | 數字 pi (`π`)： `3.141592653589793` |
| `e` | 數字 e： `2.718281828459045` |
| `true` | 相當於數字 1。在 中 AWS IoT SiteWise，布林值會轉換為其數量對等項目。 |
| `false` | 相當於數字 0。在 中 AWS IoT SiteWise，布林值會轉換為其數量對等項目。 |
| `none` | 等同於無值。您可以使用此常數來輸出條件[表達式](expression-conditional-functions.md)的結果。 |
# 在公式表達式中使用函數
您可以使用下列函數來操作公式表達式中的資料。
轉換和指標支援不同的 函數。下表指出哪些類型的函數與每種類型的公式屬性相容。
**注意**
您可以在公式表達式中包含最多 10 個函數。
| 函數類型 | 轉換 | 指標 |
| --- | --- | --- |
| [在公式表達式中使用常見函數](expression-common-functions.md) | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 |
| [在公式表達式中使用比較函數](expression-comparison-functions.md) | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 |
| [在公式表達式中使用條件式函數](expression-conditional-functions.md) | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 |
| [在公式表達式中使用字串函數](expression-string-functions.md) | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 |
| [在公式表達式中使用彙總函數](expression-aggregation-functions.md) | ![\[A red circle with the letter x for no.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-no.png) 否 | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 |
| [在公式表達式中使用暫時函數](expression-temporal-functions.md) | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 |
| [在公式表達式中使用日期和時間函數](expression-date-and-time-functions.md) | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 | ![\[A green circle with a checkmark for yes.\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/icon-yes.png) 是 |
## 函數語法
您可以使用下列語法來建立函數：
一般語法
使用一般語法時，函數名稱後面接著具有零或多個引數的括號。
`function_name(argument1, argument2, argument3, ...)`。 例如，具有一般語法的函數可能看起來像 `log(x)`和 `contains(s, substring)`。
統一函數呼叫語法 (UFCS)
UFCS 可讓您在物件導向程式設計中使用 方法呼叫的語法來呼叫函數。使用 UFCS，第一個引數後面接著點 (`.`)，然後是函數名稱和括號內剩餘的引數 （如果有的話）。
`argument1.function_name(argument2, argument3, ...)`。 例如，搭配 UFCS 的函數可能看起來像 `x.log()`和 `s.contains(substring)`。
您也可以使用 UFCS 鏈結後續函數。 AWS IoT SiteWise 會使用目前函數的評估結果做為下一個函數的第一個引數。
例如，您可以使用 `message.jp('$.status').lower().contains('fail')`而非 `contains(lower(jp(message, '$.status')),'fail')`。
如需詳細資訊，請造訪 [D 程式設計語言](https://tour.dlang.org/tour/en/gems/uniform-function-call-syntax-ufcs)網站。
**注意**
您可以對所有 AWS IoT SiteWise 函數使用 UFCS。
AWS IoT SiteWise 函數不區分大小寫。例如，您可以`Lower(s)`交替使用 `lower(s)`和 。
# 在公式表達式中使用常見函數
在[轉換](transforms.md)和[指標](metrics.md)中，您可以使用下列函數來計算轉換和指標中的常見數學函數。
| 函式 | Description |
| --- | --- |
| `abs(x)` | 傳回 `x` 的絕對值。 |
| `acos(x)` | 傳回 `x` 的反餘弦。 |
| `asin(x)` | 傳回 `x` 的反正弦。 |
| `atan(x)` | 傳回 `x` 的反正切。 |
| `cbrt(x)` | 傳回 `x` 的立方根。 |
| `ceil(x)` | 傳回大於 `x` 的最接近整數。 |
| `cos(x)` | 傳回 `x` 的餘弦。 |
| `cosh(x)` | 傳回 `x` 的雙曲餘弦。 |
| `cot(x)` | 傳回 的餘切`x`。 |
| `exp(x)` | 傳回乘以 `x` 次方的 `e`。 |
| `expm1(x)` | 傳回 `exp(x) - 1`。使用此函數可更準確地`exp(x) - 1`計算 的小值`x`。 |
| `floor(x)` | 傳回小於 `x` 的最接近整數。 |
| `log(x)` | 傳回 `x` 的 `loge` (基底 `e`)。 |
| `log10(x)` | 傳回 `x` 的 `log10` (基底 `10`)。 |
| `log1p(x)` | 傳回 `log(1 + x)`。使用此函數可更準確地`log(1 + x)`計算 的小值`x`。 |
| `log2(x)` | 傳回 `x` 的 `log2` (基底 `2`)。 |
| `pow(x, y)` | 傳回乘以 `y` 次方的 `x`。這相當於 `x ^ y`。 |
| `signum(x)` | 傳回 `x` 的正負號 (輸入負值為 `-1`，輸入零為 `0`，輸入正值則為 `+1`)。 |
| `sin(x)` | 傳回 `x` 的正弦。 |
| `sinh(x)` | 傳回 `x` 的雙曲正弦。 |
| `sqrt(x)` | 傳回 `x` 的平方根。 |
| `tan(x)` | 傳回 `x` 的正切。 |
| `tanh(x)` | 傳回 `x` 的雙曲正切。 |
# 在公式表達式中使用比較函數
在[轉換](transforms.md)和[指標](metrics.md)中，您可以使用下列比較函數來比較兩個值和輸出 `1`(true) 或 `0`(false. AWS IoT SiteWise compares strings by [lexicographic order](https://en.wikipedia.org/wiki/Lexicographic_order)。
| 函式 | Description |
| --- | --- |
| `gt(x, y)` | 如果 `x` 大於 `y`，則傳回 `1`，否則傳回 `0` (`x > y`)。 如果 `x`和 `y` 是不相容的類型，例如數字和字串，則此函數不會傳回值。 |
| `gte(x, y)` | 如果 `x` 大於或等於 `y`，則傳回 `1`，否則傳回 `0` (`x ≥ y`)。 AWS IoT SiteWise 如果引數在 的相對公差內，則 會將引數視為相等`1E-9`。這的行為類似於 Python 中的 [isclose](https://docs.python.org/3/library/math.html#math.isclose) 函數。 如果 `x`和 `y` 是不相容的類型，例如數字和字串，則此函數不會傳回值。 |
| `eq(x, y)` | 如果 `x` 等於 `y`，則傳回 `1`，否則傳回 `0` (`x == y`)。 AWS IoT SiteWise 如果引數在 的相對公差內，則 會將引數視為相等`1E-9`。這的行為類似於 Python 中的 [isclose](https://docs.python.org/3/library/math.html#math.isclose) 函數。 如果 `x`和 `y` 是不相容的類型，例如數字和字串，則此函數不會傳回值。 |
| `lt(x, y)` | 如果 `x` 小於 `y`，則傳回 `1`，否則傳回 `0` (`x < y`)。 如果 `x`和 `y` 是不相容的類型，例如數字和字串，則此函數不會傳回值。 |
| `lte(x, y)` | 如果 `x` 小於或等於 `y`，則傳回 `1`，否則傳回 `0` (`x ≤ y`)。 AWS IoT SiteWise 如果引數在 的相對公差內，則 會將引數視為相等`1E-9`。這的行為類似於 Python 中的 [isclose](https://docs.python.org/3/library/math.html#math.isclose) 函數。 如果 `x`和 `y` 是不相容的類型，例如數字和字串，則此函數不會傳回值。 |
| `isnan(x)` | `1` 如果 `x` 等於 ，則傳回 `NaN`，否則傳回 `0`。 如果 `x` 是字串，則此函數不會傳回值。 |
# 在公式表達式中使用條件式函數
在[轉換](transforms.md)和[指標](metrics.md)中，您可以使用下列函數來檢查條件並傳回不同的結果，無論條件評估為 true 還是 false。
| 函式 | Description |
| --- | --- |
| `if(condition, result_if_true, result_if_false)` | `result_if_true` 如果條件評估為 true 或`result_if_false`條件評估為 ，則評估 `condition`並傳回 `false`。 `condition` 必須是數字。此函數會將 `0`和空字串視為 `false`，並將其他所有項目 （包括 `NaN`) 視為 `true`。布林值轉換為 `0`(false) 和 `1`(true)。 您可以從此函數傳回[無常](expression-constants.md#none-definition)數，以捨棄特定條件的輸出。這表示您可以篩選出不符合條件的資料點。如需詳細資訊，請參閱[篩選資料點](expression-tutorials.md#filter-data)。
**Example 範例**
+ `if(0, x, y)` 傳回變數 `y`。
+ `if(5, x, y)` 傳回變數 `x`。
+ `if(gt(temp, 300), x, y)` `x` 如果變數`temp`大於 ，則 會傳回變數`300`。
+ `if(gt(temp, 300), temp, none)` `temp` 如果變數大於或等於 ，則傳回變數`300`；如果 小於 `temp`，則傳回 `none`（無值）`300`。 建議您將 UFCS 用於巢狀條件函數，其中一或多個引數是條件函數。您可以使用 `if(condition, result_if_true)` 來評估條件`elif(condition, result_if_true, result_if_false)`，以及評估其他條件。 例如，您可以使用 `if(condition1, result1_if_true).elif(condition2, result2_if_true, result2_if_false)`而非 `if(condition1, result1_if_true, if(condition2, result2_if_true, result2_if_false))`。 您也可以鏈結其他中繼條件函數。例如，您可以使用 `if(condition1, result1_if_true).elif(condition2, result2_if_true).elif(condition3, result3_if_true, result3_if_false)`，而不是將多個`if`陳述式巢狀化，例如 `if(condition1, result1_if_true, if(condition2, result2_if_true, if(condition3, result3_if_true result3_if_false)))`。 您必須`elif(condition, result_if_true, result_if_false)`搭配 UFCS 使用 。 |
# 在公式表達式中使用字串函數
在[轉換](transforms.md)和[指標](metrics.md)中，您可以使用下列函數在字串上操作。如需詳細資訊，請參閱[在公式中使用字串](expression-tutorials.md#use-strings-in-formulas)。
**重要**
公式表達式只能輸出雙值或字串值。巢狀運算式可以輸出其他資料類型，例如字串，但整體公式必須評估為數字或字串。您可以使用 [jp 函數](#jp-definition)將字串轉換為數字。布林值必須為 1 (true) 或 0 (false)。如需詳細資訊，請參閱[未定義、無限和溢出值](expression-tutorials.md#undefined-values)。
| 函數 | Description |
| --- | --- |
| `len(s)` | 傳回字串 的長度`s`。 |
| `find(s, substring)` | 傳回字串 `substring`中字串的索引`s`。 |
| `contains(s, substring)` | `1` 如果字串`s`包含字串 ，則傳回 `substring`，否則傳回 `0`。 |
| `upper(s)` | 以`s`大寫形式傳回字串。 |
| `lower(s)` | 以`s`小寫形式傳回字串。 |
| `jp(s, json_path)` | `s` 使用 [JsonPath](https://github.com/json-path/JsonPath) 運算式評估字串`json_path`並傳回結果。 使用此函數執行下列動作： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-string-functions.html) 若要從 JSON 結構擷取字串值並將其傳回為數字，您必須使用多個巢狀`jp`函數。外部`jp`函數會從 JSON 結構擷取字串，而內部`jp`函數會將字串轉換為數字。 字串`json_path`必須包含字串常值。這表示 `json_path` 不能是評估為字串的表達式。
**Example 範例**
+ `jp('{"status":"active","value":15}', '$.value')` 傳回：`15`
+ `jp('{"measurement":{"reading":25,"confidence":0.95}}', '$.measurement.reading')` 傳回：`25`
+ `jp('[2,8,23]', '$[2]')` 傳回：`23`
+ `jp('{"values":[3,6,7]}', '$.values[1]')` 傳回：`6`
+ `jp('111', '$')` 傳回：`111`
+ `jp(jp('{"measurement":{"reading":25,"confidence":"0.95"}}', '$.measurement.confidence'), '$')` 傳回：`0.95` |
| `join(s0, s1, s2, s3, ...)` | 傳回具有分隔符號的串連字串。此函數使用第一個輸入字串做為分隔符號，並將剩餘的輸入字串聯結在一起。這的行為類似於 Java 中的 [join(CharSequence delimiter、CharSequence... 元素）](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#join-java.lang.CharSequence-java.lang.CharSequence...-) 函數。
**Example 範例**
+ `join("-", "aa", "bb", "cc")` 傳回 `aa-bb-cc` |
| `format(expression: "format")` 或 `format("format", expression)` | 傳回指定格式的字串。此函數會評估`expression`為 值，然後以指定的格式傳回該值。這的行為類似於 Java 中的 [format（字串格式、物件... args) ](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#format-java.lang.String-java.lang.Object...-)函數。如需支援格式的詳細資訊，請參閱 *Java 平台 Standard Edition 7 API 規格*中的[類別格式化器](https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html)下的轉換。
**Example 範例**
+ `format(100+1: "d")` 傳回字串 `101`。
+ `format("The result is %d", 100+1)` 傳回字串 `The result is 101`。 |
| `f'expression'` | 傳回串連字串。使用此格式化函數，您可以使用簡單的表達式來串連和格式化字串。這些函數可能包含巢狀運算式。您可以使用 `{}`（大括號） 插入運算式。這的行為類似於 Python 中的[格式化字串常值](https://docs.python.org/3/reference/lexical_analysis.html#f-strings)。
**Example 範例**
+ `f'abc{1+2: "f"}d'` 傳回：`abc3.000000d`若要評估此範例表達式，請執行下列動作：
1. `format(1+2: "f")` 傳回浮點數 `3.000000`。
1. `join('', "abc", 1+2, 'd')` 傳回字串 `abc3.000000d`。
您也可以使用下列方式撰寫表達式：`join('', "abc", format(1+2: "f"), 'd')`。 |
# 在公式表達式中使用彙總函數
僅在[指標](metrics.md)中，您可以使用下列函數來彙總每個時間間隔的輸入值，並計算單一輸出值。彙總函數可以彙總來自關聯資產的資料。
彙總函數引數可以是[變數](expression-variables.md)、[數字常值](expression-literals.md#number-literal-definition)、[時間函數](expression-temporal-functions.md)、巢狀運算式或彙總函數。公式`max(latest(x), latest(y), latest(z))`使用彙總函數做為引數，並傳回 `x`、 `y`和 `z` 屬性的最大目前值。
您可以在彙總函數中使用巢狀運算式。當您使用巢狀運算式時，適用下列規則：
+ 每個引數只能有一個變數。
**Example**
例如，支援 `sum(x/2 )/avg(y^2 )` `avg(x*(x-1))`和 。
例如，`min(x/y)`不支援 。
+ 每個引數都可以有多層巢狀運算式。
**Example**
例如，支援 `sum(avg(x^2 )/2)` 。
+ 不同的引數可以有不同的變數。
**Example**
例如，支援 `sum(x/2, y*2)` 。
**注意**
如果您的表達式包含測量， AWS IoT SiteWise 會使用目前時間間隔內的最後一個值來計算彙總。
如果您的表達式包含屬性， AWS IoT SiteWise 會使用屬性的最新值來計算彙總。
| 函式 | Description |
| --- | --- |
| `avg(x0, ..., xn)` | 傳回目前時間間隔指定變數值的平均數。 只有在指定的變數在目前時間間隔內至少有一個資料點時，此函數才會輸出資料點。 |
| `sum(x0, ..., xn)` | 傳回目前時間間隔指定變數值的總和。 只有在指定的變數在目前時間間隔內至少有一個資料點時，此函數才會輸出資料點。 |
| `min(x0, ..., xn)` | 傳回目前時間間隔指定變數值的最小值。 只有在指定的變數在目前時間間隔內至少有一個資料點時，此函數才會輸出資料點。 |
| `max(x0, ..., xn)` | 傳回目前時間間隔指定變數值的最大值。 只有在指定的變數在目前時間間隔內至少有一個資料點時，此函數才會輸出資料點。 |
| `count(x0, ..., xn)` | 傳回目前時間間隔內給定變數的資料點總數。若要取得有關如何計算符合條件之資料點數目的更多資訊，請參閱 [計數符合條件的資料點](expression-tutorials.md#count-filtered-data)。 此函數會計算每個時間間隔的資料點。 |
| `stdev(x0, ..., xn)` | 傳回指定變數值在目前時間間隔內的標準差。 只有在指定的變數在目前時間間隔內至少有一個資料點時，此函數才會輸出資料點。 |
# 在公式表達式中使用暫時函數
使用暫時函數，根據資料點的時間戳記傳回值。
## 在指標中使用暫時函數
僅在 [指標](metrics.md)中，您可以使用下列函數，根據資料點的時間戳記傳回值。
暫時函數引數必須是來自本機資產模型或巢狀運算式的屬性。這表示您無法在暫時函數中使用子資產模型的屬性。
您可以在時間函數中使用巢狀運算式。當您使用巢狀運算式時，適用下列規則：
+ 每個引數只能有一個變數。
例如，支援 `latest( t*9/5 + 32 )` 。
+ 引數不能是彙總函數。
例如，`first( sum(x) )`不支援 。
| 函式 | Description |
| --- | --- |
| `first(x)` | 傳回目前時間間隔指定變數值中時間戳記最早的值。 |
| `last(x)` | 傳回目前時間間隔指定變數值中時間戳記最晚的值。 |
| `earliest(x)` | 傳回指定變數在目前時間間隔開始前的最後一個值。 如果輸入屬性在其歷史記錄中至少有一個資料點，此函數會計算每個時間間隔的資料點。如需詳細資訊，請參閱 [time-range-defintion](#time-range-def)。 |
| `latest(x)` | 傳回指定變數的最後一個值，並在目前時間間隔結束前加上最新的時間戳記。 如果輸入屬性在其歷史記錄中至少有一個資料點，此函數會計算每個時間間隔的資料點。如需詳細資訊，請參閱 [time-range-defintion](#time-range-def)。 |
| `statetime(x)` | 傳回目前時間間隔中指定變數為正 (positive) 的秒數。您可以使用[比較函數](expression-comparison-functions.md)來建立轉換屬性，以供`statetime`函數使用。 例如，如果您有一個為 `0` 或 `1` 的 `Idle` 屬性，您可以使用此表達式來計算每個時間間隔的閒置時間：`IdleTime = statetime(Idle)`。如需詳細資訊，請參閱 [example statetime scenario](#statetime-example) (狀態時間案例範例)。 此函數不支援使用指標屬性做為輸入變數。 如果輸入屬性在其歷史記錄中至少有一個資料點，此函數會計算每個時間間隔的資料點。 |
| `TimeWeightedAvg(x, [interpolation])` | 傳回以點之間的時間間隔加權的輸入資料平均值。如需運算和間隔詳細資訊，請參閱[時間加權函數參數](#timeweighted-parameter)。選用引數`interpolaton`必須是字串常數：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-temporal-functions.html) |
| `TimeWeightedStDev(x, [algo])` | 傳回以點之間的時間間隔加權的輸入資料標準差。 如需運算和間隔詳細資訊，請參閱[時間加權函數參數](#timeweighted-parameter)。 計算會針對資料點之間的間隔使用最後觀察的轉移運算演算法。在此方法中，資料點會計算為最後一個觀察值，直到下一個輸入資料點時間戳記為止。權重的計算方式為資料點或視窗邊界之間的時間間隔，以秒為單位。 選用引數`algo`必須是字串常數： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-temporal-functions.html) 下列公式用於運算，其中： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-temporal-functions.html) 母群體標準差的方程式： ![\[母群體標準差的方程式。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/timeweightedstdev1.png) 頻率標準差的方程式： ![\[頻率標準差的方程式。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/timeweighted-frequency-stdev.png) |
下圖顯示 如何計算 AWS IoT SiteWise 相對於目前時間間隔的時間函數 `latest`、、 `first` `last``earliest`和 。
![\[AWS IoT SiteWise 暫時函數會根據其時間戳記傳回資料點。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/sitewise-temporal-functions.png)
**注意**
`first(x)`的時間範圍`last(x)`為 （目前時段開始、目前時段結束】。
的時間範圍`latest(x)`是 （時間開始，目前時段結束】。
的時間範圍`earliest(x)`是 （時間開始，上一個時段結束】。
**時間加權函數參數**
針對彙總時段計算的時間加權函數會考量下列事項：
+ 視窗內的資料點
+ 資料點之間的時間間隔
+ 視窗之前的最後一個資料點
+ 視窗後的第一個資料點 （適用於某些演算法）
**術語：**
+ **資料點錯誤** – 任何品質不佳或非數值的資料點。這不會在視窗結果運算中考慮。
+ **錯誤的間隔** – 資料點錯誤後的間隔。第一個已知資料點之前的間隔也會被視為錯誤的間隔。
+ **良好的資料點** – 具有良好品質和數值的任何資料點。
**注意**
AWS IoT SiteWise 只會在運算轉換和指標時耗用`GOOD`品質資料。它會忽略 `UNCERTAIN`和 `BAD` 資料點。
第一個已知資料點之前的間隔會被視為**錯誤的間隔**。如需詳細資訊，請參閱[公式表達式教學課程](expression-tutorials.md)。
最後一個已知資料點之後的間隔會無限期持續，影響下列所有時段。當新的資料點到達時，函數會重新計算間隔。
遵循上述規則，會計算彙總視窗結果，並限於視窗邊界。根據預設，如果整個視窗的**間隔良好**，則函數只會傳送視窗結果。
如果視窗**良好間隔**小於視窗長度，則函數不會傳送視窗。
當影響視窗結果的資料點變更時，即使資料點位於視窗之外，函數也會重新計算視窗。
如果輸入屬性在其歷史記錄中至少有一個資料點，且已啟動運算，則函數會計算每個時間間隔的時間加權彙總函數。
**Example 狀態時間案例範例**
假設您具有以下屬性的資產：
+ `Idle` – 為 `0`或 的測量`1`。值為 `1` 時，機器處於閒置狀態。
+ `Idle Time` – 使用公式`statetime(Idle)`計算機器閒置時間的指標，以秒為單位，每隔 1 分鐘間隔。
該 `Idle` 屬性具有以下資料點。
| | | | | | |
| --- |--- |--- |--- |--- |--- |
| Timestamp | 2:00:00 PM | 2:00:30 PM | 2:01:15 PM | 2:02:45 PM | 2:04:00 PM |
| Idle | 0 | 1 | 1 | 0 | 0 |
AWS IoT SiteWise 每分鐘會從 的值計算 `Idle Time` 屬性`Idle`。此計算完成之後，`Idle Time` 屬性會具有下列資料點。
| | | | | | |
| --- |--- |--- |--- |--- |--- |
| Timestamp | 2:00:00 PM | 2:01:00 PM | 2:02:00 PM | 2:03:00 PM | 2:04:00 PM |
| Idle Time | N/A | 30 | 60 | 45 | 0 |
AWS IoT SiteWise 會在每分鐘`Idle Time`結束時對 執行下列計算。
+ 下午 2:00 (下午 1:59 至下午 2:00)
+ 下午 2:00 之前 `Idle` 沒有資料，因此不會計算任何資料點。
+ 下午 2:01 (下午 2:00 至下午 2:01)
+ 下午 2:00:00，機器處於作用中狀態 (`Idle` 為 `0`)。
+ 下午 2:00:30，機器處於閒置狀態 (`Idle` 為 `1`)。
+ 在下午 2:01:00 的間隔結束之前 `Idle` 不會再次改變，所以 `Idle Time` 是 30 秒。
+ 下午 2:02 (下午 2:01 至下午 2:02)
+ 下午 2:01:00，機器處於閒置狀態 (即最後一個資料點位於下午 2:00:30)。
+ 下午 2:01:15，機器仍處於閒置狀態。
+ 在下午 2:02:00 的間隔結束之前 `Idle` 不會再次改變，所以 `Idle Time` 是 60 秒。
+ 下午 2:03 (下午 2:02至下午 2:03)
+ 下午 2:02:00，機器處於閒置狀態 (即最後一個資料點位於下午 2:01:15)。
+ 下午 2:02:45，機器處於作用中狀態。
+ 在下午 2:03:00 的間隔結束之前 `Idle` 不會再次改變，所以 `Idle Time` 是 45 秒。
+ 下午 2:04 (下午 2:03 至下午 2:04 )
+ 下午 2:03:00，機器處於作用中狀態 (即最後一個資料點位於下午 2:02:45)。
+ 在下午 2:04:00 的間隔結束之前 `Idle` 不會再次改變，所以 `Idle Time` 是 0 秒。
**Example TimeWeightedAvg 和 TimeWeightedStDev 案例範例**
下表提供這些一分鐘時段指標的範例輸入和輸出：`Avg(x), TimeWeightedAvg(x), TimeWeightedAvg(x, "linear"), stDev(x), timeWeightedStDev(x), timeWeightedStDev(x, 'p')`。
一分鐘彙總時段的範例輸入：
這些資料點都具有`GOOD`品質。
| | |
| --- |--- |
| 03：00：00 | 4.0 |
| 03：01：00 | 2.0 |
| 03：01：10 | 8.0 |
| 03：01：50 | 20.0 |
| 03：02：00 | 14.0 |
| 03：02：05 | 10.0 |
| 03：02：10 | 3.0 |
| 03：02：30 | 20.0 |
| 03：03：30 | 0.0 |
彙總結果輸出：
無 – 未為此時段產生結果。
| 時間 | `Avg(x)` | `TimeWeightedAvg(x)` | `TimeWeightedAvg(X, "linear")` | `stDev(X)` | `timeWeightedStDev(x)` | `timeWeightedStDev(x, 'p')` |
| --- | --- | --- | --- | --- | --- | --- |
| 3：00：00 | 4 | 無 | 無 | 0 | 無 | 無 |
| 3：01：00 | 2 | 4 | 3 | 0 | 0 | 0 |
| 3：02：00 | 14 | 9 | 13 | 6 | 5.430610041581775 | 5.385164807134504 |
| 3：03：00 | 11 | 13 | 12.875 | 8.54400374531753 | 7.724054437220943 | 7.659416862050705 |
| 3：04：00 | 0 | 10 | 2.5 | 0 | 10.084389681792215 | 10 |
| 3：05：00 | 無 | 0 | 0 | 無 | 0 | 0 |
## 在轉換中使用暫時函數
僅在[轉換](transforms.md)中，您可以使用 `pretrigger()`函數，在啟動目前轉換計算的屬性更新之前擷取變數`GOOD`的品質值。
請考慮製造商用來 AWS IoT SiteWise 監控機器狀態的範例。製造商使用下列測量和轉換來代表程序：
+ 測量 `current_state`，可以是 0 或 1。
+ 如果機器處於清除狀態，則 `current_state`等於 1。
+ 如果機器處於製造狀態，則 `current_state`等於 0。
+ 等於 `cleaning_state_duration`的轉換 `if(pretrigger(current_state) == 1, timestamp(current_state) - timestamp(pretrigger(current_state)), none)`。此轉換會以秒為單位傳回機器處於清除狀態的時間，格式為 Unix epoch。如需詳細資訊，請參閱 [在公式表達式中使用條件式函數](expression-conditional-functions.md)和 [timestamp()](expression-date-and-time-functions.md) 函數。
如果機器停留在清除狀態的時間超過預期，製造商可能會調查機器。
您也可以在多變量轉換中使用 `pretrigger()`函數。例如，您有兩個名為 `x`和 `z`的測量`y`，以及一個等於 的轉換 `x + y + pretrigger(y)`。下表顯示 `x`、 `y`和 的值`z`，從上午 9：00 到上午 9：15。
**注意**
此範例假設測量的值依時間順序到達。例如，上午 09：00 `x`的 值會在上午 09：05 `x`的 值之前到達。
如果上午 9：05 的資料點在上午 9：00 的資料點到達，`z`則不會在上午 9：05 計算。
如果上午 9：05 `x`的 值在上午 09：00 `x`的 值之前到達，且依時間順序`y`抵達 的值，則 `z`等於上午 `22 = 20 + 1 + 1` 9：05。
| | 上午 09：00 | 上午 09：05 | 上午 09：10 | 上午 09：15 |
| --- | --- | --- | --- | --- |
| `x` | 10 | 20 | | 30 |
| `y` | 1 | 2 | 3 | |
| `z = x + y + pretrigger(y)` | `y` 在上午 09：00 之前不會收到任何資料點。因此， `z` 不會在上午 09：00 計算。 | 23 = 20 \$1 2 \$1 1 `pretrigger(y)` 等於 1。 | 25 = 20 \$1 3 \$1 2 `x` 不會收到新的資料點。 `pretrigger(y)`等於 2。 | 36 = 30 \$1 3 \$1 3 `y` 不會收到新的資料點。因此， `pretrigger(y)`等於上午 09：15 的 3。 |
# 在公式表達式中使用日期和時間函數
在[轉換](transforms.md)和[指標](metrics.md)中，您可以透過下列方式使用日期和時間函數：
+ 擷取 UTC 或本機時區中資料點的目前時間戳記。
+ 使用引數建構時間戳記，例如 `year`、 `month`和 `day_of_month`。
+ 使用 `unix_time`引數擷取期間，例如年份或月份。
| 函式 | Description |
| --- | --- |
| `now()` | 以秒為單位，以 Unix epoch 格式傳回目前的日期和時間。 |
| `timestamp()` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-date-and-time-functions.html) |
| `mktime(time_zone, year, month, day_of_month, hour, minute, second)` | 以秒為單位，以 Unix epoch 格式傳回輸入時間。 下列需求適用於使用此函數： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-date-and-time-functions.html) 下列限制適用於使用此函數： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-date-and-time-functions.html) 範例： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-date-and-time-functions.html) |
| `localtime(unix_time, time_zone)` | 傳回從 Unix 時間起算，指定時區中的年份、日期、星期幾、星期幾、小時、分鐘或秒。 下列需求適用於使用此函數： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-date-and-time-functions.html) 回應範例： `2007-12-03T10:15:30+01:00[Europe/Paris]` `localtime(unix_time, time_zone)` 不是獨立的 函數。`year()`、`mon()`、`mday`、`wday()`、`yday()`、`hour()`、 `minute()`和 `sec()`函數採用 `localtime(unix_time, time_zone)`作為引數。 範例： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/expression-date-and-time-functions.html) |
| `year(localtime(unix_time, time_zone)` | 從 傳回年份`localtime(unix_time, time_zone)`。 |
| `mon(localtime(unix_time, time_zone))` | 從 傳回月份`localtime(unix_time, time_zone)`。 |
| `mday(localtime(unix_time, time_zone))` | 從 傳回當月的日期`localtime(unix_time, time_zone)`。 |
| `wday(localtime(unix_time, time_zone))` | 從 傳回星期幾`localtime(unix_time, time_zone)`。 |
| `yday(localtime(unix_time, time_zone))` | 從 傳回一年中的日期`localtime(unix_time, time_zone)`。 |
| `hour(localtime(unix_time, time_zone))` | 從 傳回小時`localtime(unix_time, time_zone)`。 |
| `minute(localtime(unix_time, time_zone))` | 從 傳回分鐘`localtime(unix_time, time_zone)`。 |
| `sec(localtime(unix_time, time_zone))` | 從 傳回第二個 `localtime(unix_time, time_zone)`。 |
## 支援的時區格式
您可以透過下列方式指定時區引數：
+ 時區位移 - `'Z'`指定 UTC 或位移 (`'+2'` 或 `'-5'`)。
+ 位移 IDs - 結合時區縮寫和位移。例如，`'GMT+2'` 和 `'UTC-01:00'`。時區縮寫只能包含三個字母。
+ 區域型 IDs - 例如 `'Etc/GMT+12'`和 `'Pacific/Pago_Pago'`。
### 支援的時區縮寫
日期和時間函數支援下列三個字母的時區縮寫：
+ EST - -05：00
+ HST - -10：00
+ MST - -07：00
+ ACT - 澳洲/達爾文
+ AET - 澳洲/雪梨
+ AGT - 美洲/阿根廷/布宜諾斯\$1Aires
+ ART - 非洲/開羅
+ AST - 美洲/安克拉治
+ BET - 美洲/聖保羅
+ BST - 亞洲/達卡
+ CAT - 非洲/哈拉雷
+ CET - 歐洲/巴黎
+ CNT - 美洲/聖約翰
+ CST - 美洲/芝加哥
+ CTT - 亞洲/上海
+ EAT - 非洲/Addis\$1Ababa
+ IET - America/Indiana/Indianapolis
+ IST - 亞洲/加爾各答
+ JST - 亞洲/東京
+ MIT - 太平洋/非洲
+ NET - 亞洲/葉文
+ NST - 太平洋/奧克蘭
+ PLT - 亞洲/喀拉蚩
+ PRT - 美洲/波多黎各
+ PST - 美洲/Los\$1Angeles
+ SST - 太平洋/瓜達爾加納爾
+ VST - 亞洲/Ho\$1Chi\$1Minh
### 支援的區域型 IDs
日期和時間函數支援下列區域型 IDs，依其與 UTC\$100：00 的關係進行組織：
+ Etc/GMT\$112 (UTC-12：00)
+ Pacific/Pago\$1Pago (UTC-11：00)
+ Pacific/Samoa (UTC-11：00)
+ Pacific/Niue (UTC-11：00)
+ 美國/薩摩亞 (UTC-11：00)
+ Etc/GMT\$111 (UTC-11：00)
+ Pacific/Midway (UTC-11：00)
+ Pacific/Honolulu (UTC-10：00)
+ 太平洋/羅克頓加 (UTC-10：00)
+ 太平洋/大溪地 (UTC-10：00)
+ Pacific/Johnston (UTC-10：00)
+ 美國/夏威夷 (UTC-10：00)
+ SystemV/HST10 (UTC-10：00)
+ Etc/GMT\$110 (UTC-10：00)
+ Pacific/Marquesas (UTC-09：30)
+ Etc/GMT\$19 (UTC-09：00)
+ Pacific/Gambier (UTC-09：00)
+ America/Atka (UTC-09：00)
+ SystemV/YST9 (UTC-09：00)
+ America/Adak (UTC-09：00)
+ 美國/阿留申文 (UTC-09：00)
+ Etc/GMT\$18 (UTC-08：00)
+ 美國/阿拉斯加 (UTC-08：00)
+ America/Juneau (UTC-08：00)
+ America/Metlakatla (UTC-08：00)
+ America/Yakutat (UTC-08：00)
+ Pacific/Pitcairn (UTC-08：00)
+ America/Sitka (UTC-08：00)
+ 美洲/安克拉治 (UTC-08：00)
+ SystemV/PST8 (UTC-08：00)
+ 美洲/北美洲 (UTC-08：00)
+ SystemV/YST9YDT (UTC-08：00)
+ 加拿大/伊克隆 (UTC-07：00)
+ 美國/太平洋-新 (UTC-07：00)
+ Etc/GMT\$17 (UTC-07：00)
+ 美國/亞利桑那州 (UTC-07：00)
+ America/Dawson\$1Creek (UTC-07：00)
+ 加拿大/太平洋 (UTC-07：00)
+ PST8PDT (UTC-07：00)
+ SystemV/MST7 (UTC-07：00)
+ America/Dawson (UTC-07：00)
+ 墨西哥/BajaNorte (UTC-07：00)
+ 美洲/提華納 (UTC-07：00)
+ 美洲/克里頓 (UTC-07：00)
+ America/Hermosillo (UTC-07：00)
+ America/Santa\$1Isabel (UTC-07：00)
+ America/Vancouver (UTC-07：00)
+ America/Ensenada (UTC-07：00)
+ 美洲/鳳凰城 (UTC-07：00)
+ 美洲/白馬 (UTC-07：00)
+ America/Fort\$1Nelson (UTC-07：00)
+ SystemV/PST8PDT (UTC-07：00)
+ America/Los\$1Angeles (UTC-07：00)
+ 美國/太平洋 (UTC-07：00)
+ America/El\$1Salvador (UTC-06：00)
+ 美洲/瓜地馬拉 (UTC-06：00)
+ 美洲/貝里斯 (UTC-06：00)
+ 美洲/馬拿瓜 (UTC-06：00)
+ 美洲/德古西加巴 (UTC-06：00)
+ Etc/GMT\$16 (UTC-06：00)
+ Pacific/Easter (UTC-06：00)
+ 墨西哥/BajaSur (UTC-06：00)
+ 美洲/區域 (UTC-06：00)
+ 美洲/丹佛 (UTC-06：00)
+ Pacific/Galapagos (UTC-06：00)
+ America/Yellowknife (UTC-06：00)
+ America/Swift\$1Current (UTC-06：00)
+ America/Inuvik (UTC-06：00)
+ 美洲/馬薩特蘭 (UTC-06：00)
+ America/Boise (UTC-06：00)
+ America/Costa\$1Rica (UTC-06：00)
+ MST7MDT (UTC-06：00)
+ SystemV/CST6 (UTC-06：00)
+ 美洲/吉瓦瓦 (UTC-06：00)
+ America/Ojinaga (UTC-06：00)
+ 智利/EasterIsland (UTC-06：00)
+ US/Mountain (UTC-06：00)
+ America/Edmonton (UTC-06：00)
+ 加拿大/山區 (UTC-06：00)
+ America/Cambridge\$1Bay (UTC-06：00)
+ Navajo (UTC-06：00)
+ SystemV/MST7MDT (UTC-06：00)
+ 加拿大/薩克其萬文 (UTC-06：00)
+ 美洲/船舶 (UTC-06：00)
+ 美洲/巴拿馬 (UTC-05：00)
+ 美洲/芝加哥 (UTC-05：00)
+ America/Eirunepe (UTC-05：00)
+ Etc/GMT\$15 (UTC-05：00)
+ 墨西哥/一般 (UTC-05：00)
+ America/Porto\$1Acre (UTC-05：00)
+ 美洲/蓋亞基爾 (UTC-05：00)
+ America/Rankin\$1Inlet (UTC-05：00)
+ 美國/中部 (UTC-05：00)
+ America/Rainy\$1River (UTC-05：00)
+ America/Indiana/Knox (UTC-05：00)
+ America/North\$1Dakota/Beulah (UTC-05：00)
+ America/Monterrey (UTC-05：00)
+ 美洲/牙買加 (UTC-05：00)
+ America/Atikokan (UTC-05：00)
+ America/Coral\$1Harbour (UTC-05：00)
+ America/North\$1Dakota/Center (UTC-05：00)
+ 美洲/開曼島 (UTC-05：00)
+ America/Indiana/Tell\$1City (UTC-05：00)
+ America/Mexico\$1City (UTC-05：00)
+ America/Matamoros (UTC-05：00)
+ CST6CDT (UTC-05：00)
+ America/Knox\$1IN (UTC-05：00)
+ 美洲/波哥大 (UTC-05：00)
+ America/Menominee (UTC-05：00)
+ America/Resolute (UTC-05：00)
+ SystemV/EST5 (UTC-05：00)
+ 加拿大/中部 (UTC-05：00)
+ 巴西/希臘 (UTC-05：00)
+ America/Cancun (UTC-05：00)
+ 美洲/利馬 (UTC-05：00)
+ America/Bahia\$1Banderas (UTC-05：00)
+ US/Indiana-Starke (UTC-05：00)
+ America/Rio\$1Branco (UTC-05：00)
+ SystemV/CST6CDT (UTC-05：00)
+ 牙買加 (UTC-05：00)
+ 美洲/米蘭 (UTC-05：00)
+ America/North\$1Dakota/New\$1Salem (UTC-05：00)
+ America/Winnipeg (UTC-05：00)
+ America/Cuiaba (UTC-04：00)
+ America/Marigot (UTC-04：00)
+ America/Indiana/Petersburg (UTC-04：00)
+ 智利/洲 (UTC-04：00)
+ America/Grand\$1Turk (UTC-04：00)
+ 古巴 (UTC-04：00)
+ Etc/GMT\$14 (UTC-04：00)
+ 美洲/馬納斯 (UTC-04：00)
+ America/Fort\$1Wayne (UTC-04：00)
+ America/St\$1Thomas (UTC-04：00)
+ 美洲/安圭拉 (UTC-04：00)
+ 美洲/哈瓦那 (UTC-04：00)
+ 美國/密西根州 (UTC-04：00)
+ 美洲/巴貝多 (UTC-04：00)
+ 美洲/路易斯維爾 (UTC-04：00)
+ 美洲/庫拉索 (UTC-04：00)
+ 美洲/蓋亞那 (UTC-04：00)
+ America/Martinique (UTC-04：00)
+ America/Puerto\$1Rico (UTC-04：00)
+ America/Port\$1of\$1Spain (UTC-04：00)
+ SystemV/AST4 (UTC-04：00)
+ America/Indiana/Vevay (UTC-04：00)
+ America/Indiana/Vincennes(UTC-04：00)
+ America/Kralendijk (UTC-04：00)
+ 美洲/安提瓜 (UTC-04：00)
+ 美洲/印地安那波利斯 (UTC-04：00)
+ America/Iqaluit (UTC-04：00)
+ America/St\$1Vincent (UTC-04：00)
+ America/Kentucky/Louisville (UTC-04：00)
+ 美洲/多明尼加 (UTC-04：00)
+ America/Asuncion (UTC-04：00)
+ EST5EDT (UTC-04：00)
+ 美洲/拿索 (UTC-04：00)
+ America/Kentucky/Monticello (UTC-04：00)
+ 巴西/西部 (UTC-04：00)
+ 美洲/阿魯巴 (UTC-04：00)
+ America/Indiana/Indianapolis(UTC-04：00)
+ 美洲/聖地牙哥 (UTC-04：00)
+ America/La\$1Paz (UTC-04：00)
+ America/Thunder\$1Bay (UTC-04：00)
+ America/Indiana/Marengo (UTC-04：00)
+ America/Blanc-Sablon (UTC-04：00)
+ America/Santo\$1Domingo (UTC-04：00)
+ 美國/東部 (UTC-04：00)
+ 加拿大/東部 (UTC-04：00)
+ 美洲/Port-au-Prince(UTC-04：00)
+ America/St\$1Barthelemy (UTC-04：00)
+ America/Nipigon (UTC-04：00)
+ 美國/印度東部 (UTC-04：00)
+ America/St\$1Lucia (UTC-04：00)
+ 美洲/蒙特塞拉特 (UTC-04：00)
+ America/Lower\$1Princes (UTC-04：00)
+ America/Detroit (UTC-04：00)
+ America/Tortola (UTC-04：00)
+ America/Porto\$1Velho (UTC-04：00)
+ America/Campo\$1Grande (UTC-04：00)
+ 美洲/維吉尼亞 (UTC-04：00)
+ America/Pangnirtung (UTC-04：00)
+ 美洲/蒙特婁 (UTC-04：00)
+ America/Indiana/Winamac (UTC-04：00)
+ America/Boa\$1Vista (UTC-04：00)
+ 美洲/格瑞那達 (UTC-04：00)
+ America/New\$1York (UTC-04：00)
+ America/St\$1Kitts (UTC-04：00)
+ 美洲/卡拉卡斯 (UTC-04：00)
+ 美洲/瓜德洛普 (UTC-04：00)
+ 美洲/多倫多 (UTC-04：00)
+ SystemV/EST5EDT (UTC-04：00)
+ America/Argentina/Catamarca (UTC-03：00)
+ 加拿大/大西洋 (UTC-03：00)
+ America/Argentina/Cordoba (UTC-03：00)
+ 美洲/阿拉圭 (UTC-03：00)
+ America/Argentina/Salta (UTC-03：00)
+ Etc/GMT\$13 (UTC-03：00)
+ America/Montevideo (UTC-03：00)
+ 巴西/東部 (UTC-03：00)
+ America/Argentina/Mendoza (UTC-03：00)
+ America/Argentina/Rio\$1Gallegos (UTC-03：00)
+ America/Catamarca (UTC-03：00)
+ America/Cordoba (UTC-03：00)
+ America/Sao\$1Paulo (UTC-03：00)
+ America/Argentina/Jujuy (UTC-03：00)
+ America/Cayenne (UTC-03：00)
+ America/Recife (UTC-03：00)
+ America/Buenos\$1Aires (UTC-03：00)
+ America/Paramaribo (UTC-03：00)
+ America/Moncton (UTC-03：00)
+ 美洲/門多薩 (UTC-03：00)
+ America/Santarem (UTC-03：00)
+ Atlantic/Bermuda (UTC-03：00)
+ America/Maceio (UTC-03：00)
+ 大西洋/斯坦利 (UTC-03：00)
+ America/Halifax (UTC-03：00)
+ 南極/盧比 (UTC-03：00)
+ America/Argentina/San\$1Luis (UTC-03：00)
+ America/Argentina/Ushuaia(UTC-03：00)
+ Antarctica/Palmer (UTC-03：00)
+ America/Punta\$1Arenas (UTC-03：00)
+ America/Glace\$1Bay (UTC-03：00)
+ America/Fortaleza (UTC-03：00)
+ 美洲/泰國 (UTC-03：00)
+ America/Argentina/La\$1Rioja (UTC-03：00)
+ America/Belem (UTC-03：00)
+ America/Jujuy (UTC-03：00)
+ 美洲/巴亞 (UTC-03：00)
+ America/Goose\$1Bay (UTC-03：00)
+ America/Argentina/San\$1Juan (UTC-03：00)
+ America/Argentina/ComodRivadavia (UTC-03：00)
+ America/Argentina/Tucuman (UTC-03：00)
+ America/Rosario (UTC-03：00)
+ SystemV/AST4ADT (UTC-03：00)
+ America/Argentina/Buenos\$1Aires (UTC-03：00)
+ America/St\$1Johns (UTC-02：30)
+ 加拿大/紐芬蘭 (UTC-02：30)
+ America/Miquelon (UTC-02：00)
+ Etc/GMT\$12 (UTC-02：00)
+ America/Godthab (UTC-02：00)
+ America/Noronha (UTC-02：00)
+ 巴西/DeNoronha (UTC-02：00)
+ 大西洋/南部\$1喬治亞 (UTC-02：00)
+ Etc/GMT\$11 (UTC-01：00)
+ Atlantic/Cape\$1Verde (UTC-01：00)
+ Pacific/Kiritimati (UTC\$114：00)
+ Etc/GMT-14 (UTC\$114：00)
+ Pacific/Fakaofo (UTC\$113：00)
+ Pacific/Enderbury (UTC\$113：00)
+ Pacific/Apia (UTC\$113：00)
+ Pacific/Tongatapu (UTC\$113：00)
+ Etc/GMT-13 (UTC\$113：00)
+ NZ-CHAT (UTC\$112：45)
+ Pacific/Chatham (UTC\$112：45)
+ Pacific/Kwajalein (UTC\$112：00)
+ 南極/McMurdo (UTC\$112：00)
+ Pacific/Wallis (UTC\$112：00)
+ Pacific/Fiji (UTC\$112：00)
+ Pacific/Funafuti (UTC\$112：00)
+ Pacific/Nauru (UTC\$112：00)
+ Kwajalein (UTC\$112：00)
+ NZ (UTC\$112：00)
+ Pacific/Wake (UTC\$112：00)
+ 南極/南極 (UTC\$112：00)
+ Pacific/Tarawa (UTC\$112：00)
+ 太平洋/奧克蘭 (UTC\$112：00)
+ Asia/Kamchatka (UTC\$112：00)
+ Etc/GMT-12 (UTC\$112：00)
+ 亞洲/安多爾 (UTC\$112：00)
+ Pacific/Majuro (UTC\$112：00)
+ Pacific/Ponape (UTC\$111：00)
+ Pacific/Bougainville (UTC\$111：00)
+ 南極/Macquarie (UTC\$111：00)
+ Pacific/Pohnpei (UTC\$111：00)
+ Pacific/Efate (UTC\$111：00)
+ Pacific/Norfolk (UTC\$111：00)
+ 亞洲/馬加達文 (UTC\$111：00)
+ Pacific/Kosrae (UTC\$111：00)
+ Asia/Sakhalin (UTC\$111：00)
+ Pacific/Noumea (UTC\$111：00)
+ Etc/GMT-11 (UTC\$111：00)
+ Asia/Srednekolymsk (UTC\$111：00)
+ Pacific/Guadalcanal (UTC\$111：00)
+ Australia/Lord\$1Howe (UTC\$110：30)
+ 澳洲/LHI (UTC\$110：30)
+ 澳洲/哈巴特 (UTC\$110：00)
+ Pacific/Yap (UTC\$110：00)
+ 澳洲/塔斯馬尼亞 (UTC\$110：00)
+ Pacific/Port\$1Moresby (UTC\$110：00)
+ 澳洲/ACT (UTC\$110：00)
+ 澳洲/維吉尼亞 (UTC\$110：00)
+ Pacific/Chuuk (UTC\$110：00)
+ 澳洲/芬蘭 (UTC\$110：00)
+ 澳洲/坎培拉 (UTC\$110：00)
+ 澳洲/馬里 (UTC\$110：00)
+ 太平洋/關島 (UTC\$110：00)
+ Pacific/Truk (UTC\$110：00)
+ 澳洲/NSW (UTC\$110：00)
+ Asia/Vladivostok (UTC\$110：00)
+ 太平洋/塞班 (UTC\$110：00)
+ 南極/DumontDUrville (UTC\$110：00)
+ 澳洲/雪梨 (UTC\$110：00)
+ 澳洲/布里斯班 (UTC\$110：00)
+ Etc/GMT-10 (UTC\$110：00)
+ Asia/Ust-Nera (UTC\$110：00)
+ 澳洲/墨爾本 (UTC\$110：00)
+ 澳洲/林德曼 (UTC\$110：00)
+ 澳洲/北部 (UTC\$109：30)
+ 澳洲/雅科文納 (UTC\$109：30)
+ 澳洲/阿德雷德 (UTC\$109：30)
+ Australia/Broken\$1Hill (UTC\$109：30)
+ 澳洲/南部 (UTC\$109：30)
+ 澳洲/達爾文 (UTC\$109：30)
+ Etc/GMT-9 (UTC\$109：00)
+ Pacific/Palau (UTC\$109：00)
+ 亞洲/中國 (UTC\$109：00)
+ Asia/Dili (UTC\$109：00)
+ 亞洲/日本 (UTC\$109：00)
+ 亞洲/雅各斯克 (UTC\$109：00)
+ Asia/Pyongyang (UTC\$109：00)
+ ROK (UTC\$109：00)
+ 亞洲/首爾 (UTC\$109：00)
+ Asia/Khandyga (UTC\$109：00)
+ 日本 (UTC\$109：00)
+ 亞洲/東京 (UTC\$109：00)
+ Australia/Eucla (UTC\$108：45)
+ Asia/Kuching (UTC\$108：00)
+ 亞洲/北京 (UTC\$108：00)
+ Etc/GMT-8 (UTC\$108：00)
+ 澳洲/伯斯 (UTC\$108：00)
+ 亞洲/澳門 (UTC\$108：00)
+ 亞洲/澳門 (UTC\$108：00)
+ Asia/Choibalsan (UTC\$108：00)
+ 亞洲/上海 (UTC\$108：00)
+ 南極/凱西 (UTC\$108：00)
+ Asia/Ulan\$1Bator (UTC\$108：00)
+ 亞洲/重慶 (UTC\$108：00)
+ 亞洲/阿拉伯聯合大公國 (UTC\$108：00)
+ 亞洲/台北 (UTC\$108：00)
+ 亞洲/曼尼拉 (UTC\$108：00)
+ PRC (UTC\$108：00)
+ Asia/Ujung\$1Pandang (UTC\$108：00)
+ 亞洲/哈爾賓 (UTC\$108：00)
+ 新加坡 (UTC\$108：00)
+ 亞洲/布魯伊 (UTC\$108：00)
+ 澳洲/西部 (UTC\$108：00)
+ 亞洲/香港\$1香港 (UTC\$108：00)
+ 亞洲/馬卡薩爾 (UTC\$108：00)
+ 香港 (UTC\$108：00)
+ Asia/Kuala\$1Lumpur (UTC\$108：00)
+ 亞洲/伊爾庫次克 (UTC\$108：00)
+ 亞洲/新加坡 (UTC\$108：00)
+ Asia/Pontianak (UTC\$107：00)
+ Etc/GMT-7 (UTC\$107：00)
+ Asia/Phnom\$1Penh (UTC\$107：00)
+ 亞洲/Novosibirsk (UTC\$107：00)
+ 南極/達維斯 (UTC\$107：00)
+ 亞洲/東京 (UTC\$107：00)
+ 亞洲/雅加達 (UTC\$107：00)
+ 亞洲/巴納爾 (UTC\$107：00)
+ 印度/聖誕 (UTC\$107：00)
+ 亞洲/Ho\$1Chi\$1Minh (UTC\$107：00)
+ Asia/Hovd (UTC\$107：00)
+ 亞洲/曼谷 (UTC\$107：00)
+ Asia/Vientiane (UTC\$107：00)
+ 亞洲/Novokuznetsk (UTC\$107：00)
+ 亞洲/克拉斯諾亞爾斯克 (UTC\$107：00)
+ Asia/Saigon (UTC\$107：00)
+ 亞洲/仰光 (UTC\$106：30)
+ Asia/Rangoon (UTC\$106：30)
+ 印度/可哥斯 (UTC\$106：30)
+ 亞洲/喀什加爾 (UTC\$106：00)
+ Etc/GMT-6 (UTC\$106：00)
+ Asia/Almaty (UTC\$106：00)
+ 亞洲/達卡 (UTC\$106：00)
+ 亞洲/大阪 (UTC\$106：00)
+ 亞洲/達卡 (UTC\$106：00)
+ 印度/芝加哥 (UTC\$106：00)
+ Asia/Qyzylorda (UTC\$106：00)
+ 亞洲/比什克文 (UTC\$106：00)
+ 南極/維斯托克 (UTC\$106：00)
+ 亞洲/烏魯木齊 (UTC\$106：00)
+ Asia/Thimbu (UTC\$106：00)
+ 亞洲/明湖 (UTC\$106：00)
+ 亞洲/加德滿都 (UTC\$105：45)
+ 亞洲/加德滿都 (UTC\$105：45)
+ 亞洲/加爾各答 (UTC\$105：30)
+ 亞洲/可倫坡 (UTC\$105：30)
+ 亞洲/卡庫塔 (UTC\$105：30)
+ Asia/Aqtau (UTC\$105：00)
+ Etc/GMT-5 (UTC\$105：00)
+ Asia/Samarkand (UTC\$105：00)
+ 亞洲/喀拉蚩 (UTC\$105：00)
+ 亞洲/葉卡特琳堡 (UTC\$105：00)
+ Asia/Dushanbe (UTC\$105：00)
+ 印度/馬爾地夫 (UTC\$105：00)
+ 亞洲/歐羅 (UTC\$105：00)
+ 亞洲/塔什干 (UTC\$105：00)
+ 南極/馬遜 (UTC\$105：00)
+ Asia/Aqtobe (UTC\$105：00)
+ Asia/Ashkhabad (UTC\$105：00)
+ Asia/Ashgabat (UTC\$105：00)
+ Asia/Atyrau (UTC\$105：00)
+ 印度/開加勒文 (UTC\$105：00)
+ 伊朗 (UTC\$104：30)
+ 亞洲/德黑蘭 (UTC\$104：30)
+ 亞洲/喀布爾 (UTC\$104：30)
+ 亞洲/葉文 (UTC\$104：00)
+ Etc/GMT-4 (UTC\$104：00)
+ Etc/GMT-4 (UTC\$104：00)
+ 亞洲/杜拜 (UTC\$104：00)
+ 印度/留尼旺 (UTC\$104：00)
+ 歐洲/薩拉托夫 (UTC\$104：00)
+ 歐洲/薩馬拉 (UTC\$104：00)
+ 印度/馬來西亞 (UTC\$104：00)
+ 亞洲/巴庫 (UTC\$104：00)
+ 亞洲/馬斯卡特 (UTC\$104：00)
+ 歐洲/Volgograd (UTC\$104：00)
+ 歐洲/阿斯特拉坎 (UTC\$104：00)
+ 亞洲/提比利斯 (UTC\$104：00)
+ 歐洲/阿拉伯聯合大公國斯克 (UTC\$104：00)
+ Asia/Aden (UTC\$103：00)
+ 非洲/奈洛比 (UTC\$103：00)
+ 歐洲/伊斯坦堡 (UTC\$103：00)
+ Etc/GMT-3 (UTC\$103：00)
+ 歐洲/Zaporozhye (UTC\$103：00)
+ 以色列 (UTC\$103：00)
+ Indian/Comoro (UTC\$103：00)
+ 南極/雪瓦 (UTC\$103：00)
+ 非洲/摩加迪休 (UTC\$103：00)
+ 歐洲/布加勒斯特 (UTC\$103：00)
+ 非洲/亞洲 (UTC\$103：00)
+ 歐洲/馬里漢文 (UTC\$103：00)
+ 亞洲/伊斯坦堡 (UTC\$103：00)
+ 歐洲/特拉索波爾 (UTC\$103：00)
+ 歐洲/莫斯科 (UTC\$103：00)
+ 歐洲/中國 (UTC\$103：00)
+ 歐洲/赫爾辛基 (UTC\$103：00)
+ 亞洲/貝魯特 (UTC\$103：00)
+ 亞洲/特拉維夫 (UTC\$103：00)
+ 非洲/吉布地 (UTC\$103：00)
+ 歐洲/塞維多爾 (UTC\$103：00)
+ 歐洲/索菲亞 (UTC\$103：00)
+ 亞洲/加薩 (UTC\$103：00)
+ 非洲/阿斯馬拉 (UTC\$103：00)
+ 歐洲/里加 (UTC\$103：00)
+ 亞洲/巴加達 (UTC\$103：00)
+ 亞洲/大馬士革 (UTC\$103：00)
+ Africa/Dar\$1es\$1Salaam (UTC\$103：00)
+ Africa/Addis\$1Ababa (UTC\$103：00)
+ 歐洲/烏茲哥羅德 (UTC\$103：00)
+ 亞洲/耶路撒冷 (UTC\$103：00)
+ 亞洲/利雅得 (UTC\$103：00)
+ 亞洲/科威特 (UTC\$103：00)
+ 歐洲/基羅夫 (UTC\$103：00)
+ 非洲/坎帕拉 (UTC\$103：00)
+ 歐洲/明斯克 (UTC\$103：00)
+ 亞洲/卡達 (UTC\$103：00)
+ 歐洲/基輔 (UTC\$103：00)
+ 亞洲/巴林 (UTC\$103：00)
+ 歐洲/維爾紐斯 (UTC\$103：00)
+ Indian/Antananarivo (UTC\$103：00)
+ 印度/ Mayotte (UTC\$103：00)
+ 歐洲/塔林 (UTC\$103：00)
+ 土耳其 (UTC\$103：00)
+ 非洲/古巴 (UTC\$103：00)
+ 亞洲/尼科西亞 (UTC\$103：00)
+ 亞洲/法蘭克福 (UTC\$103：00)
+ W-SU (UTC\$103：00)
+ EET (UTC\$103：00)
+ Asia/Hebron (UTC\$103：00)
+ 亞洲/安曼 (UTC\$103：00)
+ 歐洲/尼科西亞 (UTC\$103：00)
+ 歐洲/雅典 (UTC\$103：00)
+ 非洲/開羅 (UTC\$102：00)
+ 非洲/馬巴巴尼 (UTC\$102：00)
+ 歐洲/巴西 (UTC\$102：00)
+ 歐洲/華沙 (UTC\$102：00)
+ CET (UTC\$102：00)
+ 歐洲/盧森堡 (UTC\$102：00)
+ Etc/GMT-2 (UTC\$102：00)
+ 利比亞 (UTC\$102：00)
+ 非洲/基加利 (UTC\$102：00)
+ 非洲/Tripoli (UTC\$102：00)
+ 歐洲/卡寧格勒 (UTC\$102：00)
+ 非洲/溫荷克 (UTC\$102：00)
+ 歐洲/馬爾他 (UTC\$102：00)
+ 歐洲/北京 (UTC\$102：00)
+
+ 歐洲/斯科普耶 (UTC\$102：00)
+ 歐洲/薩拉傑沃 (UTC\$102：00)
+ 歐洲/羅馬 (UTC\$102：00)
+ 歐洲/蘇黎世 (UTC\$102：00)
+ 歐洲/加布羅陀 (UTC\$102：00)
+ 非洲/盧森堡 (UTC\$102：00)
+ 歐洲/維度 (UTC\$102：00)
+ 歐洲/盧比安那 (UTC\$102：00)
+ 歐洲/柏林 (UTC\$102：00)
+ 歐洲/斯德哥爾摩 (UTC\$102：00)
+ 歐洲/布達佩斯 (UTC\$102：00)
+ 歐洲/札格瑞布 (UTC\$102：00)
+ 歐洲/巴黎 (UTC\$102：00)
+ Africa/Ceuta (UTC\$102：00)
+ 歐洲/布拉格 (UTC\$102：00)
+ Antarctica/Troll (UTC\$102：00)
+ 非洲/加布隆 (UTC\$102：00)
+ 歐洲/哥本哈根 (UTC\$102：00)
+ 歐洲/維也納 (UTC\$102：00)
+ 歐洲/土耳其 (UTC\$102：00)
+ MET (UTC\$102：00)
+ 歐洲/阿姆斯特丹 (UTC\$102：00)
+ 非洲/馬普索 (UTC\$102：00)
+ 歐洲/桑\$1馬利諾 (UTC\$102：00)
+ 波蘭 (UTC\$102：00)
+ 歐洲/安道爾 (UTC\$102：00)
+ 歐洲/奧斯陸 (UTC\$102：00)
+ 歐洲/Podgorica (UTC\$102：00)
+ 非洲/布漢布拉 (UTC\$102：00)
+ Atlantic/Jan\$1Mayen (UTC\$102：00)
+ 非洲/馬斯魯 (UTC\$102：00)
+ 歐洲/馬德里 (UTC\$102：00)
+ 非洲/布林特爾 (UTC\$102：00)
+ 非洲/俄羅斯 (UTC\$102：00)
+ 非洲/哈拉雷 (UTC\$102：00)
+ 非洲/喀土木 (UTC\$102：00)
+ 非洲/約翰尼斯堡 (UTC\$102：00)
+ 歐洲/貝爾格勒 (UTC\$102：00)
+ 歐洲/布拉迪斯拉瓦 (UTC\$102：00)
+ 北極/長年比 (UTC\$102：00)
+ 埃及 (UTC\$102：00)
+ 歐洲/梵蒂岡 (UTC\$102：00)
+ 歐洲/摩納哥 (UTC\$102：00)
+ 歐洲/倫敦 (UTC\$101：00)
+ Etc/GMT-1 (UTC\$101：00)
+ 歐洲/澤西 (UTC\$101：00)
+ 歐洲/格恩西島 (UTC\$101：00)
+ 歐洲/Isle\$1of\$1Man (UTC\$101：00)
+ 非洲/突尼斯 (UTC\$101：00)
+ 非洲/馬拉波 (UTC\$101：00)
+ GB-Eire (UTC\$101：00)
+ 非洲/拉哥斯 (UTC\$101：00)
+ 非洲/阿爾及爾 (UTC\$101：00)
+ GB (UTC\$101：00)
+ 葡萄牙 (UTC\$101：00)
+ Africa/Sao\$1Tome (UTC\$101：00)
+ 非洲/Ndjamena (UTC\$101：00)
+ 大西洋/法蘭克福 (UTC\$101：00)
+ 愛爾蘭 (UTC\$101：00)
+ 大西洋/法羅 (UTC\$101：00)
+ 歐洲/都柏林 (UTC\$101：00)
+ 非洲/利伯維爾 (UTC\$101：00)
+ Africa/El\$1Aaiun (UTC\$101：00)
+ Africa/El\$1Aaiun (UTC\$101：00)
+ 非洲/多拉 (UTC\$101：00)
+ 非洲/布拉薩維爾 (UTC\$101：00)
+ 非洲/波多-諾哥 (UTC\$101：00)
+ 大西洋/馬德拉 (UTC\$101：00)
+ 歐洲/里斯本 (UTC\$101：00)
+ 大西洋/加那利 (UTC\$101：00)
+ 非洲/卡薩布蘭卡 (UTC\$101：00)
+ 歐洲/貝爾法斯特 (UTC\$101：00)
+ 非洲/盧安達 (UTC\$101：00)
+ 非洲/金夏沙 (UTC\$101：00)
+ 非洲/孟買 (UTC\$101：00)
+ WET (UTC\$101：00)
+ 非洲/尼亞米 (UTC\$101：00)
+ GMT (UTC\$100：00)
+ Etc/GMT-0 (UTC\$100：00)
+ Atlantic/St\$1Helena (UTC\$100：00)
+ Etc/GMT\$10 (UTC\$100：00)
+ 非洲/班加爾 (UTC\$100：00)
+ Etc/GMT (UTC\$100：00)
+ 非洲/自由城 (UTC\$100：00)
+ 非洲/巴馬科 (UTC\$100：00)
+ 非洲/庫克里 (UTC\$100：00)
+ 通用 (UTC\$100：00)
+ 非洲/Nouakchott (UTC\$100：00)
+ UTC (UTC\$100：00)
+ Etc/Universal (UTC\$100：00)
+ Atlantic/Azores (UTC\$100：00)
+ 非洲/Abidjan (UTC\$100：00)
+ 非洲/阿克拉 (UTC\$100：00)
+ Etc/UCT (UTC\$100：00)
+ GMT0 (UTC\$100：00)
+ Zulu (UTC\$100：00)Zulu (UTC\$100：00)
+ 非洲/大阪 (UTC\$100：00)
+ 大西洋/雷克雅維克 (UTC\$100：00)
+ Etc/Zulu (UTC\$100：00)
+ 冰島 (UTC\$100：00)
+ 非洲/羅馬 (UTC\$100：00)
+ 格林威治文 (UTC\$100：00)
+ Etc/GMT0 (UTC\$100：00)
+ 美洲/丹麥夏文 (UTC\$100：00)
+ 非洲/達卡 (UTC\$100：00)
+ 非洲/比索 (UTC\$100：00)
+ Etc/Greenwich (UTC\$100：00)
+ 非洲/Timbuktu (UTC\$100：00)
+ UCT (UTC\$100：00)
+ 非洲/蒙羅維亞 (UTC\$100：00)
+ Etc/UTC (UTC\$100：00)
# 公式表達式教學課程
您可以依照這些教學課程來使用 中的公式表達式 AWS IoT SiteWise。
**Topics**
+ [在公式中使用字串](#use-strings-in-formulas)
+ [篩選資料點](#filter-data)
+ [計數符合條件的資料點](#count-filtered-data)
+ [公式中的延遲資料](#late-data)
+ [公式中的資料品質](#data-quality)
+ [未定義、無限和溢出值](#undefined-values)
## 在公式中使用字串
您可以在公式表達式中的字串上操作 。您也可以從參考屬性和測量屬性的變數輸入字串。
**重要**
公式表達式只能輸出雙值或字串值。巢狀運算式可以輸出其他資料類型，例如字串，但整體公式必須評估為數字或字串。您可以使用 [jp 函數](expression-string-functions.md#jp-definition)將字串轉換為數字。布林值必須為 1 (true) 或 0 (false)。如需詳細資訊，請參閱[未定義、無限和溢出值](#undefined-values)。
AWS IoT SiteWise 提供下列公式表達式功能，可用於在字串上操作：
+ [字串常值](expression-literals.md#string-literal-definition)
+ [索引運算子](expression-operators.md#index-operator-definition) (`s[index]`)
+ [配量運算子](expression-operators.md#slice-operator-definition) (`s[start:end:step]`)
+ [比較函數](expression-comparison-functions.md)，您可以使用依[語彙順序](https://en.wikipedia.org/wiki/Lexicographic_order)比較字串
+ [字串函數](expression-string-functions.md)，其中包含可剖析序列化 JSON 物件並將字串轉換為數字的`jp`函數
## 篩選資料點
您可以使用 [if 函數](expression-conditional-functions.md#if-definition)來篩選不符合條件的資料點。`if` 函數會評估條件，並傳回 `true` 和 `false`結果的不同值。您可以使用[無常](expression-constants.md#none-definition)數作為一個`if`函數案例的輸出，以捨棄該案例的資料點。
**篩選出符合條件的資料點**
+ 建立使用 `if`函數的轉換來定義條件，以檢查是否符合條件，並傳回 `none` `result_if_true`或 `result_if_false`值。
**Example 範例：篩選出水未沸騰的資料點**
假設您有提供機器中水溫 `temp_c`（攝氏） 的測量 。您可以定義下列轉換，以篩選出水未沸騰的資料點：
+ 轉換： `boiling_temps = if(gte(temp_c, 100), temp_c, none)` – 如果溫度大於或等於攝氏 100 度，則傳回溫度，否則不會傳回任何資料點。
## 計數符合條件的資料點
您可以使用[比較函數](expression-comparison-functions.md)和 [sum()](expression-aggregation-functions.md#sum-definition) 來計算條件為 true 的資料點數目。
**計算符合條件的資料點**
1. 建立使用比較函數在另一個屬性上定義篩選條件的轉換。
1. 建立可加總符合該條件之資料點的指標。
**Example 範例：計算水沸騰的資料點數量**
假設您有提供機器中水溫 `temp_c`（攝氏） 的測量 。您可以定義下列轉換和指標屬性，以計算水沸騰的資料點數量：
+ 轉換： `is_boiling = gte(temp_c, 100)` – `1` 如果溫度大於或等於攝氏 100 度，則傳回 ，否則傳回 `0`。
+ 指標： `boiling_count = sum(is_boiling)` – 傳回水沸騰的資料點數目。
## 公式中的延遲資料
AWS IoT SiteWise 支援延遲擷取長達 7 天的資料。當 AWS IoT SiteWise 收到延遲資料時，它會重新計算過去時段內輸入延遲資料的任何指標的現有值。這些重新計算會產生資料處理費用。
**注意**
當 AWS IoT SiteWise 運算輸入延遲資料的屬性時，它會使用每個屬性目前的公式表達式。
在 AWS IoT SiteWise 重新計算指標的過去時段之後，它會取代該時段的先前值。如果您啟用該指標的通知， AWS IoT SiteWise 也會發出屬性值通知。這表示您可以針對先前收到通知的相同屬性和時間戳記，接收新的屬性值更新通知。如果您的應用程式或資料湖使用屬性值通知，您必須使用新的值來更新之前的值，使其資料正確無誤。
## 公式中的資料品質
在 中 AWS IoT SiteWise，每個資料點都有一個品質碼，可以是下列其中一項：
+ `GOOD` – 資料不會受到任何問題的影響。
+ `BAD` – 資料會受到感應器故障等問題的影響。
+ `UNCERTAIN` – 資料受到感應器不準確等問題的影響。
AWS IoT SiteWise 只會在運算轉換和指標時耗用`GOOD`品質資料。 AWS IoT SiteWise 輸出只會輸出`GOOD`品質資料以成功運算。如果運算不成功，則 AWS IoT SiteWise 不會輸出該運算的資料點。如果計算導致未定義、無限或溢出值，則可能會發生這種情況。
如需如何查詢資料及依資料品質篩選的詳細資訊，請參閱 [從 查詢資料 AWS IoT SiteWise](query-industrial-data.md)。
## 未定義、無限和溢出值
某些公式表達式 （例如 `x / 0`、 `sqrt(-1)`或 `log(0)`) 會計算在實數系統中未定義、無限或超出 支援範圍的值 AWS IoT SiteWise。當資產屬性的表達式運算未定義、無限或溢位值時， AWS IoT SiteWise 不會輸出該運算的資料點。
AWS IoT SiteWise 如果資料點運算非數值作為公式表達式的結果，也不會輸出資料點。這表示如果您定義計算字串、陣列或[無常](expression-constants.md#none-definition)數的公式，則 AWS IoT SiteWise 不會輸出該運算的資料點。
**Example 範例**
下列每個公式表達式都會產生 AWS IoT SiteWise 無法表示為 number 的值。當計算這些公式表達式時， AWS IoT SiteWise 不會輸出資料點。
+ `x / 0` 未定義。
+ `log(0)` 未定義。
+ `sqrt(-1)` 在實數系統中未定義。
+ `"hello" + " world"` 是字串。
+ `jp('{"values":[3,6,7]}', '$.values')` 是陣列。
+ `if(gte(temp, 300), temp, none)` 當 小於 `none`時`temp`， 為 `300`。
# 建立自訂複合模型 （元件）
如果您使用 主控台，則可自訂複合模型或元件，為您的資產模型和元件模型提供另一層級的組織。您可以使用它們來透過分組屬性或參考其他模型來建構模型。如需使用自訂複合模型的詳細資訊，請參閱 [自訂複合模型 （元件）](custom-composite-models.md)。
您可以在現有的資產模型或元件模型中建立自訂複合模型。自訂複合模型有兩種類型。若要將模型中的相關屬性分組，您可以建立**內嵌**自訂複合模型。若要在資產模型或元件模型中參考元件模型，您可以建立**component-model-based**自訂複合模型。
下列各節說明如何使用 AWS IoT SiteWise API 來建立自訂複合模型。
**Topics**
+ [建立內嵌元件 （主控台）](#create-inline-component-console)
+ [建立內嵌自訂複合模型 (AWS CLI)](#create-inline-composite-models-cli)
+ [建立component-model-based元件 （主控台）](#create-component-console)
+ [建立component-model-based自訂複合模型 (AWS CLI)](#create-component-based-composite-model-cli)
## 建立內嵌元件 （主控台）
您可以使用 AWS IoT SiteWise 主控台來建立定義其自身屬性的內嵌元件。
**注意**
由於這是*內嵌*元件，因此這些屬性僅適用於目前的資產模型，不會在其他地方共用。
如果您需要產生可重複使用的模型 （例如，要在多個資產模型之間共用，或在一個資產模型中包含多個執行個體），您應該改為根據元件模型建立元件。如需詳細資訊，請參閱下一節。
**建立元件 （主控台）**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Models (模型)**。
1. 選擇您要新增元件的資產模型。
1. 在**屬性**索引標籤上，選擇**元件**。
1. 選擇**建立元件**。
1. 在**建立元件**頁面上，執行下列動作：
1. 輸入元件**的名稱**，例如 **ServoMotor**或 **ServoMotor Model**。此名稱在此區域您帳戶中的所有元件中必須是唯一的。
1. (選擇性) 新增模型的 **Attribute definitions (屬性定義)**。屬性代表很少變更的資訊。如需詳細資訊，請參閱[定義靜態資料 （屬性）](attributes.md)。
1. (選擇性) 新增模型的 **Measurement definitions (衡量值定義)**。測量代表來自您設備的資料串流。如需詳細資訊，請參閱[從設備定義資料串流 （度量）](measurements.md)。
1. (選擇性) 新增模型的 **Transform definitions (轉換定義)**。轉換是將資料從一個表單映射到另一個表單的公式。如需詳細資訊，請參閱[轉換資料 （轉換）](transforms.md)。
1. (選擇性) 新增模型的 **Metric definitions (指標定義)**。指標是跨時間間隔彙總資料的公式。指標可以從相關聯的資產輸入資料，讓您可以計算代表操作或操作子集的值。如需詳細資訊，請參閱[從屬性和其他資產彙總資料 （指標）](metrics.md)。
1. 選擇**建立元件**。
## 建立內嵌自訂複合模型 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 來建立定義自己的屬性的內嵌自訂複合模型。
使用 [CreateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModelCompositeModel.html) 操作來建立具有 屬性的內嵌模型。此操作預期會有具備下列結構的承載。
**注意**
由於這是*內嵌*複合模型，因此這些屬性僅適用於目前的資產模型，不會在其他地方共用。讓它「內嵌」的原因在於它不會為 `composedAssetModelId` 欄位提供值。
如果您需要產生可重複使用的模型 （例如，要在多個資產模型之間共用，或在一個資產模型中包含多個執行個體），您應該改為建立以*component-model-based*複合模型。如需詳細資訊，請參閱下一節。
```
{
"assetModelCompositeModelName": "CNCLathe_ServoMotorA",
"assetModelCompositeModelType": "CUSTOM",
"assetModelCompositeModelProperties": [
{
"dataType": "DOUBLE",
"name": "Servo Motor Temperature",
"type": {
"measurement": {}
},
"unit": "Celsius"
},
{
"dataType": "DOUBLE",
"name": "Spindle speed",
"type": {
"measurement": {}
},
"unit": "rpm"
}
]
}
```
## 建立component-model-based元件 （主控台）
您可以使用 AWS IoT SiteWise 主控台，根據元件模型建立元件。
**建立component-model-based元件 （主控台）**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Models (模型)**。
1. 選擇您要新增元件的資產模型。
1. 在**屬性**索引標籤上，選擇**元件**。
1. 選擇**建立元件**。
1. 在**建立元件**頁面上，執行下列動作：
1. 選取您要以元件為基礎的元件模型。
1. 輸入元件**的名稱**，例如 **ServoMotor**或 **ServoMotor Model**。此名稱在此區域您帳戶中的所有元件中必須是唯一的。
1. 選擇**建立元件**。
## 建立component-model-based自訂複合模型 (AWS CLI)
您可以使用 AWS CLI 在資產模型中建立component-model-based自訂複合模型。component-model-based自訂複合模型是您已在其他位置定義的元件模型參考。
使用 [CreateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModelCompositeModel.html) 操作建立component-model-based自訂複合模型。此操作預期會有具備下列結構的承載。
**注意**
在此範例中， 的值`composedAssetModelId`是資產模型 ID 或現有元件模型的外部 ID。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。如需如何建立元件模型的範例，請參閱 [建立元件模型 (AWS CLI)](create-component-models.md#create-component-model-cli)。
```
{
"assetModelCompositeModelName": "CNCLathe_ServoMotorA",
"assetModelCompositeModelType": "CUSTOM",
"composedAssetModelId": component model ID
]
```
由於它只是參考，component-model-based自訂複合模型除了名稱之外沒有自己的屬性。
如果您想要將相同元件的多個執行個體新增至資產模型 （例如，具有多個伺服馬達的 CNC 機器），您可以新增多個component-model-based自訂複合模型，每個模型都有自己的名稱，但都參考相同的 `composedAssetModelId`。
您可以在其他元件中巢狀化元件。若要這樣做，您可以將以component-model-based複合模型新增至其中一個元件模型，如本範例所示。
# 在 中建立資產模型的資產 AWS IoT SiteWise
您可以從資產模型建立資產。您必須先擁有資產模型，才能建立資產。若您尚未建立資產模型，請參閱 [在 中建立資產模型 AWS IoT SiteWise](create-asset-models.md)。
**注意**
您只能從 `ACTIVE` 模型建立資產。如果模型狀態不是 `ACTIVE`，您可能需要等待幾分鐘，才能從該模型建立資產。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。
**Topics**
+ [建立資產 （主控台）](#create-asset-console)
+ [建立資產 (AWS CLI)](#create-asset-cli)
+ [設定新的資產](create-asset-next-steps.md)
## 建立資產 （主控台）
您可以使用 AWS IoT SiteWise 主控台來建立資產。
**建立資產 (主控台)**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Assets (資產)**。
1. 選擇 **Create asset (建立資產)**。
1. 在 **Create asset (建立資產)** 頁面上，執行下列動作：
1. 針對 **Model (模型)**，選擇要從中建立資產的資產模型。
**注意**
如果您的模型非 **ACTIVE (作用中)**，則必須等候模型處於作用中狀態，或如果模型為 **FAILED (失敗)**，則必須解決問題。
1. 輸入資產的 **Name (名稱)**。
1. (選用) 為您的資產新增標籤。如需詳細資訊，請參閱[標記您的 AWS IoT SiteWise 資源](tag-resources.md)。
1. 選擇 **Create asset (建立資產)**。
當您建立資產時， AWS IoT SiteWise 主控台會導覽至新資產的頁面。在此頁面上，您可以看到資產的 **Status (狀態)**，最初為 **CREATING (建立中)**。此頁面會自動更新，因此您可以等候資產的狀態更新。
**注意**
資產建立程序可能需要一分鐘的時間。**狀態**為 **ACTIVE** 之後，您可以對資產執行更新操作。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。
建立資產後，請參閱 [設定新的資產](create-asset-next-steps.md)。
## 建立資產 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 從資產模型建立資產。
您必須具有 `assetModelId` 才能建立資產。如果您已建立資產模型，但不知道其 `assetModelId`，請使用 [ListAssetModels](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssetModels.html) API 來檢視所有資產模型。
若要從資產模型建立資產，請使用 [CreateAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAsset.html) API 搭配下列參數：
+ `assetName` – 新資產的名稱。為您的資產命名以協助您識別它。
+ `assetModelId` – 資產的 ID。這是 UUID 格式的實際 ID，`externalId:myExternalId`如果有的話，則為 。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
**建立資產 (AWS CLI)**
+ 執行下列命令以建立資產。將 *asset-name* 取代為資產的名稱，並將 *asset-model-id* 取代為資產模型的 ID 或外部 ID。
```
aws iotsitewise create-asset \
--asset-name asset-name \
--asset-model-id asset-model-id
```
此操作會以下列格式傳回包含新資產詳細資料和狀態的回應。
```
{
"assetId": "String",
"assetArn": "String",
"assetStatus": {
"state": "String",
"error": {
"code": "String",
"message": "String"
}
}
}
```
資產的 `state` 會是 `CREATING`，直到資產建立為止。
**注意**
資產建立程序可能需要一分鐘的時間。若要檢查資產的狀態，請使用 [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html) 操作搭配資產的 ID 做為 `assetId` 參數。在資產的 `state`為 之後`ACTIVE`，您可以對資產執行更新操作。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。
建立資產後，請參閱 [設定新的資產](create-asset-next-steps.md)。
# 設定新的資產
在 中建立資產之後 AWS IoT SiteWise，您可以採取幾個後續步驟，以充分利用資產及其資料。這些步驟可能包括設定資料串流以從資產擷取資料、設定警示和通知以監控資產效能、建立視覺化和儀表板以顯示資產的資料，以及將資產與其他 AWS 服務或第三方應用程式整合以進行進一步分析或自動化。
使用下列選用動作完成資產的設定：
+ [管理 的資料串流 AWS IoT SiteWise](manage-data-streams.md) 如果您的資產具有衡量值屬性。
+ [更新屬性值](update-attribute-values.md) 如果您的資產具有唯一的屬性值。
+ [關聯和取消關聯資產](add-associated-assets.md) 如果您的資產是父項資產。
# 在 上搜尋資產 AWS IoT SiteWise 主控台
使用 AWS IoT SiteWise 主控台 搜尋功能根據中繼資料和即時屬性值篩選條件來尋找資產。
## 先決條件
AWS IoT SiteWise 需要與 整合的許可 AWS IoT TwinMaker ，才能更好地組織和建立工業資料的模型。如果您已授予 的許可 AWS IoT SiteWise，請使用 [ExecuteQuery](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ExecuteQuery.html) API。如果您尚未將許可授予 AWS IoT SiteWise，且需要協助入門，請參閱 [整合 AWS IoT SiteWise 和 AWS IoT TwinMaker](integrate-tm.md)。
## 上的進階搜尋 AWS IoT SiteWise 主控台
### 中繼資料搜尋
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇**資產**下的**進階搜尋**。
1. 在**進階搜尋**下，選擇**中繼資料搜尋**選項。
1. 填寫參數。填寫盡可能多的欄位以進行有效率的搜尋。
1. **資產名稱** — 輸入完整資產名稱或部分名稱以進行廣泛搜尋。
1. **屬性名稱** — 輸入完整屬性名稱或部分名稱以進行廣泛搜尋。
1. **運算**子 — 從中選擇運算子：
+ **=**
+ **<**
+ **>**
+ **<=**
+ **>=**
1. **屬性值** — 此值會與屬性的最新值進行比較。
1. **屬性值類型** — 屬性的資料類型。請選擇下列項目：
+ **雙重**
+ **整數**
+ **：字串**
+ **：布林值**
1. 選擇 **Search** (搜尋)。
1. 從**搜尋結果**表格中，從**名稱**欄中選擇資產。這會帶您前往該資產的詳細資產頁面。
![\[中繼資料搜尋結果。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/search_results_all_fields.png)
#### 部分搜尋
資產搜尋不需要提供所有參數。以下是使用中繼資料搜尋選項的部分搜尋範例：
+ 依資產名稱尋找資產：
+ 單獨在**資產名稱**欄位中輸入值。
+ **屬性名稱**和**屬性值**欄位為空白。
+ 尋找包含具有特定名稱屬性的資產：
+ 單獨在**屬性名稱**欄位中輸入值。
+ **資產名稱**和**屬性值**欄位為空白。
+ 根據其屬性的最新值尋找資產：
+ 在**屬性名稱**和**屬性值**欄位中輸入值。
+ 選取**運算**子和**屬性值類型**。
### 查詢建置器搜尋
1. 導覽至 AWS IoT SiteWise 主控台。
1. 在導覽窗格中，選擇**資產**下的**進階搜尋**。
1. 在**進階搜尋**下，選擇**查詢建置器**選項。
1. 在**查詢建置器**窗格中，撰寫 SQL 查詢以擷取 `asset_name`、 `asset_id`和 `asset_description`。
1. 選擇 **Search** (搜尋)。
1. 從**搜尋結果**表格中，從**名稱**欄中選擇資產。這會帶您前往該資產的詳細資產頁面。
![\[查詢建置器搜尋結果。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/search_results_sql_query.png)
**注意**
SQL 查詢中的 `SELECT`子句必須包含 `asset_name`和 `asset_id` 欄位，以確保**搜尋結果**資料表中的有效資產。
**查詢建置器**只會在結果資料表中顯示**名稱**、**資產 ID **和**描述**。將更多欄位新增至子`SELECT`句並不會將更多資料欄新增至結果資料表
# 更新屬性值
資產會繼承其資產模型的屬性，包括屬性的預設值。在某些情況下，您會想要保留資產模型的預設屬性，例如資產製造商屬性。在其他情況下，您會想要更新繼承的屬性，例如資產的緯度和經度。
------
#### [ Updating an attribute value (console) ]
您可以使用 AWS IoT SiteWise 主控台來更新屬性資產屬性的值。
**更新屬性值 (主控台)**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Assets (資產)**。
1. 選擇您要為其更新屬性的資產。
**提示**
您可以選擇箭頭圖示來展開資產階層，以尋找您的資產。
1. 選擇**編輯**。
1. 尋找要更新的屬性，然後輸入其新值。
![\[AWS IoT SiteWise 「編輯資產」頁面螢幕擷取畫面，並反白顯示屬性值。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/sitewise-update-asset-attribute-console.png)
1. 選擇**儲存**。
------
#### [ Updating an attribute value (AWS CLI) ]
您可以使用 AWS Command Line Interface (AWS CLI) 來更新屬性值。
您必須知道資產的 `assetId` 和財產的 `propertyId`，才能完成此程序。您也可以使用外部 ID。如果您建立資產但不知道其 `assetId`，請使用 [ListAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssets.html) API 列出特定模型的所有資產。使用 [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html) 操作來檢視資產的屬性，包括屬性 IDs。
使用 [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) 操作將屬性值指派給您的資產。您可以使用此操作一次設定多個屬性。此操作的裝載包含項目清單，而每個項目都包含資產 ID、屬性 ID 和屬性值。
**更新屬性的值 (AWS CLI)**
1. 建立名為 `batch-put-payload.json` 的檔案，並將下列 JSON 物件複製到檔案。此範例承載示範如何設定風力發電機的緯度和經度。更新 ID、值和時間戳記，以修改您的使用案例的承載。
```
{
"entries": [
{
"entryId": "windfarm3-turbine7-latitude",
"assetId": "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE",
"propertyId": "a1b2c3d4-5678-90ab-cdef-33333EXAMPLE",
"propertyValues": [
{
"value": {
"doubleValue": 47.6204
},
"timestamp": {
"timeInSeconds": 1575691200
}
}
]
},
{
"entryId": "windfarm3-turbine7-longitude",
"assetId": "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE",
"propertyId": "a1b2c3d4-5678-90ab-cdef-55555EXAMPLE",
"propertyValues": [
{
"value": {
"doubleValue": 122.3491
},
"timestamp": {
"timeInSeconds": 1575691200
}
}
]
}
]
}
```
+ 承載中的每個項目都包含 `entryId`，您可以將其定義為任何獨特的字串。如果有任何請求項目失敗，每個錯誤都會包含對應請求的 `entryId`，這樣您就可以知道要重試哪些請求。
+ 若要設定屬性值，您可以在每個屬性內容的 `propertyValues` 清單中包含一個時間戳記品質值 (TQV) 結構。此結構必須包含新的 `value` 和目前的 `timestamp`。
+ `value` – 包含下列其中一個欄位的結構，取決於所設定屬性的類型：
+ `booleanValue`
+ `doubleValue`
+ `integerValue`
+ `stringValue`
+ `nullValue`
+ `timestamp` – 包含目前 Unix epoch 時間的結構，以秒為單位，`timeInSeconds`. AWS IoT SiteWise 會拒絕過去超過 7 天或未來超過 5 分鐘的任何時間戳記資料點。
如需如何準備 [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) 承載的詳細資訊，請參閱 [使用 AWS IoT SiteWise APIs 擷取資料](ingest-api.md)。
1. 執行下列命令，將屬性值傳送至 AWS IoT SiteWise：
```
aws iotsitewise batch-put-asset-property-value -\-cli-input-json file://batch-put-payload.json
```
------
# 關聯和取消關聯資產
如果您的資產模型定義了任何子資產模型階層，您可以將子資產與您的資產建立關聯。父資產可以存取並從關聯的資產彙總資料。如需階層式資產模型的詳細資訊，請參閱 [定義資產模型階層](define-asset-hierarchies.md)。如果您使用界面，則會在實作界面的資產模型上強制執行界面中定義的階層。如需介面的詳細資訊，請參閱 [資產模型界面](model-interfaces.md)。
**Topics**
+ [關聯和取消關聯資產 （主控台）](#associate-asset-console)
+ [關聯和取消關聯資產 (AWS CLI)](#associate-asset-cli)
## 關聯和取消關聯資產 （主控台）
您可以使用 AWS IoT SiteWise 主控台來關聯和取消關聯資產。
**關聯資產 (主控台)**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Assets (資產)**。
1. 選擇您要關聯子資產的父資產。
**提示**
您可以選擇箭頭圖示來展開資產階層，以尋找您的資產。
1. 選擇**編輯**。
1. 在 **Assets associated to this asset (與此資產相關聯的資產)** 中，選擇 **Add associated asset (新增相關聯的資產)**。
![\[編輯具有此欄位文字的 AWS IoT SiteWise 資產頁面：新增相關聯的資產。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/sitewise-associate-asset-console.png)
1. 針對 **Hierarchy (階層)** 中，選擇定義主資產與子資產之間關係的階層。
1. 對於 **Asset (資產)**，選擇要關聯的子資產。
1. 選擇**儲存**。
**取消關聯資產 (主控台)**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Assets (資產)**。
1. 選擇您要取消關聯子資產的父資產。
**提示**
您可以選擇箭頭圖示來展開資產階層，以尋找您的資產。
1. 選擇**編輯**。
1. 在 **Assets associated to this asset (與此資產相關聯的資產)** 中，選擇資產的 **Disassociate (取消關聯)**。
![\[AWS IoT SiteWise 反白顯示「取消關聯」的「編輯資產」頁面螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/sitewise-disassociate-asset-console.png)
1. 選擇**儲存**。
## 關聯和取消關聯資產 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 來關聯和取消關聯資產。
針對此程序，您必須知道定義與子資產模型之關係的父資產模型中階層 (`hierarchyId`) 的 ID。使用 [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html) 操作來尋找回應中的階層 ID。
**尋找階層 ID**
+ 執行下列命令來描述父資產。將 *parent-asset-id* 取代為父資產的 ID 或外部 ID。
```
aws iotsitewise describe-asset --asset-id parent-asset-id
```
此操作會傳回包含資產詳細資料的回應。回應包含具有下列結構的`assetHierarchies`清單：
```
{
...
"assetHierarchies": [
{
"id": "String",
"name": "String"
}
],
...
}
```
階層 ID 是資產階層清單中階層的 `id` 值。
取得階層 ID 之後，您可以將資產與該階層關聯或取消關聯。
若要將子資產與父項資產建立關聯，請使用 [AssociateAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssociateAssets.html) 操作。若要將子資產與父資產取消關聯，請使用 [DisassociateAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DisassociateAssets.html) 操作。指定下列參數，這兩個操作的參數相同：
+ `assetId` – 父資產的 ID 或外部 ID。
+ `hierarchyId` – 父資產中的階層 ID 或外部 ID。
+ `childAssetId` – 子資產的 ID 或外部 ID。
**建立資產的關聯 (AWS CLI)**
+ 執行下列命令來關聯子資產與父資產。將 *parent-asset-id*、 *hierarchy-id* 和 *child-asset-id* 取代為各自的 IDs：
```
aws iotsitewise associate-assets \
--asset-id parent-asset-id \
--hierarchy-id hierarchy-id \
--child-asset-id child-asset-id
```
**取消資產的關聯 (AWS CLI)**
+ 執行下列命令來取消關聯子資產與父資產。將 *parent-asset-id*、 *hierarchy-id* 和 *child-asset-id* 取代為個別 IDs：
```
aws iotsitewise disassociate-assets \
--asset-id parent-asset-id \
--hierarchy-id hierarchy-id \
--child-asset-id child-asset-id
```
# 更新資產和模型
您可以在 中更新資產、資產模型、元件模型和界面 AWS IoT SiteWise ，以修改其名稱和定義。這些更新操作是非同步的，需要一些時間才能傳播 AWS IoT SiteWise。在進行其他變更之前，請檢查資產或模型的狀態。您必須先等到變更傳播，才能繼續使用更新的資產或模型。
**Topics**
+ [在 中更新資產 AWS IoT SiteWise](update-assets.md)
+ [更新資產模型、元件模型和界面](update-asset-models.md)
+ [更新自訂複合模型 （元件）](update-custom-composite-models.md)
+ [資產模型寫入的樂觀鎖定](opt-locking-for-model.md)
# 在 中更新資產 AWS IoT SiteWise
您可以使用 AWS IoT SiteWise 主控台或 API 來更新資產的名稱。
當您更新資產時，資產的狀態會是 ，`UPDATING`直到變更傳播為止。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。
**Topics**
+ [更新資產 （主控台）](#update-asset-console)
+ [更新資產 (AWS CLI)](#update-asset-cli)
## 更新資產 （主控台）
您可以使用 AWS IoT SiteWise 主控台來更新資產詳細資訊。
**更新資產 (主控台)**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Assets (資產)**。
1. 選擇要更新的資產。
**提示**
您可以選擇箭頭圖示來展開資產階層，以尋找您的資產。
1. 選擇**編輯**。
1. 更新資產的 **Name (名稱)**。
1. (選擇性) 在此頁面上，更新資產的其他資訊。如需詳細資訊，請參閱下列內容：
+ [管理 的資料串流 AWS IoT SiteWise](manage-data-streams.md)
+ [更新屬性值](update-attribute-values.md)
+ [與其他 AWS 服務互動](interact-with-other-services.md)
1. 選擇**儲存**。
## 更新資產 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 來更新資產的名稱。
使用 [UpdateAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAsset.html) 操作來更新資產。指定下列參數：
+ `assetId` – 資產的 ID。這是 UUID 格式的實際 ID，`externalId:myExternalId`如果有的話，則為 。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
+ `assetName` – 資產的新名稱。
**更新資產的名稱 (AWS CLI)**
+ 執行以下命令來更新資產的名稱。以*資產的 ID 或外部 ID 取代 asset-id*。使用*資產的新名稱更新 asset-name*。
```
aws iotsitewise update-asset \
--asset-id asset-id \
--asset-name asset-name
```
# 更新資產模型、元件模型和界面
使用 AWS IoT SiteWise 主控台或 API 更新資產模型、元件模型或界面。
您無法變更現有屬性的類型或資料類型，或現有指標的視窗。您也無法將模型的類型從資產模型變更為元件模型或界面，反之亦然。
**重要**
如果您從資產模型或元件模型中移除屬性， 會 AWS IoT SiteWise 刪除該屬性的所有先前資料。對於元件模型，這會影響**使用該元件模型的所有資產模型**，因此請特別注意了解您的變更可能套用的範圍。
如果您從資產模型中移除階層定義， 會 AWS IoT SiteWise 取消與該階層中的所有資產的關聯。
更新資產模型時，以該模型為基礎的每個資產都會反映您對基礎模型所做的任何變更。在變更傳播之前，每個資產都有 `UPDATING` 狀態。您必須等到這些資產變回 `ACTIVE` 狀態，才能與它們進行互動。在這段期間，更新的資產模型的狀態將是 `PROPAGATING`。
當您更新元件模型時，包含該元件模型的每個資產模型都會反映變更。在元件模型變更傳播之前，每個受影響的資產模型都會具有 `UPDATING` 狀態，然後在更新其相關聯的資產`PROPAGATING`時，如前段所述。您必須等到這些資產模型回到 `ACTIVE` 狀態，才能與其互動。在此期間，更新的元件模型狀態將為 `PROPAGATING`。
如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。
**Topics**
+ [更新資產模型、元件模型或界面 （主控台）](#update-asset-model-console)
+ [更新資產模型、元件模型或界面 (AWS CLI)](#update-asset-model-cli)
## 更新資產模型、元件模型或界面 （主控台）
您可以使用 AWS IoT SiteWise 主控台來更新資產模型、元件模型或界面。
**更新資產模型、元件模型或界面 （主控台）**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Models (模型)**。
1. 選擇要更新的資產模型、元件模型或界面。
1. 選擇**編輯**。
1. 在 **Edit model (編輯模型)** 頁面上，執行以下任一項操作：
+ 在 **Model details (模型詳細資料)** 中，變更模型的 **Name (名稱)**。
+ 變更任何 **Attribute definitions (屬性定義)**。您無法變更現有屬性的 **Data type (資料類型)**。如需詳細資訊，請參閱[定義靜態資料 （屬性）](attributes.md)。
+ 變更任何 **Measurement definitions (衡量值定義)**。您無法變更現有衡量值的 **Data type (資料類型)**。如需詳細資訊，請參閱[從設備定義資料串流 （度量）](measurements.md)。
+ 變更任何 **Transform definitions (轉換定義)**。如需詳細資訊，請參閱[轉換資料 （轉換）](transforms.md)。
+ 變更任何 **Metric definitions (指標定義)**。您無法變更現有指標的 **Time interval (時間間隔)**。如需詳細資訊，請參閱[從屬性和其他資產彙總資料 （指標）](metrics.md)。
+ （僅限資產模型） 變更任何**階層定義**。您無法變更現有階層的 **Hierarchy model (階層模型)**。如需詳細資訊，請參閱[定義資產模型階層](define-asset-hierarchies.md)。
1. 選擇 **Save** (儲存)。
**注意**
如果另一位使用者自上次開啟**編輯模型**頁面後成功更新資產模型，則會拒絕在主控台中提出的更新請求。主控台會提示使用者**重新整理****編輯模型**頁面，以擷取更新的模型。您必須再次進行更新，然後重試儲存。如需詳細資訊，請參閱[資產模型寫入的樂觀鎖定](opt-locking-for-model.md)。
## 更新資產模型、元件模型或界面 (AWS CLI)
使用 AWS Command Line Interface (AWS CLI) 更新資產模型、元件模型或界面。
使用 [UpdateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModel.html) API 更新資產模型、元件模型或界面的名稱、描述和屬性。僅針對資產模型，您可以更新階層。對於介面，您可以更新屬性和階層。指定下列參數：
+ `assetModelId` – 資產的 ID。這是 UUID 格式的實際 ID，`externalId:myExternalId`如果有的話，則為 。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
在承載中指定更新的模型。若要了解資產模型或元件模型的預期格式，請參閱 [在 中建立資產模型 AWS IoT SiteWise](create-asset-models.md)。
**警告**
[UpdateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModel.html) API 會使用您在承載中提供的模型覆寫現有模型。若要避免刪除模型的屬性或階層，您必須在更新的模型承載中包含其 IDs 和定義。若要了解如何查詢模型的現有結構，請參閱 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) 操作。
**注意**
下列程序只能更新類型 的複合模型`AWS/ALARM`。如果您想要更新`CUSTOM`複合模型，請改用 [UpdateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModelCompositeModel.html)。如需詳細資訊，請參閱[更新自訂複合模型 （元件）](update-custom-composite-models.md)。
**更新資產模型或元件模型 (AWS CLI)**
1. 執行下列命令來擷取現有的模型定義。將 *asset-model-id* 取代為要更新的資產模型或元件模型的 ID 或外部 ID。
```
aws iotsitewise describe-asset-model --asset-model-id asset-model-id
```
上述命令會傳回對應至模型最新版本的模型定義。
對於資產模型處於 `FAILED` 狀態的使用案例，請擷取與其作用中版本對應的有效模型定義，以建置您的更新請求。如需詳細資訊，請參閱 [資產模型版本](model-active-version.md)。執行下列命令來擷取作用中模型定義：
```
aws iotsitewise describe-asset-model --asset-model-id asset-model-id --asset-model-version ACTIVE
```
操作會傳回包含模型詳細資訊的回應。回應有以下結構。
```
{
"assetModelId": "String",
"assetModelArn": "String",
"assetModelName": "String",
"assetModelDescription": "String",
"assetModelProperties": Array of AssetModelProperty,
"assetModelHierarchies": Array of AssetModelHierarchyDefinition,
"assetModelCompositeModels": Array of AssetModelCompositeModel,
"assetModelCompositeModelSummaries": Array of AssetModelCompositeModelSummary,
"assetModelCreationDate": "String",
"assetModelLastUpdateDate": "String",
"assetModelStatus": {
"state": "String",
"error": {
"code": "String",
"message": "String"
},
"assetModelType": "String"
},
"assetModelVersion": "String",
"eTag": "String"
}
```
如需詳細資訊，請參閱 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) 操作。
1. 建立名為 `update-asset-model.json` 的文件，並將前一個命令的回應複製到檔案中。
1. 從 JSON 物件的 `update-asset-model.json` 中移除以下鍵值組：
+ `assetModelId`
+ `assetModelArn`
+ `assetModelCompositeModelSummaries`
+ `assetModelCreationDate`
+ `assetModelLastUpdateDate`
+ `assetModelStatus`
+ `assetModelType`
+ `assetModelVersion`
+ `eTag`
[UpdateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModel.html) 操作預期承載具有下列結構：
```
{
"assetModelName": "String",
"assetModelDescription": "String",
"assetModelProperties": Array of AssetModelProperty,
"assetModelHierarchies": Array of AssetModelHierarchyDefinition,
"assetModelCompositeModels": Array of AssetModelCompositeModel
}
```
1. 在 `update-asset-model.json` 中，執行下列任何一項：
+ 變更資產模型的名稱 (`assetModelName`)。
+ 變更、新增或移除資產模型的描述 (`assetModelDescription`)。
+ 變更、新增或移除任何資產模型的屬性 (`assetModelProperties`)。您無法變更現有屬性的 `dataType` 或現有指標的 `window`。如需詳細資訊，請參閱[定義資料屬性](asset-properties.md)。
+ 變更、新增或移除任何資產模型的階層 (`assetModelHierarchies`)。您無法變更現有階層的 `childAssetModelId`。如需詳細資訊，請參閱[定義資產模型階層](define-asset-hierarchies.md)。
+ 變更、新增或移除任何資產模型類型 `AWS/ALARM`() 的複合模型`assetModelCompositeModels`。警示會監控其他屬性，讓您可以識別設備或程序何時需要注意。每個警示定義都是複合模型，可標準化警示使用的屬性集。如需詳細資訊，請參閱[在 中使用警示監控資料 AWS IoT SiteWise](industrial-alarms.md)及[在 中定義資產模型的警示 AWS IoT SiteWise](define-alarms.md)。
1. 執行以下命令，使用儲存在 `update-asset-model.json` 中的定義更新資產模型。將 *asset-model-id* 取代為資產模型的 ID：
```
aws iotsitewise update-asset-model \
--asset-model-id asset-model-id \
--cli-input-json file://model-payload.json
```
**重要**
當多個使用者同時更新資產模型時，其他使用者可能會無意中覆寫使用者的變更。若要避免這種情況，您必須定義條件式更新請求。請參閱 [資產模型寫入的樂觀鎖定](opt-locking-for-model.md)。
# 更新自訂複合模型 （元件）
您可以使用 AWS IoT SiteWise API 更新自訂複合模型，或使用 AWS IoT SiteWise 主控台更新元件。
**Topics**
+ [更新元件 （主控台）](#update-custom-composite-model-console)
+ [更新自訂複合模型 (AWS CLI)](#update-custom-composite-model-cli)
## 更新元件 （主控台）
您可以使用 AWS IoT SiteWise 主控台來更新元件。
**更新元件 （主控台）**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Models (模型)**。
1. 選擇元件所在的資產模型。
1. 在**屬性**索引標籤上，選擇**元件**。
1. 選擇您要更新的元件。
1. 選擇**編輯**。
1. 在**編輯元件**頁面上，執行下列任一動作：
+ 在 **Model details (模型詳細資料)** 中，變更模型的 **Name (名稱)**。
+ 變更任何 **Attribute definitions (屬性定義)**。您無法變更現有屬性的 **Data type (資料類型)**。如需詳細資訊，請參閱[定義靜態資料 （屬性）](attributes.md)。
+ 變更任何 **Measurement definitions (衡量值定義)**。您無法變更現有衡量值的 **Data type (資料類型)**。如需詳細資訊，請參閱[從設備定義資料串流 （度量）](measurements.md)。
+ 變更任何 **Transform definitions (轉換定義)**。如需詳細資訊，請參閱[轉換資料 （轉換）](transforms.md)。
+ 變更任何 **Metric definitions (指標定義)**。您無法變更現有指標的 **Time interval (時間間隔)**。如需詳細資訊，請參閱[從屬性和其他資產彙總資料 （指標）](metrics.md)。
1. 選擇 **Save** (儲存)。
## 更新自訂複合模型 (AWS CLI)
使用 AWS Command Line Interface (AWS CLI) 更新自訂複合模型。
若要更新名稱或描述，請使用 [UpdateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModelCompositeModel.html) 操作。僅適用於內嵌自訂複合模型，您也可以更新屬性。您無法更新以component-model-based自訂複合模型的屬性，因為其參考的元件模型提供其相關聯的屬性。
**重要**
如果您從自訂複合模型中移除屬性， 會 AWS IoT SiteWise 刪除該屬性的所有先前資料。您無法變更現有屬性的類型或資料類型。
若要將現有的複合模型屬性取代為具有相同 的新複合模型屬性`name`，請執行下列動作：
提交已移除整個現有屬性的`UpdateAssetModelCompositeModel`請求。
提交包含新屬性的第二個`UpdateAssetModelCompositeModel`請求。新的資產屬性將與上一個資產屬性`name`相同， AWS IoT SiteWise 並會產生新的唯一 `id`。
**更新自訂複合模型 (AWS CLI)**
1. 若要擷取現有的複合模型定義，請執行下列命令。將 *composite-model-id* 取代為要更新的自訂複合模型的 ID 或外部 ID，並將 *asset-model-id* 取代為與自訂複合模型相關聯的資產模型。如需詳細資訊，請參閱*「AWS IoT SiteWise 使用者指南」*。
1. 執行以下命令：
```
aws iotsitewise describe-asset-model-composite-model \
--asset-model-composite-model-id composite-model-id \
--asset-model-id asset-model-id
```
1. 上述命令會傳回對應至相關聯模型最新版本的複合模型定義。對於資產模型處於 `FAILED` 狀態的使用案例，請擷取與其作用中版本對應的有效模型定義，以建置您的更新請求。如需詳細資訊，請參閱 [資產模型版本](model-active-version.md)。
1. 執行下列命令來擷取作用中模型定義：
```
aws iotsitewise describe-asset-model-composite-model \
--asset-model-composite-model-id composite-model-id \
--asset-model-id asset-model-id \
--asset-model-version ACTIVE
```
1. 如需詳細資訊，請參閱 [DescribeAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModelCompositeModel.html) 操作。
1. 建立名為 的檔案`update-custom-composite-model.json`，然後將上一個命令的回應複製到 檔案。
1. 從 中的 JSON 物件移除每個鍵/值對，下列欄位`update-custom-composite-model.json`除外：
+ `assetModelCompositeModelName`
+ `assetModelCompositeModelDescription` （如果有）
+ `assetModelCompositeModelProperties` （如果有）
1. 在 `update-custom-composite-model.json` 中，執行下列任何一項：
+ 變更 的值`assetModelCompositeModelName`。
+ 新增或移除 `assetModelCompositeModelDescription`，或變更其值。
+ 僅適用於內嵌自訂複合模型：變更、新增或移除 中的任何資產模型屬性`assetModelCompositeModelProperties`。
如需此檔案所需格式的詳細資訊，請參閱 [UpdateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModelCompositeModel.html) 的請求語法。
1. 執行下列命令，使用存放在 中的定義更新自訂複合模型`update-custom-composite-model.json`。以複合模型的 ID 取代 *composite-model-id*，並以其所在的資產模型 ID 取代 *asset-model-id*。
```
aws iotsitewise update-asset-model-composite-model \
--asset-model-composite-model-id composite-model-id \
--asset-model-id asset-model-id \
--cli-input-json file://update-custom-composite-model.json
```
**重要**
當多個使用者同時更新資產模型時，其他使用者可能會無意中覆寫使用者的變更。若要避免這種情況，您必須定義條件式更新請求。請參閱 [資產模型寫入的樂觀鎖定](opt-locking-for-model.md)。
# 資產模型寫入的樂觀鎖定
更新資產模型時，使用者會執行下列動作：
1. 讀取目前的資產模型定義。
1. 編輯具有必要變更的資產模型定義。
1. 使用新定義更新資產模型。
在有兩個使用者更新模型的情況下，可以執行下列動作：
+ 使用者 A 讀取資產模型 X 定義。
+ 使用者 B 讀取資產模型 X 定義並遞交變更，修改 X 的定義。
+ 使用者 A 會遞交並覆寫使用者 B 針對資產模型 X 所做的變更，而不驗證或整合使用者 B 的變更。
樂觀鎖定是 AWS IoT SiteWise 用來防止意外覆寫的機制，如上述案例所示。樂觀鎖定是確保更新或刪除資產模型目前版本的策略，與其目前版本相同 AWS IoT SiteWise。這可防止資產模型寫入被意外更新覆寫。
請依照下列步驟執行具有樂觀鎖定的資產模型寫入：
**Topics**
+ [使用樂觀鎖定執行資產模型寫入 （主控台）](#opt-locking-for-model-console)
+ [使用樂觀鎖定執行資產模型寫入 (AWS CLI)](#opt-locking-for-model-cli)
## 使用樂觀鎖定執行資產模型寫入 （主控台）
以下程序說明如何在主控台中對資產模型的作用中版本執行具有樂觀鎖定的資產模型寫入。
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Models (模型)**。
1. 選擇要更新的資產模型或元件模型。
1. 選擇**編輯**。
1. 在**編輯模型**頁面上進行變更。
1. 選擇**儲存**。
**注意**
有時候，當使用者開始編輯模型，並將所做的編輯儲存至模型時，就會發生一或多個成功的模型更新。
為了確保使用者不會意外覆寫新的成功更新，會拒絕使用者的寫入。主控台會停用**儲存**按鈕，並提示使用者重新整理**編輯模型**頁面。使用者必須再次更新模型的新作用中版本。使用者必須執行下列額外步驟：
1. 選擇 **Refresh (重新整理)**。
1. 再次遵循步驟 5 和 6。
## 使用樂觀鎖定執行資產模型寫入 (AWS CLI)
以下程序說明如何在 中執行具有樂觀鎖定的資產模型寫入 AWS CLI。
1. **擷取與目前模型定義相關聯的 ETag **
`ETag` 是針對資產模型的每個新表示所產生的唯一權杖。呼叫 [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html) API 以擷取目前的資產模型定義，並從回應`ETag`關聯。
在並行更新期間，使用者會執行成功的更新 （處於 `ACTIVE` 狀態的模型） 或失敗的更新 （處於 `FAILED` 狀態的模型）。為了確保使用者不會意外覆寫成功的更新，您必須從 擷取資產模型的作用中版本[資產模型版本](model-active-version.md)，並取得 `ETag`值。
執行以下命令：
```
aws iotsitewise describe-asset-model --asset-model-id asset-model-id \
--asset-model-version ACTIVE
```
回應會傳回下列結構：
```
{
"assetModelId": "String",
"assetModelArn": "String",
"assetModelName": "String",
...
"eTag": "String"
}
```
**注意**
您必須擷取資產模型的最新版本及其 ，`ETag`才不會覆寫任何更新。
1. **使用寫入條件執行 UPDATE 和 DELETE 操作**
下列資產模型 APIs支援樂觀鎖定：
+ [UpdateAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModel.html)
+ [DeleteAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DeleteAssetModel.html)
+ [CreateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAssetModelCompositeModel.html)
+ [UpdateAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateAssetModelCompositeModel.html)
+ [DeleteAssetModelCompositeModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DeleteAssetModelCompositeModel.html)
**注意**
以下案例使用 `UpdateAssetModel` API 做為參考。這些條件適用於上述所有操作。
以下案例根據並行控制需求描述不同的寫入條件：
+ 執行下列命令，以免覆寫任何成功的更新。自上次讀取作用中版本以來，新的作用中版本不得存在。`e-tag` 將 取代為在讀取作用中版本時使用的 API 操作中`ETag`傳回的 。
```
aws iotsitewise update-asset-model \
--asset-model-id asset-model-id \
--if-match e-tag \
--match-for-version-type ACTIVE \
--cli-input-json file://model-payload.json
```
+ 當模型建立失敗時，作用中版本尚不存在，因為它處於 `FAILED` 狀態。在遞交變更之前，仍然可以覆寫存在的新作用中版本。當您上次讀取期間沒有作用中版本時，請執行下列命令，以免覆寫新的作用中版本。
```
aws iotsitewise update-asset-model \
--asset-model-id asset-model-id \
--if-none-match "*" \
--match-for-version-type ACTIVE \
--cli-input-json file://model-payload.json
```
+ 執行下列命令，以避免覆寫任何成功或失敗的更新。此命令會定義寫入條件，以確保自您上次讀取最新版本以來，不會建立最新版本。`e-tag` 將 取代為在讀取作用中版本時使用的 API 操作中`ETag`傳回的 。
```
aws iotsitewise update-asset-model \
--asset-model-id asset-model-id \
--if-match eTag \
--match-for-version-type LATEST \
--cli-input-json file://model-payload.json
```
如果寫入條件評估為 `FALSE`，寫入請求會因 而失敗`PreconditionFailedException`。
# 在 中刪除資產和模型 AWS IoT SiteWise
您可以在完成資產、資產模型、元件模型和界面 AWS IoT SiteWise 時，從中刪除它們。刪除操作是非同步的，需要一些時間才能傳播 AWS IoT SiteWise。
**Topics**
+ [在 中刪除資產 AWS IoT SiteWise](delete-assets.md)
+ [在 中刪除資產模型、元件模型和界面 AWS IoT SiteWise](delete-asset-models.md)
# 在 中刪除資產 AWS IoT SiteWise
您可以使用 AWS IoT SiteWise 主控台或 API 來刪除環境中不再需要的資產。刪除資產模型也會刪除所有相關聯的資產和元件模型。不過，請務必注意，刪除資產或模型是永久動作，而且也會移除與已刪除資源相關聯的任何資料。刪除資產或模型之前，建議您檢閱任何可能受影響的相依性或整合，並確保您擁有任何重要資料的備份。
您必須先將資產與其子資產取消關聯，才能將其從其父資產中刪除。如需詳細資訊，請參閱[關聯和取消關聯資產](add-associated-assets.md)。如果您使用 AWS Command Line Interface (AWS CLI)，您可以使用 [ListAssociatedAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssociatedAssets.html) 操作來列出資產的子系。
刪除資產時，於變更傳播之前，其狀態會保持為 `DELETING`。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。刪除資產後，您無法查詢該資產。如果您這樣做，API 會傳回 HTTP 404 回應。
**重要**
AWS IoT SiteWise 會刪除已刪除資產的所有屬性資料。
**Topics**
+ [刪除資產 （主控台）](#delete-asset-console)
+ [刪除資產 (AWS CLI)](#delete-asset-cli)
## 刪除資產 （主控台）
您可以使用 AWS IoT SiteWise 主控台來刪除資產。
**刪除資產 (主控台)**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Assets (資產)**。
1. 選擇要刪除的資產。
**提示**
您可以選擇箭頭圖示來展開資產階層，以尋找您的資產。
1. 如果資產有任何 **Associated assets (關聯的資產)**，請刪除每個資產。您可以選擇資產的名稱，以導覽至其頁面，您可以在其中刪除資產。
1. 在資產頁面上，選擇 **Delete (刪除)**。
1. 在**刪除資產**對話方塊中，執行下列動作：
1. 輸入 **Delete** 以確認刪除。
1. 選擇 **刪除**。
## 刪除資產 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 來刪除資產。
使用 [DeleteAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DeleteAsset.html) 操作來刪除資產。指定下列參數：
+ `assetId` – 資產的 ID。這是 UUID 格式的實際 ID，`externalId:myExternalId`如果有的話，則為 。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
**刪除資產 (AWS CLI)**
1. 執行下列命令來列出資產的階層。將 *asset-id* 取代為資產的 ID 或外部 ID：
```
aws iotsitewise describe-asset --asset-id asset-id
```
此操作會傳回包含資產詳細資料的回應。回應包含具有下列結構的`assetHierarchies`清單：
```
{
...
"assetHierarchies": [
{
"id": "String",
"name": "String"
}
],
...
}
```
如需詳細資訊，請參閱 [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html) 操作。
1. 針對每個階層，執行下列命令來列出與該階層相關聯的資產子系。將 *asset-id* 取代為資產的 ID 或外部 ID，並將 *hierarchy-id* 取代為階層的 ID 或外部 ID。
```
aws iotsitewise list-associated-assets \
--asset-id asset-id \
--hierarchy-id hierarchy-id
```
如需詳細資訊，請參閱 [ListAssociatedAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssociatedAssets.html) 操作。
1. 執行下列命令來刪除每個關聯的資產，然後刪除資產。以*資產的 ID 或外部 ID 取代 asset-id*。
```
aws iotsitewise delete-asset --asset-id asset-id
```
# 在 中刪除資產模型、元件模型和界面 AWS IoT SiteWise
您可以使用 AWS IoT SiteWise 主控台或 API 來刪除資產模型、元件模型或界面。
您必須先刪除從資產模型建立的所有資產，才能刪除資產模型。您必須先將其與實作該界面的所有資產模型取消連結，才能刪除該界面。
當您刪除資產模型或界面時，其狀態為 ，`DELETING`直到變更傳播為止。如需詳細資訊，請參閱[資產和模型狀態](asset-and-model-states.md)。刪除資產模型或界面後，您無法查詢該資產模型或界面。如果您這樣做，API 會傳回 HTTP 404 回應。
**Topics**
+ [刪除資產模型、元件模型或界面 （主控台）](#delete-asset-model-console)
+ [刪除資產模型、元件模型或界面 (AWS CLI)](#delete-asset-model-cli)
## 刪除資產模型、元件模型或界面 （主控台）
您可以使用 AWS IoT SiteWise 主控台來刪除資產模型、元件模型或界面。
**Topics**
**刪除資產模型、元件模型或界面 （主控台）**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Models (模型)**。
1. 選擇要刪除的資產模型、元件模型或界面。
1. 如果刪除資產模型且具有任何**資產**，請刪除每個資產。選擇資產的名稱，以導覽至其頁面，您可以在其中刪除資產。如需詳細資訊，請參閱[刪除資產 （主控台）](delete-assets.md#delete-asset-console)。
1. 在模型頁面上，選擇 **Delete (刪除)**。
1. 在**刪除模型**對話方塊中，執行下列動作：
1. 輸入 **Delete** 以確認刪除。
1. 選擇 **刪除**。
## 刪除資產模型、元件模型或界面 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 來刪除資產模型、元件模型或界面。
使用 [DeleteAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DeleteAssetModel.html) 操作來刪除資產模型、元件模型或界面。指定下列參數：
+ `assetModelId` – 資產的 ID。這是 UUID 格式的實際 ID，`externalId:myExternalId`如果有的話，則為 。如需詳細資訊，請參閱《AWS IoT SiteWise 使用者指南》**中的 [參考具有外部 IDs物件](object-ids.md#external-id-references)。
**刪除資產模型 (AWS CLI)**
1. 執行以下命令來列出從模型建立的所有資產。以資產模型的 ID 或外部 ID 取代 *asset-model-id*。
```
aws iotsitewise list-assets --asset-model-id asset-model-id
```
如需詳細資訊，請參閱 [ListAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssets.html) 操作。
1. 如果上一個命令傳回模型中的任何資產，請刪除每個資產。如需詳細資訊，請參閱[刪除資產 (AWS CLI)](delete-assets.md#delete-asset-cli)。
1. 執行以下命令以刪除資產模型。以資產模型的 ID 或外部 ID 取代 *asset-model-id*。
```
aws iotsitewise delete-asset-model --asset-model-id asset-model-id
```
**重要**
若要避免刪除自上次讀取操作以來同時更新的資產模型，您必須定義條件式刪除請求。請參閱 [資產模型寫入的樂觀鎖定](opt-locking-for-model.md)。
# 使用資產和模型進行大量操作
若要使用大量資產或資產模型，請使用大量操作將資源大量匯入和匯出到不同的位置。例如，您可以建立資料檔案來定義 Amazon S3 儲存貯體中的資產或資產模型，並使用大量匯入來建立或更新它們 AWS IoT SiteWise。或者，如果您有大量的資產或資產模型 AWS IoT SiteWise，您可以將它們匯出至 Amazon S3。
**注意**
您可以透過在 AWS IoT TwinMaker API 中 AWS IoT SiteWise 呼叫 操作，在 中執行大量操作。您可以這樣做，而無需設定 AWS IoT TwinMaker 或建立 AWS IoT TwinMaker 工作區。您只需要一個 Amazon S3 儲存貯體，您可以在其中放置 AWS IoT SiteWise 內容。
**Topics**
+ [重要概念和術語](#bulk-operations-terminology)
+ [受支援的功能](#bulk-operations-functionality)
+ [大量操作先決條件](bulk-operations-prereqs.md)
+ [執行大量匯入任務](running-bulk-operations-import.md)
+ [執行大量匯出任務](running-bulk-operations-export.md)
+ [任務進度追蹤和錯誤處理](jobs-progress-error-handling.md)
+ [匯入中繼資料範例](bulk-operations-import-metadata-example.md)
+ [匯出中繼資料範例](bulk-operations-export-filter-examples.md)
+ [AWS IoT SiteWise 中繼資料傳輸任務結構描述](bulk-operations-schema.md)
## 重要概念和術語
AWS IoT SiteWise 大量匯入和匯出功能依賴下列概念和術語：
+ **匯入**：將資產或資產模型從 Amazon S3 儲存貯體中的檔案移至 的動作 AWS IoT SiteWise。
+ **匯出**：將資產或資產模型從 移至 Amazon S3 儲存貯 AWS IoT SiteWise 體的動作。
+ **來源**：您要從中移動內容的起始位置。
例如，Amazon S3 儲存貯體是匯入來源， AWS IoT SiteWise 也是匯出來源。
+ **目的地**：您要將內容移至其中的所需位置。
例如，Amazon S3 儲存貯體是匯出目的地，而 AWS IoT SiteWise 是匯入目的地。
+ **AWS IoT SiteWise 結構描述**：此結構描述用於從中匯入和匯出中繼資料 AWS IoT SiteWise。
+ **最上層資源：**您可以個別建立或更新 AWS IoT SiteWise 的資源，例如資產或資產模型。
+ **子資源：**頂層 AWS IoT SiteWise 資源中的巢狀資源。範例包括屬性、階層和複合模型。
+ **中繼資料**：成功匯入或匯出資源所需的金鑰資訊。中繼資料的範例是資產和資產模型的定義。
+ **metadataTransferJob**：執行 時建立的物件`CreateMetadataTransferJob`。
## 受支援的功能
本主題說明執行大量操作時可以執行的操作。大量操作支援下列功能：
+ **最上層資源建立：**當您匯入的資產或資產模型未定義 ID，或其 ID 與現有資源的 ID 不相符時，則會將其建立為新資源。
+ **最上層資源取代：**當您匯入 ID 與已存在的資產或資產模型相符時，它會取代現有的資源。
+ **子資源建立、取代或刪除：**當您的匯入取代資產或資產模型等頂層資源時，新定義會取代所有子資源，例如屬性、階層或複合模型。
例如，如果您在大量匯入期間更新資產模型，且更新版本定義了原始屬性上不存在的屬性，則會建立新的屬性。如果定義已存在的屬性，則會更新現有的屬性。如果更新的資產模型省略存在於原始的 屬性，則會刪除 屬性。
+ **不刪除頂層資源：**大量操作不會刪除資產或資產模型。大量操作只會建立或更新它們。
# 大量操作先決條件
本節說明大量操作先決條件，包括 AWS Identity and Access Management (IAM) 在 AWS 服務與本機機器之間交換資源的許可。開始大量操作之前，請先完成下列先決條件：
+ 建立 Amazon S3 儲存貯體以存放資源。如需使用 Amazon S3 的詳細資訊，請參閱[什麼是 Amazon S3？](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Welcome.html)
## IAM 許可
若要執行大量操作，您必須建立具有允許 Amazon S3 AWS IoT SiteWise與本機電腦之間 AWS 資源交換許可的 AWS Identity and Access Management (IAM) 政策。如需建立自訂 IAM 政策的詳細資訊，請參閱[建立 IAM 政策](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_create.html)。
若要執行大量操作，您需要下列政策。
### AWS IoT SiteWise 政策
此政策允許存取大量操作所需的 AWS IoT SiteWise API 動作：
```
{
"Sid": "SiteWiseApiAccess",
"Effect": "Allow",
"Action": [
"iotsitewise:CreateAsset",
"iotsitewise:CreateAssetModel",
"iotsitewise:UpdateAsset",
"iotsitewise:UpdateAssetModel",
"iotsitewise:UpdateAssetProperty",
"iotsitewise:ListAssets",
"iotsitewise:ListAssetModels",
"iotsitewise:ListAssetProperties",
"iotsitewise:ListAssetModelProperties",
"iotsitewise:ListAssociatedAssets",
"iotsitewise:DescribeAsset",
"iotsitewise:DescribeAssetModel",
"iotsitewise:DescribeAssetProperty",
"iotsitewise:AssociateAssets",
"iotsitewise:DisassociateAssets",
"iotsitewise:AssociateTimeSeriesToAssetProperty",
"iotsitewise:DisassociateTimeSeriesFromAssetProperty",
"iotsitewise:BatchPutAssetPropertyValue",
"iotsitewise:BatchGetAssetPropertyValue",
"iotsitewise:TagResource",
"iotsitewise:UntagResource",
"iotsitewise:ListTagsForResource",
"iotsitewise:CreateAssetModelCompositeModel",
"iotsitewise:UpdateAssetModelCompositeModel",
"iotsitewise:DescribeAssetModelCompositeModel",
"iotsitewise:DeleteAssetModelCompositeModel",
"iotsitewise:ListAssetModelCompositeModels",
"iotsitewise:ListCompositionRelationships",
"iotsitewise:DescribeAssetCompositeModel"
],
"Resource": "*"
}
```
### AWS IoT TwinMaker 政策
此政策允許存取您用來處理大量操作的 AWS IoT TwinMaker API 操作：
```
{
"Sid": "MetadataTransferJobApiAccess",
"Effect": "Allow",
"Action": [
"iottwinmaker:CreateMetadataTransferJob",
"iottwinmaker:CancelMetadataTransferJob",
"iottwinmaker:GetMetadataTransferJob",
"iottwinmaker:ListMetadataTransferJobs"
],
"Resource": "*"
}
```
### Amazon S3 政策
此政策提供 Amazon S3 儲存貯體的存取權，用於傳輸大量操作的中繼資料。
------
#### [ For a specific Amazon S3 bucket ]
如果您使用一個特定的儲存貯體來處理大量操作中繼資料，則此政策會提供該儲存貯體的存取權：
```
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:AbortMultipartUpload",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts"
],
"Resource": [
"arn:aws:s3:::bucket name",
"arn:aws:s3:::bucket name/*"
]
}
```
------
#### [ To allow any Amazon S3 bucket ]
如果您將使用許多不同的儲存貯體來使用大量操作中繼資料，則此政策可讓您存取任何儲存貯體：
```
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:AbortMultipartUpload",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts"
],
"Resource": "*"
}
```
------
如需對匯入和匯出操作進行故障診斷的資訊，請參閱 [對大量匯入和匯出進行故障診斷](troubleshooting-bulk.md)。
# 執行大量匯入任務
大量匯入是將中繼資料移至 AWS IoT SiteWise 工作區的動作。例如，大量匯入可以將中繼資料從本機檔案或 Amazon S3 儲存貯體中的檔案移至 AWS IoT SiteWise 工作區。
## 步驟 1：準備要匯入的檔案
下載 AWS IoT SiteWise 原生格式檔案以匯入資產和資產模型。如需詳細資訊，請參閱[AWS IoT SiteWise 中繼資料傳輸任務結構描述](bulk-operations-schema.md)。
## 步驟 2：將準備好的檔案上傳至 Amazon S3
將檔案上傳至 Amazon S3。如需詳細資訊，請參閱《[Amazon Simple Storage Service 使用者指南》中的將檔案上傳至 Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html#uploading-an-object-bucket)。 **
## 匯入中繼資料 （主控台）
您可以使用 AWS IoT SiteWise 主控台 大量匯入中繼資料。遵循 [步驟 1：準備要匯入的檔案](#preparing-import-file)和 [步驟 2：將準備好的檔案上傳至 Amazon S3](#uploading-import-file) 準備準備好匯入的檔案。
**將資料從 Amazon S3 匯入至 AWS IoT SiteWise 主控台**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 從導覽窗格中選擇**大量操作新增**。
1. 選擇**新增匯入**以開始匯入程序。
1. 在**匯入中繼資料**頁面上：
+ 選擇**瀏覽 Amazon S3** 以檢視 Amazon S3 儲存貯體和檔案。
+ 導覽至包含預備匯入檔案的 Amazon S3 儲存貯體。
+ 選取要匯入的檔案。
+ 檢閱選取的檔案，然後選擇**匯入**。
1. **SiteWise 中繼資料頁面上的大量操作**會在任務進度表中 AWS IoT SiteWise 主控台 顯示新建立的匯入任務。 ****
## 匯入中繼資料 (AWS CLI)
若要執行匯入動作，請使用下列程序：
**將資料從 Amazon S3 匯入至 AWS CLI**
1. 依照 建立中繼資料檔案，指定您要匯入的資源[AWS IoT SiteWise 中繼資料傳輸任務結構描述](bulk-operations-schema.md)。將此檔案存放在 Amazon S3 儲存貯體中。
如需要匯入的中繼資料檔案範例，請參閱 [匯入中繼資料範例](bulk-operations-import-metadata-example.md)。
1. 現在使用請求內文建立 JSON 檔案。請求內文會指定傳輸任務的來源和目的地。此檔案與上一個步驟的檔案分開。請務必將 Amazon S3 儲存貯體指定為來源和`iotsitewise`目的地。
下列範例顯示請求內文：
```
{
"metadataTransferJobId": "your-transfer-job-Id",
"sources": [{
"type": "s3",
"s3Configuration": {
"location": "arn:aws:s3:::amzn-s3-demo-bucket/your_import_metadata.json"
}
}],
"destination": {
"type": "iotsitewise"
}
}
```
1. 執行下列 AWS CLI 命令`CreateMetadataTransferJob`來叫用 。在此範例中，上一個步驟的請求內文檔案名為 `createMetadataTransferJobExport.json`。
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobImport.json
```
這將建立中繼資料傳輸任務，並開始轉移所選資源的程序。
# 執行大量匯出任務
大量匯出是將中繼資料從 AWS IoT SiteWise 工作區移至 Amazon S3 儲存貯體的動作。
當您將 AWS IoT SiteWise 內容大量匯出至 Amazon S3 時，您可以指定篩選條件來限制您要匯出的特定資產模型和資產。
篩選條件必須在 JSON 請求來源`iotSiteWiseConfiguration`區段的 區段中指定。
**注意**
您可以在請求中包含多個篩選條件。大量操作會匯出符合任何篩選條件的資產模型和資產。
如果您未提供任何篩選條件，大量操作會匯出所有資產模型和資產。
**Example 使用篩選條件請求內文**
```
{
"metadataTransferJobId": "your-transfer-job-id",
"sources": [
{
"type": "iotsitewise",
"iotSiteWiseConfiguration": {
"filters": [
{
"filterByAssetModel": {
"assetModelId": "asset model ID"
}
},
{
"filterByAssetModel": {
"assetModelId": "asset model ID",
"includeAssets": true
}
},
{
"filterByAssetModel": {
"assetModelId": "asset model ID",
"includeOffspring": true
}
}
]
}
}
],
"destination": {
"type": "s3",
"s3Configuration": {
"location": "arn:aws:s3:::amzn-s3-demo-bucket"
}
}
}
```
## 匯出中繼資料 （主控台）
下列程序說明主控台匯出動作：
**在 中建立匯出任務 AWS IoT SiteWise 主控台**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 從導覽窗格中選擇**大量操作新增**。
1. 選擇**新增匯出**以開始匯出程序。
1. 在**匯出中繼資料**頁面上：
+ 輸入匯出任務的名稱。這是用於 Amazon S3 儲存貯體中匯出檔案的名稱。
+ 選擇要匯出的資源，這會設定任務的篩選條件：
+ 匯出所有資產和資產模型。在資產和資產模型上使用篩選條件。
+ 匯出資產。篩選您的資產。
+ 選取要用於匯出篩選條件的資產。
+ （選用） 新增後代或相關聯的資產模型。
+ 匯出資產模型。篩選您的資產模型。
+ 選取要用於匯出篩選條件的資產模型。
+ （選用） 新增後代，或關聯的資產或兩者。
+ 選擇**下一步**。
+ 導覽至 Amazon S3 儲存貯體：
+ 選擇**瀏覽 Amazon S3** 以檢視 Amazon S3 儲存貯體和檔案。
+ 導覽至必須放置檔案的 Amazon S3 儲存貯體。
+ 選擇**下一步**。
+ 檢閱匯出任務，然後選擇**匯出**。
1. **SiteWise 中繼資料頁面上的大量操作**會在任務進度表中 AWS IoT SiteWise 主控台 顯示新建立的匯入任務。 ****
如需匯出中繼資料時使用篩選條件的不同方式，請參閱 [匯出中繼資料範例](bulk-operations-export-filter-examples.md)。
## 匯出中繼資料 (AWS CLI)
下列程序說明 AWS CLI 匯出動作：
**從 匯出資料 AWS IoT SiteWise 至 Amazon S3**
1. 使用請求內文建立 JSON 檔案。請求內文會指定傳輸任務的來源和目的地。下列範例顯示範例請求內文：
```
{
"metadataTransferJobId": "your-transfer-job-Id",
"sources": [{
"type": "iotsitewise"
}],
"destination": {
"type": "s3",
"s3Configuration": {
"location": "arn:aws:s3:::amzn-s3-demo-bucket"
}
}
}
```
請務必將 Amazon S3 儲存貯體指定為中繼資料傳輸任務的目的地。
**注意**
此範例會匯出所有資產模型和資產。若要限制匯出至特定資產模型或資產，您可以在請求內文中包含篩選條件。如需套用匯出篩選條件的詳細資訊，請參閱 [匯出中繼資料範例](bulk-operations-export-filter-examples.md)。
1. 儲存您的請求內文檔案以用於下一個步驟。在此範例中，檔案命名為 `createMetadataTransferJobExport.json`。
1. 執行下列 AWS CLI 命令`CreateMetadataTransferJob`來叫用 ：
```
aws iottwinmaker create-metadata-transfer-job --region us-east-1 \
--cli-input-json file://createMetadataTransferJobExport.json
```
以`createMetadataTransferJobExport.json`您自己的傳輸檔案名稱取代輸入 JSON 檔案。
# 任務進度追蹤和錯誤處理
大量程序任務需要時間來處理。每個任務都會按照 AWS IoT SiteWise 接收請求的順序進行處理。每個帳戶one-at-a-time。當任務完成時，佇列中的下一個 會自動開始處理。 會以非同步方式 AWS IoT SiteWise 解決任務，並在每個任務進行時更新其狀態。如果適用，每個任務都有一個狀態欄位，其中包含資源的狀態和錯誤訊息。
狀態可以是下列其中一個值：
+ `VALIDATING` – 驗證任務，包括提交的檔案格式及其內容。
+ `PENDING` – 任務在佇列中。您可以從主控台取消處於此狀態 AWS IoT SiteWise 的任務，但所有其他狀態會持續到結束為止。
+ `RUNNING` – 處理任務。它正在建立和更新匯入檔案定義的資源，或根據所選的匯出任務篩選條件匯出資源。如果取消，則不會刪除此任務匯入的任何資源。如需詳細資訊，請參閱[檢閱任務進度和詳細資訊 （主控台）](review-job-progress.md#review-job-progress-console)。
+ `CANCELLING` – 任務正在主動取消。
+ `ERROR` – 一或多個資源無法處理。如需詳細資訊，請參閱詳細的任務報告。如需詳細資訊，請參閱[檢查錯誤詳細資訊 （主控台）](inspect-errors.md#inspect-errors-console)。
+ `COMPLETED` – 任務已完成，沒有錯誤。
+ `CANCELLED` – 任務已取消且未排入佇列。如果您取消`RUNNING`任務，則不會從中刪除此任務在取消時已匯入的資源 AWS IoT SiteWise。
**Topics**
+ [任務進度追蹤](review-job-progress.md)
+ [檢查 的錯誤 AWS IoT SiteWise](inspect-errors.md)
# 任務進度追蹤
## 檢閱任務進度和詳細資訊 （主控台）
請參閱 [匯入中繼資料 （主控台）](running-bulk-operations-import.md#import-metadata-console)或 [匯出中繼資料 （主控台）](running-bulk-operations-export.md#export-metadata-console)以啟動大量任務。
**AWS IoT SiteWise 主控台中的任務進度概觀：**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 從導覽窗格中選擇**大量操作新增**。
1. AWS IoT SiteWise 主控台中的**任務進度**表會顯示大量操作任務的清單。
1. **任務類型**欄說明是匯出還是匯入任務。**匯入日期**欄會顯示任務開始的日期。
1. **狀態**欄會顯示任務的狀態。您可以選取任務以查看任務的詳細資訊。
1. 選取的任務會在成功時顯示**成功**，或在任務失敗時顯示失敗清單。每個資源類型也會顯示錯誤描述。
**AWS IoT SiteWise 主控台中的任務詳細資訊概觀：**
AWS IoT SiteWise 主控台中的**任務進度**表會顯示大量操作任務的清單。
1. 選擇任務以查看更多詳細資訊。
1. 對於**匯入**任務， `Data source ARN`代表匯入檔案的 Amazon S3 位置。
1. 對於**匯出**任務， `Data destination ARN`代表匯出後檔案的 Amazon S3 位置。
1. `Status` 和 `Status reason`提供目前任務的其他詳細資訊。如需詳細資訊，請參閱[任務進度追蹤和錯誤處理](jobs-progress-error-handling.md)。
1. `Queued position` 代表任務在程序佇列中的位置。一次處理一個任務。排入佇列的位置為 1，表示接下來將處理任務。
1. 任務詳細資訊頁面也會顯示任務進度計數。
1. 任務進度計數類型為：
1. `Total resources` – 表示轉移程序中資產的總計數。
1. `Succeeded` – 表示程序期間成功傳輸的資產計數。
1. `Failed` – 指出程序期間失敗的計數資產。
1. `Skipped` – 表示在程序期間略過的資產計數。
1. 任務狀態為 `PENDING`或 時`VALIDATING`， 會顯示所有任務進度計為 `–`。這表示正在評估任務進度計數。
1. 的任務狀態`RUNNING`會顯示`Total resources`計數，即提交處理的任務。詳細計數 (`Succeeded`、 `Failed`和 `Skipped`) 會套用至已處理的資源。詳細計數的總和小於`Total resources`計數，直到任務的狀態為 `COMPLETED`或 為止`ERROR`。
1. 如果任務的狀態為 `COMPLETED`或 `ERROR`，則`Total resources`計數等於詳細計數 (`Succeeded`、 `Failed`和 ) 的總和`Skipped`。
1. 如果任務的狀態為 `ERROR`，請檢查**任務失敗**資料表，以取得特定錯誤和失敗的詳細資訊。如需詳細資訊，請參閱[檢查錯誤詳細資訊 （主控台）](inspect-errors.md#inspect-errors-console)。
## 檢閱任務進度和詳細資訊 (AWS CLI)
啟動大量操作後，您可以使用下列 API 動作來檢查或更新其狀態：
+ 若要擷取特定任務的資訊，請使用 [ GetMetadataTransferJob](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetMetadataTransferJob.html) API 動作。
**使用 `GetMetadataTransferJob` API 擷取資訊：**
1. 建立並執行轉移任務。呼叫 `GetMetadataTransferJob` API。
**Example AWS CLI 命令：**
```
aws iottwinmaker get-metadata-transfer-job \
--metadata-transfer-job-id your_metadata_transfer_job_id \
--region your_region
```
1. `GetMetadataTransferJob` API 會傳回具有下列參數的`MetadataTransferJobProgress`物件：
+ **succeededCount** – 表示流程中成功傳輸的資產計數。
+ **failedCount** – 表示程序期間失敗的資產計數。
+ **skippedCount** – 表示程序期間略過的資產計數。
+ **totalCount** – 指出轉移程序中資產的總計數。
這些參數表示任務進度狀態。如果狀態為 `RUNNING`，則有助於追蹤仍在處理的資源數量。
如果您遇到結構描述驗證錯誤，或如果 **failedCount** 大於或等於 1，任務進度狀態會變成 `ERROR`。任務的完整錯誤報告會放置在 Amazon S3 儲存貯體中。如需詳細資訊，請參閱[檢查 的錯誤 AWS IoT SiteWise](inspect-errors.md)。
+ 若要列出目前的任務，請使用 [ListMetadataTransferJobs](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ListMetadataTransferJobs.html) API 動作。
使用 JSON 檔案，根據其目前狀態篩選傳回的任務。請參閱下列程序：
1. 若要指定要使用的篩選條件，請建立 AWS CLI 輸入 JSON 檔案。 想要使用：
```
{
"sourceType": "s3",
"destinationType": "iottwinmaker",
"filters": [{
"state": "COMPLETED"
}]
}
```
如需有效`state`值的清單，請參閱《 *AWS IoT TwinMaker API 參考指南*》中的 [ListMetadataTransferJobsFilter](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_ListMetadataTransferJobsFilter.html)。
1. 在下列 AWS CLI 範例命令中使用 JSON 檔案做為引數：
```
aws iottwinmaker list-metadata-transfer-job --region your_region \
--cli-input-json file://ListMetadataTransferJobsExample.json
```
+ 若要取消任務，請使用 [CancelMetadataTransferJob](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_CancelMetadataTransferJob.html) API 動作。此 API 會取消特定中繼資料傳輸任務，而不會影響任何已匯出或匯入的資源：
```
aws iottwinmaker cancel-metadata-transfer-job \
--region your_region \
--metadata-transfer-job-id job-to-cancel-id
```
# 檢查 的錯誤 AWS IoT SiteWise
## 檢查錯誤詳細資訊 （主控台）
**AWS IoT SiteWise 主控台中的錯誤詳細資訊：**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 如需大量操作任務的清單 AWS IoT SiteWise 主控台 ，請參閱 中的任務**進度**表。
1. 選取任務以檢視任務詳細資訊。
1. 如果任務的狀態為 `COMPLETED`或 `ERROR`，則`Total resources`計數等於詳細計數 (`Succeeded`、 `Failed`和 ) 的總和`Skipped`。
1. 如果任務的狀態為 `ERROR`，請檢查**任務失敗**資料表，以取得特定錯誤和失敗的詳細資訊。
1. **任務失敗**資料表會顯示任務報告中的內容。`Resource type` 欄位指出錯誤或失敗的位置，如下所示：
+ 例如， `Resource type` 欄位中`Bulk operations template`的驗證錯誤表示匯入範本和中繼資料結構描述檔案格式不相符。如需詳細資訊，請參閱[AWS IoT SiteWise 中繼資料傳輸任務結構描述](bulk-operations-schema.md)。
+ `Resource type` 欄位`Asset`失敗表示資產未建立，因為與另一個資產發生衝突。如需 AWS IoT SiteWise 資源[錯誤和衝突的相關資訊，請參閱常見](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/CommonErrors.html)錯誤。
## 檢查錯誤詳細資訊 (AWS CLI)
若要處理和診斷傳輸任務期間產生的錯誤，請參閱下列有關使用 `GetMetadataTransferJob` API 動作的程序：
1. 建立和執行傳輸任務之後，請呼叫 [GetMetadataTransferJob](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_GetMetadataTransferJob.html)：
```
aws iottwinmaker get-metadata-transfer-job \
--metadata-transfer-job-id your_metadata_transfer_job_id \
--region us-east-1
```
1. 一旦看到任務的狀態變成 `COMPLETED`，您就可以開始驗證任務的結果。
1. 當您呼叫 時`GetMetadataTransferJob`，它會傳回名為 的物件[https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_MetadataTransferJobProgress.html](https://docs.aws.amazon.com//iot-twinmaker/latest/apireference/API_MetadataTransferJobProgress.html)。
MetadataTransferJobProgress 物件包含下列參數：
+ **failedCount：**表示轉移程序期間失敗的資產計數。
+ **skippedCount：**表示轉移過程中略過的資產計數。
+ **succeededCount：**表示轉移程序期間成功的資產計數。
+ **totalCount：**表示轉移程序中涉及的資產總數。
1. 此外，API 呼叫會傳回 元素 `reportUrl`，其中包含預先簽章的 URL。如果您的轉移任務有任何需要進一步調查的問題，請造訪此 URL。
# 匯入中繼資料範例
本節說明如何建立中繼資料檔案，以使用單一大量匯入操作匯入資產模型和資產。
## 大量匯入的範例
您可以使用單一大量匯入操作來匯入許多資產模型和資產。下列範例示範如何建立中繼資料檔案來執行此操作。
在此範例案例中，您有各種工作站點，其中包含工作單元中的工業機器人。
此範例定義兩個資產模型：
+ `RobotModel1`：此資產模型代表您在工作站點中擁有的特定類型的機器人。機器人具有測量屬性 `Temperature`。
+ `WorkCell`：此資產模型代表其中一個工作站點內的機器人集合。資產模型會定義階層 `robotHierarchyOEM1`，以代表工作區包含機器人的關係。
此範例也會定義一些資產：
+ `WorkCell1`：您波士頓站點內的工作區
+ `RobotArm123456`：該工作區內的機器人
+ `RobotArm987654`：該工作區內的另一個機器人
下列 JSON 中繼資料檔案會定義這些資產模型和資產。使用此中繼資料執行大量匯入會在其中建立資產模型和資產 AWS IoT SiteWise，包括其階層關係。
### 用於匯入的中繼資料檔案
```
{
"assetModels": [
{
"assetModelExternalId": "Robot.OEM1.3536",
"assetModelName": "RobotModel1",
"assetModelProperties": [
{
"dataType": "DOUBLE",
"externalId": "Temperature",
"name": "Temperature",
"type": {
"measurement": {
"processingConfig": {
"forwardingConfig": {
"state": "ENABLED"
}
}
}
},
"unit": "fahrenheit"
}
]
},
{
"assetModelExternalId": "ISA95.WorkCell",
"assetModelName": "WorkCell",
"assetModelProperties": [],
"assetModelHierarchies": [
{
"externalId": "workCellHierarchyWithOEM1Robot",
"name": "robotHierarchyOEM1",
"childAssetModelExternalId": "Robot.OEM1.3536"
}
]
}
],
"assets": [
{
"assetExternalId": "Robot.OEM1.3536.123456",
"assetName": "RobotArm123456",
"assetModelExternalId": "Robot.OEM1.3536"
},
{
"assetExternalId": "Robot.OEM1.3536.987654",
"assetName": "RobotArm987654",
"assetModelExternalId": "Robot.OEM1.3536"
},
{
"assetExternalId": "BostonSite.Area1.Line1.WorkCell1",
"assetName": "WorkCell1",
"assetModelExternalId": "ISA95.WorkCell",
"assetHierarchies": [
{
"externalId": "workCellHierarchyWithOEM1Robot",
"childAssetExternalId": "Robot.OEM1.3536.123456"
},
{
"externalId": "workCellHierarchyWithOEM1Robot",
"childAssetExternalId": "Robot.OEM1.3536.987654"
}
]
}
]
}
```
## 模型和資產初始加入的範例
在此範例案例中，您有各種工作站點，其中包含公司中的工業機器人。
此範例定義多個資產模型：
+ `Sample_Enterprise` – 此資產模型代表網站所屬的公司。資產模型會定義階層 `Enterprise to Site`，以代表網站與企業的關係。
+ `Sample_Site` – 此資產模型代表公司內的製造站點。資產模型會定義階層 `Site to Line`，以代表行與網站的關係。
+ `Sample_Welding Line` – 此資產模型代表工作現場內的組裝線。資產模型會定義階層 `Line to Robot`，以代表機器人與線條的關係。
+ `Sample_Welding Robot` – 此資產模型代表您工作站點中特定類型的機器人。
此範例也會根據資產模型定義資產。
+ `Sample_AnyCompany Motor` – 此資產是從`Sample_Enterprise`資產模型建立的。
+ `Sample_Chicago` – 此資產是從`Sample_Site`資產模型建立的。
+ `Sample_Welding Line 1` – 此資產是從`Sample_Welding Line`資產模型建立的。
+ `Sample_Welding Robot 1` – 此資產是從`Sample_Welding Robot`資產模型建立的。
+ `Sample_Welding Robot 2` – 此資產是從`Sample_Welding Robot`資產模型建立的。
下列 JSON 中繼資料檔案會定義這些資產模型和資產。使用此中繼資料執行大量匯入會在其中建立資產模型和資產 AWS IoT SiteWise，包括其階層關係。
### 用於加入資產和模型以進行匯入的 JSON 檔案
```
{
"assetModels": [
{
"assetModelExternalId": "External_Id_Welding_Robot",
"assetModelName": "Sample_Welding Robot",
"assetModelProperties": [
{
"dataType": "STRING",
"externalId": "External_Id_Welding_Robot_Serial_Number",
"name": "Serial Number",
"type": {
"attribute": {
"defaultValue": "-"
}
},
"unit": "-"
},
{
"dataType": "DOUBLE",
"externalId": "External_Id_Welding_Robot_Cycle_Count",
"name": "CycleCount",
"type": {
"measurement": {}
},
"unit": "EA"
},
{
"dataType": "DOUBLE",
"externalId": "External_Id_Welding_Robot_Joint_1_Current",
"name": "Joint 1 Current",
"type": {
"measurement": {}
},
"unit": "Amps"
},
{
"dataType": "DOUBLE",
"externalId": "External_Id_Welding_Robot_Joint_1_Max_Current",
"name": "Max Joint 1 Current",
"type": {
"metric": {
"expression": "max(joint1current)",
"variables": [
{
"name": "joint1current",
"value": {
"propertyExternalId": "External_Id_Welding_Robot_Joint_1_Current"
}
}
],
"window": {
"tumbling": {
"interval": "5m"
}
}
}
},
"unit": "Amps"
}
]
},
{
"assetModelExternalId": "External_Id_Welding_Line",
"assetModelName": "Sample_Welding Line",
"assetModelProperties": [
{
"dataType": "DOUBLE",
"externalId": "External_Id_Welding_Line_Availability",
"name": "Availability",
"type": {
"measurement": {}
},
"unit": "%"
}
],
"assetModelHierarchies": [
{
"externalId": "External_Id_Welding_Line_TO_Robot",
"name": "Line to Robot",
"childAssetModelExternalId": "External_Id_Welding_Robot"
}
]
},
{
"assetModelExternalId": "External_Id_Site",
"assetModelName": "Sample_Site",
"assetModelProperties": [
{
"dataType": "STRING",
"externalId": "External_Id_Site_Street_Address",
"name": "Street Address",
"type": {
"attribute": {
"defaultValue": "-"
}
},
"unit": "-"
}
],
"assetModelHierarchies": [
{
"externalId": "External_Id_Site_TO_Line",
"name": "Site to Line",
"childAssetModelExternalId": "External_Id_Welding_Line"
}
]
},
{
"assetModelExternalId": "External_Id_Enterprise",
"assetModelName": "Sample_Enterprise",
"assetModelProperties": [
{
"dataType": "STRING",
"name": "Company Name",
"externalId": "External_Id_Enterprise_Company_Name",
"type": {
"attribute": {
"defaultValue": "-"
}
},
"unit": "-"
}
],
"assetModelHierarchies": [
{
"externalId": "External_Id_Enterprise_TO_Site",
"name": "Enterprise to Site",
"childAssetModelExternalId": "External_Id_Site"
}
]
}
],
"assets": [
{
"assetExternalId": "External_Id_Welding_Robot_1",
"assetName": "Sample_Welding Robot 1",
"assetModelExternalId": "External_Id_Welding_Robot",
"assetProperties": [
{
"externalId": "External_Id_Welding_Robot_Serial_Number",
"attributeValue": "S1000"
},
{
"externalId": "External_Id_Welding_Robot_Cycle_Count",
"alias": "AnyCompany/Chicago/Welding Line/S1000/Count"
},
{
"externalId": "External_Id_Welding_Robot_Joint_1_Current",
"alias": "AnyCompany/Chicago/Welding Line/S1000/1/Current"
}
]
},
{
"assetExternalId": "External_Id_Welding_Robot_2",
"assetName": "Sample_Welding Robot 2",
"assetModelExternalId": "External_Id_Welding_Robot",
"assetProperties": [
{
"externalId": "External_Id_Welding_Robot_Serial_Number",
"attributeValue": "S2000"
},
{
"externalId": "External_Id_Welding_Robot_Cycle_Count",
"alias": "AnyCompany/Chicago/Welding Line/S2000/Count"
},
{
"externalId": "External_Id_Welding_Robot_Joint_1_Current",
"alias": "AnyCompany/Chicago/Welding Line/S2000/1/Current"
}
]
},
{
"assetExternalId": "External_Id_Welding_Line_1",
"assetName": "Sample_Welding Line 1",
"assetModelExternalId": "External_Id_Welding_Line",
"assetProperties": [
{
"externalId": "External_Id_Welding_Line_Availability",
"alias": "AnyCompany/Chicago/Welding Line/Availability"
}
],
"assetHierarchies": [
{
"externalId": "External_Id_Welding_Line_TO_Robot",
"childAssetExternalId": "External_Id_Welding_Robot_1"
},
{
"externalId": "External_Id_Welding_Line_TO_Robot",
"childAssetExternalId": "External_Id_Welding_Robot_2"
}
]
},
{
"assetExternalId": "External_Id_Site_Chicago",
"assetName": "Sample_Chicago",
"assetModelExternalId": "External_Id_Site",
"assetHierarchies": [
{
"externalId": "External_Id_Site_TO_Line",
"childAssetExternalId": "External_Id_Welding_Line_1"
}
]
},
{
"assetExternalId": "External_Id_Enterprise_AnyCompany",
"assetName": "Sample_AnyEnterprise Motor",
"assetModelExternalId": "External_Id_Enterprise",
"assetHierarchies": [
{
"externalId": "External_Id_Enterprise_TO_Site",
"childAssetExternalId": "External_Id_Site_Chicago"
}
]
}
]
}
```
下列螢幕擷取畫面是在您執行先前程式碼範例 AWS IoT SiteWise 主控台 後，顯示於 中的模型。
![\[AWS IoT SiteWise 具有資產和資產模型的模型。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/import-example-asset.png)
下列螢幕擷取畫面是在您執行先前程式碼範例 AWS IoT SiteWise 主控台 後，顯示於 中的模型、資產和階層。
![\[AWS IoT SiteWise 具有資產、資產模型和階層的模型。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/hierarchy-example-import.png)
## 加入其他資產的範例
此範例定義要匯入至您帳戶中現有資產模型的其他資產：
+ `Sample_Welding Line 2` – 此資產是從`Sample_Welding Line`資產模型建立的。
+ `Sample_Welding Robot 3`– 此資產是從`Sample_Welding Robot`資產模型建立的。
+ `Sample_Welding Robot 4`– 此資產是從`Sample_Welding Robot`資產模型建立的。
若要建立此範例的初始資產，請參閱 [模型和資產初始加入的範例](#example-scenario1)。
下列 JSON 中繼資料檔案會定義這些資產模型和資產。使用此中繼資料執行大量匯入會在其中建立資產模型和資產 AWS IoT SiteWise，包括其階層關係。
### 加入其他資產的 JSON 檔案
```
{
"assets": [
{
"assetExternalId": "External_Id_Welding_Robot_3",
"assetName": "Sample_Welding Robot 3",
"assetModelExternalId": "External_Id_Welding_Robot",
"assetProperties": [
{
"externalId": "External_Id_Welding_Robot_Serial_Number",
"attributeValue": "S3000"
},
{
"externalId": "External_Id_Welding_Robot_Cycle_Count",
"alias": "AnyCompany/Chicago/Welding Line/S3000/Count"
},
{
"externalId": "External_Id_Welding_Robot_Joint_1_Current",
"alias": "AnyCompany/Chicago/Welding Line/S3000/1/Current"
}
]
},
{
"assetExternalId": "External_Id_Welding_Robot_4",
"assetName": "Sample_Welding Robot 4",
"assetModelExternalId": "External_Id_Welding_Robot",
"assetProperties": [
{
"externalId": "External_Id_Welding_Robot_Serial_Number",
"attributeValue": "S4000"
},
{
"externalId": "External_Id_Welding_Robot_Cycle_Count",
"alias": "AnyCompany/Chicago/Welding Line/S4000/Count"
},
{
"externalId": "External_Id_Welding_Robot_Joint_1_Current",
"alias": "AnyCompany/Chicago/Welding Line/S4000/1/Current"
}
]
},
{
"assetExternalId": "External_Id_Welding_Line_1",
"assetName": "Sample_Welding Line 1",
"assetModelExternalId": "External_Id_Welding_Line",
"assetHierarchies": [
{
"externalId": "External_Id_Welding_Line_TO_Robot",
"childAssetExternalId": "External_Id_Welding_Robot_1"
},
{
"externalId": "External_Id_Welding_Line_TO_Robot",
"childAssetExternalId": "External_Id_Welding_Robot_2"
},
{
"externalId": "External_Id_Welding_Line_TO_Robot",
"childAssetExternalId": "External_Id_Welding_Robot_3"
}
]
},
{
"assetExternalId": "External_Id_Welding_Line_2",
"assetName": "Sample_Welding Line 2",
"assetModelExternalId": "External_Id_Welding_Line",
"assetHierarchies": [
{
"externalId": "External_Id_Welding_Line_TO_Robot",
"childAssetExternalId": "External_Id_Welding_Robot_4"
}
]
},
{
"assetExternalId": "External_Id_Site_Chicago",
"assetName": "Sample_Chicago",
"assetModelExternalId": "External_Id_Site",
"assetHierarchies": [
{
"externalId": "External_Id_Site_TO_Line",
"childAssetExternalId": "External_Id_Welding_Line_1"
},
{
"externalId": "External_Id_Site_TO_Line",
"childAssetExternalId": "External_Id_Welding_Line_2"
}
]
}
]
}
```
下列螢幕擷取畫面是在您執行先前程式碼範例 AWS IoT SiteWise 主控台 後，顯示於 中的模型、資產和階層。
![\[AWS IoT SiteWise 具有資產和資產模型的模型。\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/images/additional-assets-import.png)
## 加入新屬性的範例
此範例定義現有資產模型的新屬性。請參閱 [加入其他資產的範例](#example-scenario2)以加入其他資產和模型。
+ `Joint 1 Temperature` – 此屬性會新增至`Sample_Welding Robot`資產模型。這個新屬性也會傳播到從資產模型建立的每個`Sample_Welding Robot`資產。
若要將新屬性新增至現有資產模型，請參閱下列 JSON 中繼資料檔案範例。如 JSON 所示，整個現有的`Sample_Welding Robot`資產模型定義必須與新的 屬性一起提供。如果未提供現有定義中的整個屬性清單， 會 AWS IoT SiteWise 刪除省略的屬性。
### 加入新屬性的 JSON 檔案
此範例`Joint 1 Temperature`會將新的屬性新增至資產模型。
```
{
"assetModels": [
{
"assetModelExternalId": "External_Id_Welding_Robot",
"assetModelName": "Sample_Welding Robot",
"assetModelProperties": [
{
"dataType": "STRING",
"externalId": "External_Id_Welding_Robot_Serial_Number",
"name": "Serial Number",
"type": {
"attribute": {
"defaultValue": "-"
}
},
"unit": "-"
},
{
"dataType": "DOUBLE",
"externalId": "External_Id_Welding_Robot_Cycle_Count",
"name": "CycleCount",
"type": {
"measurement": {}
},
"unit": "EA"
},
{
"dataType": "DOUBLE",
"externalId": "External_Id_Welding_Robot_Joint_1_Current",
"name": "Joint 1 Current",
"type": {
"measurement": {}
},
"unit": "Amps"
},
{
"dataType": "DOUBLE",
"externalId": "External_Id_Welding_Robot_Joint_1_Max_Current",
"name": "Max Joint 1 Current",
"type": {
"metric": {
"expression": "max(joint1current)",
"variables": [
{
"name": "joint1current",
"value": {
"propertyExternalId": "External_Id_Welding_Robot_Joint_1_Current"
}
}
],
"window": {
"tumbling": {
"interval": "5m"
}
}
}
},
"unit": "Amps"
},
{
"dataType": "DOUBLE",
"externalId": "External_Id_Welding_Robot_Joint_1_Temperature",
"name": "Joint 1 Temperature",
"type": {
"measurement": {}
},
"unit": "degC"
}
]
}
]
}
```
## 管理資料串流的範例
此範例顯示管理與資產屬性相關聯之資料串流的兩種方式。重新命名資產屬性別名時，資產屬性資料串流中目前存放的歷史資料有兩個選項。
+ 選項一：保留目前的資料串流，並單獨重新命名別名，以便使用新的別名存取歷史資料。
在 JSON 中繼資料檔案範例中，具有 ID 的資產屬性會將其別名`External_Id_Welding_Robot_Cycle_Count`變更為 `AnyCompany/Chicago/Welding Line/S3000/Count-Updated`。此資產屬性的歷史資料在此變更後保持不變。
+ 選項二 – 將新的資料串流指派給資產屬性，該屬性可透過新的別名存取。舊資料串流及其歷史資料仍可使用舊別名存取，但不會與任何資產屬性相關聯。
在 JSON 中繼資料檔案範例中，具有 ID 的資產屬性會將其別名`External_Id_Welding_Robot_Joint_1_Current`變更為 `AnyCompany/Chicago/Welding Line/S4999/1/Current`。此時會出現額外的值，`retainDataOnAliasChange`並將 設定為 `False`。使用此設定，原始資料串流會與資產屬性取消關聯，並建立新的資料串流，其中包含沒有歷史資料。
若要使用原始歷史資料存取舊資料串流，請在 中 AWS Console Home，前往*資料串流*頁面並搜尋舊別名 `AnyCompany/Chicago/Welding Line/S3000/1/Current`。
### 更新屬性別名的 JSON 檔案
```
{
"assetExternalId": "External_Id_Welding_Robot_3",
"assetName": "Sample_Welding Robot 3",
"assetModelExternalId": "External_Id_Welding_Robot",
"assetProperties": [
{
"externalId": "External_Id_Welding_Robot_Serial_Number",
"attributeValue": "S3000"
},
{
"externalId": "External_Id_Welding_Robot_Cycle_Count",
"alias": "AnyCompany/Chicago/Welding Line/S3000/Count-Updated"
},
{
"externalId": "External_Id_Welding_Robot_Joint_1_Current",
"alias": "AnyCompany/Chicago/Welding Line/S4999/1/Current",
"retainDataOnAliasChange": "FALSE"
}
]
}
```
# 匯出中繼資料範例
當您將 AWS IoT SiteWise 內容大量匯出至 Amazon S3 時，您可以指定*篩選條件*來限制您要匯出的特定資產模型和資產。
您可以在請求內文 `iotSiteWiseConfiguration`區段的 `sources`區段中指定篩選條件。
**注意**
您可以包含多個篩選條件。大量操作將匯出符合任何篩選條件的任何資產模型或資產。
如果您未提供任何篩選條件，則操作會匯出所有資產模型和資產。
```
{
"metadataTransferJobId": "your-transfer-job-id",
"sources": [{
"type": "iotsitewise",
"iotSiteWiseConfiguration": {
"filters": [{
list of filters
}]
}
}],
"destination": {
"type": "s3",
"s3Configuration": {
"location": "arn:aws:s3:::amzn-s3-demo-bucket"
}
}
}
```
## 依資產模型篩選
您可以篩選特定的資產模型。您也可以包含使用該模型的所有資產，或其階層中的所有資產模型。您無法同時包含資產和階層。
如需有關階層的詳細資訊，請參閱[定義資產模型階層](define-asset-hierarchies.md)。
------
#### [ Asset model ]
此篩選條件包含指定的資產模型：
```
"filterByAssetModel": {
"assetModelId": "asset model ID"
}
```
------
#### [ Asset model and its assets ]
此篩選條件包含指定的資產模型，以及使用該資產模型的所有資產：
```
"filterByAssetModel": {
"assetModelId": "asset model ID",
"includeAssets": true
}
```
------
#### [ Asset model and its hierarchy ]
此篩選條件包含指定的資產模型，以及其階層中所有相關聯的資產模型：
```
"filterByAssetModel": {
"assetModelId": "asset model ID",
"includeOffspring": true
}
```
------
## 依資產篩選
您可以篩選特定資產。您也可以在其階層中包含其資產模型或所有相關資產。您無法同時包含資產模型和階層。
如需有關階層的詳細資訊，請參閱[定義資產模型階層](define-asset-hierarchies.md)。
------
#### [ Asset ]
此篩選條件包含指定的資產：
```
"filterByAsset": {
"assetId": "asset ID"
}
```
------
#### [ Asset and its asset model ]
此篩選條件包含指定的資產，以及其使用的資產模型：
```
"filterByAsset": {
"assetId": "asset ID",
"includeAssetModel": true
}
```
------
#### [ Asset and its hierarchy ]
此篩選條件包含指定的資產，以及其階層中所有相關聯的資產：
```
"filterByAsset": {
"assetId": "asset ID",
"includeOffspring": true
}
```
------
# AWS IoT SiteWise 中繼資料傳輸任務結構描述
執行您自己的大量匯入和匯出操作時，請使用 AWS IoT SiteWise 中繼資料傳輸任務結構描述進行參考：
```
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "IoTSiteWise",
"description": "Metadata transfer job resource schema for IoTSiteWise",
"definitions": {
"Name": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"pattern": "[^\\u0000-\\u001F\\u007F]+"
},
"Description": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"pattern": "[^\\u0000-\\u001F\\u007F]+"
},
"ID": {
"type": "string",
"minLength": 36,
"maxLength": 36,
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"ExternalId": {
"type": "string",
"minLength": 2,
"maxLength": 128,
"pattern": "[a-zA-Z0-9_][a-zA-Z_\\-0-9.:]*[a-zA-Z0-9_]+"
},
"AttributeValue": {
"description": "The value of the property attribute.",
"type": "string",
"pattern": "[^\\u0000-\\u001F\\u007F]+"
},
"PropertyUnit": {
"description": "The unit of measure (such as Newtons or RPM) of the asset property.",
"type": "string",
"minLength": 1,
"maxLength": 256,
"pattern": "[^\\u0000-\\u001F\\u007F]+"
},
"PropertyAlias": {
"description": "The property alias that identifies the property.",
"type": "string",
"minLength": 1,
"maxLength": 1000,
"pattern": "[^\\u0000-\\u001F\\u007F]+"
},
"AssetProperty": {
"description": "The asset property's definition, alias, unit, and notification state.",
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"externalId"
]
}
],
"properties": {
"id": {
"description": "The ID of the asset property.",
"$ref": "#/definitions/ID"
},
"externalId": {
"description": "The ExternalID of the asset property.",
"$ref": "#/definitions/ExternalId"
},
"alias": {
"$ref": "#/definitions/PropertyAlias"
},
"unit": {
"$ref": "#/definitions/PropertyUnit"
},
"attributeValue": {
"$ref": "#/definitions/AttributeValue"
},
"retainDataOnAliasChange": {
"type": "string",
"default": "TRUE",
"enum": [
"TRUE",
"FALSE"
]
},
"propertyNotificationState": {
"description": "The MQTT notification state (ENABLED or DISABLED) for this asset property.",
"type": "string",
"enum": [
"ENABLED",
"DISABLED"
]
}
}
},
"AssetHierarchy": {
"description": "A hierarchy specifies allowed parent/child asset relationships.",
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"id",
"childAssetId"
]
},
{
"required": [
"externalId",
"childAssetId"
]
},
{
"required": [
"id",
"childAssetExternalId"
]
},
{
"required": [
"externalId",
"childAssetExternalId"
]
}
],
"properties": {
"id": {
"description": "The ID of a hierarchy in the parent asset's model.",
"$ref": "#/definitions/ID"
},
"externalId": {
"description": "The ExternalID of a hierarchy in the parent asset's model.",
"$ref": "#/definitions/ExternalId"
},
"childAssetId": {
"description": "The ID of the child asset to be associated.",
"$ref": "#/definitions/ID"
},
"childAssetExternalId": {
"description": "The ExternalID of the child asset to be associated.",
"$ref": "#/definitions/ExternalId"
}
}
},
"Tag": {
"type": "object",
"additionalProperties": false,
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"AssetModelType": {
"type": "string",
"default": null,
"enum": [
"ASSET_MODEL",
"COMPONENT_MODEL"
]
},
"AssetModelCompositeModel": {
"description": "Contains a composite model definition in an asset model. This composite model definition is applied to all assets created from the asset model.",
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"externalId"
]
}
],
"required": [
"name",
"type"
],
"properties": {
"id": {
"description": "The ID of the asset model composite model.",
"$ref": "#/definitions/ID"
},
"externalId": {
"description": "The ExternalID of the asset model composite model.",
"$ref": "#/definitions/ExternalId"
},
"parentId": {
"description": "The ID of the parent asset model composite model.",
"$ref": "#/definitions/ID"
},
"parentExternalId": {
"description": "The ExternalID of the parent asset model composite model.",
"$ref": "#/definitions/ExternalId"
},
"composedAssetModelId": {
"description": "The ID of the composed asset model.",
"$ref": "#/definitions/ID"
},
"composedAssetModelExternalId": {
"description": "The ExternalID of the composed asset model.",
"$ref": "#/definitions/ExternalId"
},
"description": {
"description": "A description for the asset composite model.",
"$ref": "#/definitions/Description"
},
"name": {
"description": "A unique, friendly name for the asset composite model.",
"$ref": "#/definitions/Name"
},
"type": {
"description": "The type of the composite model. For alarm composite models, this type is AWS/ALARM.",
"$ref": "#/definitions/Name"
},
"properties": {
"description": "The property definitions of the asset model.",
"type": "array",
"items": {
"$ref": "#/definitions/AssetModelProperty"
}
}
}
},
"AssetModelProperty": {
"description": "Contains information about an asset model property.",
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"externalId"
]
}
],
"required": [
"name",
"dataType",
"type"
],
"properties": {
"id": {
"description": "The ID of the asset model property.",
"$ref": "#/definitions/ID"
},
"externalId": {
"description": "The ExternalID of the asset model property.",
"$ref": "#/definitions/ExternalId"
},
"name": {
"description": "The name of the asset model property.",
"$ref": "#/definitions/Name"
},
"dataType": {
"description": "The data type of the asset model property.",
"$ref": "#/definitions/DataType"
},
"dataTypeSpec": {
"description": "The data type of the structure for this property.",
"$ref": "#/definitions/Name"
},
"unit": {
"description": "The unit of the asset model property, such as Newtons or RPM.",
"type": "string",
"minLength": 1,
"maxLength": 256,
"pattern": "[^\\u0000-\\u001F\\u007F]+"
},
"type": {
"description": "The property type",
"$ref": "#/definitions/PropertyType"
}
}
},
"DataType": {
"type": "string",
"enum": [
"STRING",
"INTEGER",
"DOUBLE",
"BOOLEAN",
"STRUCT"
]
},
"PropertyType": {
"description": "Contains a property type, which can be one of attribute, measurement, metric, or transform.",
"type": "object",
"additionalProperties": false,
"properties": {
"attribute": {
"$ref": "#/definitions/Attribute"
},
"transform": {
"$ref": "#/definitions/Transform"
},
"metric": {
"$ref": "#/definitions/Metric"
},
"measurement": {
"$ref": "#/definitions/Measurement"
}
}
},
"Attribute": {
"type": "object",
"additionalProperties": false,
"properties": {
"defaultValue": {
"type": "string",
"pattern": "[^\\u0000-\\u001F\\u007F]+"
}
}
},
"Transform": {
"type": "object",
"additionalProperties": false,
"required": [
"expression",
"variables"
],
"properties": {
"expression": {
"description": "The mathematical expression that defines the transformation function.",
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"variables": {
"description": "The list of variables used in the expression.",
"type": "array",
"items": {
"$ref": "#/definitions/ExpressionVariable"
}
},
"processingConfig": {
"$ref": "#/definitions/TransformProcessingConfig"
}
}
},
"TransformProcessingConfig": {
"description": "The processing configuration for the given transform property.",
"type": "object",
"additionalProperties": false,
"required": [
"computeLocation"
],
"properties": {
"computeLocation": {
"description": "The compute location for the given transform property.",
"$ref": "#/definitions/ComputeLocation"
},
"forwardingConfig": {
"description": "The forwarding configuration for a given property.",
"$ref": "#/definitions/ForwardingConfig"
}
}
},
"Metric": {
"type": "object",
"additionalProperties": false,
"required": [
"expression",
"variables",
"window"
],
"properties": {
"expression": {
"description": "The mathematical expression that defines the metric aggregation function.",
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"variables": {
"description": "The list of variables used in the expression.",
"type": "array",
"items": {
"$ref": "#/definitions/ExpressionVariable"
}
},
"window": {
"description": "The window (time interval) over which AWS IoT SiteWise computes the metric's aggregation expression",
"$ref": "#/definitions/MetricWindow"
},
"processingConfig": {
"$ref": "#/definitions/MetricProcessingConfig"
}
}
},
"MetricProcessingConfig": {
"description": "The processing configuration for the metric.",
"type": "object",
"additionalProperties": false,
"required": [
"computeLocation"
],
"properties": {
"computeLocation": {
"description": "The compute location for the given metric property.",
"$ref": "#/definitions/ComputeLocation"
}
}
},
"ComputeLocation": {
"type": "string",
"enum": [
"EDGE",
"CLOUD"
]
},
"ForwardingConfig": {
"type": "object",
"additionalProperties": false,
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"ENABLED",
"DISABLED"
]
}
}
},
"MetricWindow": {
"description": "Contains a time interval window used for data aggregate computations (for example, average, sum, count, and so on).",
"type": "object",
"additionalProperties": false,
"properties": {
"tumbling": {
"description": "The tumbling time interval window.",
"type": "object",
"additionalProperties": false,
"required": [
"interval"
],
"properties": {
"interval": {
"description": "The time interval for the tumbling window.",
"type": "string",
"minLength": 2,
"maxLength": 23
},
"offset": {
"description": "The offset for the tumbling window.",
"type": "string",
"minLength": 2,
"maxLength": 25
}
}
}
}
},
"ExpressionVariable": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"value"
],
"properties": {
"name": {
"description": "The friendly name of the variable to be used in the expression.",
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$"
},
"value": {
"description": "The variable that identifies an asset property from which to use values.",
"$ref": "#/definitions/VariableValue"
}
}
},
"VariableValue": {
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"propertyId"
]
},
{
"required": [
"propertyExternalId"
]
}
],
"properties": {
"propertyId": {
"$ref": "#/definitions/ID"
},
"propertyExternalId": {
"$ref": "#/definitions/ExternalId"
},
"hierarchyId": {
"$ref": "#/definitions/ID"
},
"hierarchyExternalId": {
"$ref": "#/definitions/ExternalId"
}
}
},
"Measurement": {
"type": "object",
"additionalProperties": false,
"properties": {
"processingConfig": {
"$ref": "#/definitions/MeasurementProcessingConfig"
}
}
},
"MeasurementProcessingConfig": {
"type": "object",
"additionalProperties": false,
"required": [
"forwardingConfig"
],
"properties": {
"forwardingConfig": {
"description": "The forwarding configuration for the given measurement property.",
"$ref": "#/definitions/ForwardingConfig"
}
}
},
"AssetModelHierarchy": {
"description": "Contains information about an asset model hierarchy.",
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"id",
"childAssetModelId"
]
},
{
"required": [
"id",
"childAssetModelExternalId"
]
},
{
"required": [
"externalId",
"childAssetModelId"
]
},
{
"required": [
"externalId",
"childAssetModelExternalId"
]
}
],
"required": [
"name"
],
"properties": {
"id": {
"description": "The ID of the asset model hierarchy.",
"$ref": "#/definitions/ID"
},
"externalId": {
"description": "The ExternalID of the asset model hierarchy.",
"$ref": "#/definitions/ExternalId"
},
"name": {
"description": "The name of the asset model hierarchy.",
"$ref": "#/definitions/Name"
},
"childAssetModelId": {
"description": "The ID of the asset model. All assets in this hierarchy must be instances of the child AssetModelId asset model.",
"$ref": "#/definitions/ID"
},
"childAssetModelExternalId": {
"description": "The ExternalID of the asset model. All assets in this hierarchy must be instances of the child AssetModelId asset model.",
"$ref": "#/definitions/ExternalId"
}
}
},
"AssetModel": {
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"assetModelId"
]
},
{
"required": [
"assetModelExternalId"
]
}
],
"required": [
"assetModelName"
],
"properties": {
"assetModelId": {
"description": "The ID of the asset model.",
"$ref": "#/definitions/ID"
},
"assetModelExternalId": {
"description": "The ID of the asset model.",
"$ref": "#/definitions/ExternalId"
},
"assetModelName": {
"description": "A unique, friendly name for the asset model.",
"$ref": "#/definitions/Name"
},
"assetModelDescription": {
"description": "A description for the asset model.",
"$ref": "#/definitions/Description"
},
"assetModelType": {
"description": "The type of the asset model.",
"$ref": "#/definitions/AssetModelType"
},
"assetModelProperties": {
"description": "The property definitions of the asset model.",
"type": "array",
"items": {
"$ref": "#/definitions/AssetModelProperty"
}
},
"assetModelCompositeModels": {
"description": "The composite asset models that are part of this asset model. Composite asset models are asset models that contain specific properties.",
"type": "array",
"items": {
"$ref": "#/definitions/AssetModelCompositeModel"
}
},
"assetModelHierarchies": {
"description": "The hierarchy definitions of the asset model. Each hierarchy specifies an asset model whose assets can be children of any other assets created from this asset model.",
"type": "array",
"items": {
"$ref": "#/definitions/AssetModelHierarchy"
}
},
"tags": {
"description": "A list of key-value pairs that contain metadata for the asset model.",
"type": "array",
"items": {
"$ref": "#/definitions/Tag"
}
}
}
},
"Asset": {
"type": "object",
"additionalProperties": false,
"anyOf": [
{
"required": [
"assetId",
"assetModelId"
]
},
{
"required": [
"assetExternalId",
"assetModelId"
]
},
{
"required": [
"assetId",
"assetModelExternalId"
]
},
{
"required": [
"assetExternalId",
"assetModelExternalId"
]
}
],
"required": [
"assetName"
],
"properties": {
"assetId": {
"description": "The ID of the asset",
"$ref": "#/definitions/ID"
},
"assetExternalId": {
"description": "The external ID of the asset",
"$ref": "#/definitions/ExternalId"
},
"assetModelId": {
"description": "The ID of the asset model from which to create the asset.",
"$ref": "#/definitions/ID"
},
"assetModelExternalId": {
"description": "The ExternalID of the asset model from which to create the asset.",
"$ref": "#/definitions/ExternalId"
},
"assetName": {
"description": "A unique, friendly name for the asset.",
"$ref": "#/definitions/Name"
},
"assetDescription": {
"description": "A description for the asset",
"$ref": "#/definitions/Description"
},
"assetProperties": {
"type": "array",
"items": {
"$ref": "#/definitions/AssetProperty"
}
},
"assetHierarchies": {
"type": "array",
"items": {
"$ref": "#/definitions/AssetHierarchy"
}
},
"tags": {
"description": "A list of key-value pairs that contain metadata for the asset.",
"type": "array",
"uniqueItems": false,
"items": {
"$ref": "#/definitions/Tag"
}
}
}
}
},
"additionalProperties": false,
"properties": {
"assetModels": {
"type": "array",
"uniqueItems": false,
"items": {
"$ref": "#/definitions/AssetModel"
}
},
"assets": {
"type": "array",
"uniqueItems": false,
"items": {
"$ref": "#/definitions/Asset"
}
}
}
}
```