本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 從 查詢資料 AWS IoT SiteWise
您可以使用 AWS IoT SiteWise API 操作來查詢資產屬性的目前值、歷史值和在特定時間間隔的彙總。 AWS IoT SiteWise 提供多個查詢界面，以滿足不同的整合需求：
+ **直接 API 操作** - 針對特定資料擷取需求的簡單目標 API 呼叫
+ **類似 SQL 的查詢語言** - 用於複雜資料分析的強大、彈性查詢
+ **ODBC 驅動程式** - 與商業智慧工具和應用程式的整合
使用這些查詢功能來：
+ 取得操作資料的即時洞見
+ 分析歷史趨勢和模式
+ 計算工業資產的效能指標
+ 將 IoT 資料與企業系統和儀表板整合
+ 建置利用工業資料的自訂應用程式
例如，您可以探索具有特定屬性值的所有資產、建立資料的自訂表示法，或開發與儲存在 AWS IoT SiteWise 資產中的工業資料整合的軟體解決方案。您也可以即時在 AWS IoT SiteWise Monitor中探索您的資產資料。若要了解如何設定 SiteWise Monitor，請參閱 [使用 監控資料 AWS IoT SiteWise Monitor](monitor-data.md)。
本節所述的操作會傳回包含時間戳記、品質、值 (TQV) 結構的屬性值物件：
+ `timestamp` 包含目前的 Unix epoch 時間，以秒為單位，具有奈秒偏移。
+ `quality` 包含下列其中一個字串，指出資料點的品質：
+ `GOOD` – 資料不會受到任何問題的影響。
+ `BAD` – 資料會受到感應器故障等問題的影響。
+ `UNCERTAIN` – 資料受到感應器不準確等問題的影響。
+ `value` 包含下列其中一個欄位，取決於 屬性的類型：
+ `booleanValue`
+ `doubleValue`
+ `integerValue`
+ `stringValue`
+ `nullValue`
**Topics**
+ [查詢 中的目前資產屬性值 AWS IoT SiteWise](current-values.md)
+ [在 中查詢歷史資產屬性值 AWS IoT SiteWise](historical-values.md)
+ [在 中查詢資產屬性彙總 AWS IoT SiteWise](aggregates.md)
+ [AWS IoT SiteWise 查詢語言](sql.md)
+ [查詢最佳化](query-optimize.md)
+ [ODBC](query-ODBC.md)
# 查詢 中的目前資產屬性值 AWS IoT SiteWise
本教學課程顯示取得資產屬性目前值的兩種方式。您可以使用 AWS IoT SiteWise 主控台或在 AWS Command Line Interface () 中使用 API AWS CLI。
**Topics**
+ [查詢資產屬性的目前值 （主控台）](#query-current-value-console)
+ [查詢資產屬性的目前值 (AWS CLI)](#query-current-value-cli)
## 查詢資產屬性的目前值 （主控台）
您可以使用 AWS IoT SiteWise 主控台來檢視資產屬性的目前值。
**取得資產屬性的目前值 (主控台)**
1. 導覽至 [AWS IoT SiteWise 主控台](https://console.aws.amazon.com/iotsitewise/)。
1. 在導覽窗格中，選擇 **Assets (資產)**。
1. 選擇具有要查詢之屬性的資產。
1. 選擇箭頭圖示以展開資產階層來尋找您的資產。
1. 選擇屬性類型的標籤。例如，選擇 **Measurements (衡量值)** 以檢視衡量值屬性的目前值。
1. 尋找要檢視的屬性。目前值會顯示在 **Latest value (最新值)** 欄中。
## 查詢資產屬性的目前值 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 來查詢資產屬性的目前值。
使用 [GetAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValue.html) 操作來查詢資產屬性的目前值。
若要識別資產屬性，請指定下列其中一項：
+ 資料傳送到的資產屬性`propertyId`的 `assetId`和 。
+ `propertyAlias`，這是資料串流別名 （例如 `/company/windfarm/3/turbine/7/temperature`)。若要使用這個選項，您必須先設定您的資產屬性別名。若要設定屬性別名，請參閱 [管理 的資料串流 AWS IoT SiteWise](manage-data-streams.md)。
**若要取得資產屬性的目前值 (AWS CLI)**
+ 執行下列命令以取得資產屬性的目前值。將 *asset-id* 取代為資產的 ID，並將 *property-id* 取代為屬性的 ID。
```
aws iotsitewise get-asset-property-value \
--asset-id asset-id \
--property-id property-id
```
該操作會傳回回應，其中包含以下格式的屬性目前 TQV。
```
{
"propertyValue": {
"value": {
"booleanValue": Boolean,
"doubleValue": Number,
"integerValue": Number,
"stringValue": "String",
"nullValue": {
"valueType": "String"
}
},
"timestamp": {
"timeInSeconds": Number,
"offsetInNanos": Number
},
"quality": "String"
}
}
```
# 在 中查詢歷史資產屬性值 AWS IoT SiteWise
您可以使用 AWS IoT SiteWise API [GetAssetPropertyValueHistory](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValueHistory.html) 操作來查詢資產屬性的歷史值。
若要識別資產屬性，請指定下列其中一項：
+ 資料傳送到的資產屬性`propertyId`的 `assetId`和 。
+ `propertyAlias`，這是資料串流別名 （例如 `/company/windfarm/3/turbine/7/temperature`)。若要使用這個選項，您必須先設定您的資產屬性別名。若要設定屬性別名，請參閱 [管理 的資料串流 AWS IoT SiteWise](manage-data-streams.md)。
傳遞下列參數以精簡您的結果：
+ `startDate` – 查詢歷史資料範圍的專屬起點，以秒為單位，以 Unix epoch 時間表示。
+ `endDate` – 查詢歷史資料範圍的包含端點，以秒為單位，以 Unix epoch 時間表示。
+ `maxResults` – 在單一請求中傳回的結果數目上限。預設為`20`結果。
+ `nextToken` – 從此操作的上一個呼叫傳回的分頁字符。
+ `timeOrdering` – 要套用至傳回值的排序： `ASCENDING`或 `DESCENDING`。
+ `qualities` – 篩選結果的品質：`GOOD`、 `BAD`或 `UNCERTAIN`。
**查詢資產屬性的值歷史記錄 (AWS CLI)**
1. 執行下列命令以取得資產屬性的值歷程記錄。此命令會在特定的 10 分鐘間隔內查詢屬性的歷程記錄。將 *asset-id* 取代為資產的 ID，並將 *property-id* 取代為屬性的 ID。將日期參數取代為要查詢的間隔。
```
aws iotsitewise get-asset-property-value-history \
--asset-id asset-id \
--property-id property-id \
--start-date 1575216000 \
--end-date 1575216600
```
操作會傳回回應，其中包含 屬性的歷史 TQVs格式如下：
```
{
"assetPropertyValueHistory": [
{
"value": {
"booleanValue": Boolean,
"doubleValue": Number,
"integerValue": Number,
"stringValue": "String",
"nullValue": {
"valueType": "String"
}
},
"timestamp": {
"timeInSeconds": Number,
"offsetInNanos": Number
},
"quality": "String"
}
],
"nextToken": "String"
}
```
1. 如果存在更多值項目，您可以從 `nextToken` 欄位將分頁字符傳遞給 [GetAssetPropertyValueHistory](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValueHistory.html) 操作的後續呼叫。
# 在 中查詢資產屬性彙總 AWS IoT SiteWise
AWS IoT SiteWise 會自動計算彙總的資產屬性值，這是在多個時間間隔內計算的一組基本指標。 會為您的資產屬性 AWS IoT SiteWise 計算下列每分鐘、每小時和每天彙總：
+ **平均值** – 屬性值在時間間隔內的平均值 （平均值）。
+ **count** – 屬性在時間間隔內的資料點數目。
+ **maximum** – 時間間隔內屬性值的最大值。
+ minimum**** – 時間間隔內屬性值的最小值。
+ **標準差** – 屬性值在時間間隔內的標準差。
+ sum**** – 屬性在時間間隔內的值總和。
對於非數值屬性，例如字串和布林值， 只會 AWS IoT SiteWise 計算計數彙總。
您也可以為您的資產資料計算自訂指標。使用指標屬性，您可以定義 操作特有的彙總。指標屬性提供未針對 AWS IoT SiteWise API 預先計算的額外彙總函數和時間間隔。如需詳細資訊，請參閱[從屬性和其他資產彙總資料 （指標）](metrics.md)。
**Topics**
+ [彙總資產屬性 (API)](#aggregates-api)
+ [彙總資產屬性 (AWS CLI)](#aggregates-cli)
## 彙總資產屬性 (API)
使用 AWS IoT SiteWise API 取得資產屬性的彙總。
使用 [GetAssetPropertyAggregates](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyAggregates.html) 操作來查詢資產屬性的彙總。
若要識別資產屬性，請指定下列其中一項：
+ 資料傳送到的資產屬性`propertyId`的 `assetId`和 。
+ `propertyAlias`，這是資料串流別名 （例如 `/company/windfarm/3/turbine/7/temperature`)。若要使用這個選項，您必須先設定您的資產屬性別名。若要設定屬性別名，請參閱 [管理 的資料串流 AWS IoT SiteWise](manage-data-streams.md)。
您必須傳遞下列必要參數：
+ `aggregateTypes` – 要擷取的彙總清單。您可以指定 `AVERAGE`、`COUNT`、`MAXIMUM`、`MINIMUM`、`STANDARD_DEVIATION` 和 `SUM` 中的任何一個。
+ `resolution` – 擷取指標的時間間隔：`1m`(1 分鐘）、`15m`(15 分鐘）、`1h`(1 小時） 或 `1d`(1 天）。
+ `startDate` – 查詢歷史資料範圍的專屬起點，以秒為單位，以 Unix epoch 時間表示。
+ `endDate` – 查詢歷史資料範圍的包含端點，以秒為單位，以 Unix epoch 時間表示。
您也可以傳遞下列任一參數來精簡結果：
+ `maxResults` – 在單一請求中傳回的結果數目上限。預設為`20`結果。
+ `nextToken` – 從此操作的上一個呼叫傳回的分頁字符。
+ `timeOrdering` – 要套用至傳回值的排序： `ASCENDING`或 `DESCENDING`。
+ `qualities` – 篩選結果的品質：`GOOD`、 `BAD`或 `UNCERTAIN`。
**注意**
[GetAssetPropertyAggregates](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyAggregates.html) 操作會傳回與本區段所述操作以外之不同格式的 TQV。`value` 結構包含適用於該請求中每個 `aggregateTypes` 的欄位。`timestamp` 包含彙總發生的時間，以 Unix epoch 時間的秒計算。
## 彙總資產屬性 (AWS CLI)
**查詢資產屬性的彙總 (AWS CLI)**
1. 執行下列命令以取得資產屬性的彙總。此命令會查詢特定 1 小時間隔的 1 小時解析度的平均值和總和。將 *asset-id* 取代為資產的 ID，並將 *property-id* 取代為屬性的 ID。使用要查詢的彙總和間隔取代參數。
```
aws iotsitewise get-asset-property-aggregates \
--asset-id asset-id \
--property-id property-id \
--start-date 1575216000 \
--end-date 1575219600 \
--aggregate-types AVERAGE SUM \
--resolution 1h
```
此操作會傳回回應，其中包含以下格式的屬性歷史 TQV。回應只包括請求的彙總。
```
{
"aggregatedValues": [
{
"timestamp": Number,
"quality": "String",
"value": {
"average": Number,
"count": Number,
"maximum": Number,
"minimum": Number,
"standardDeviation": Number,
"sum": Number
}
}
],
"nextToken": "String"
}
```
1. 如果存在更多值項目，您可以將分頁字符從 `nextToken` 欄位傳遞至後續呼叫 [GetAssetPropertyAggregates](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyAggregates.html) 操作。
**注意**
如果您的查詢範圍包含`null`值 TQVs，請參閱 [AssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetPropertyValue.html) API。計數以外的所有統計資料都會產生`null`回應，類似於字串 TQVs統計資料。如果您的查詢範圍包含`Double.NaN`雙重類型 TQVs則計數以外的所有計算都會產生 `Double.NaN`。
# AWS IoT SiteWise 查詢語言
透過 AWS IoT SiteWise 資料擷取 [ExecuteQuery](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ExecuteQuery.html) API 操作，您可以從下列項目擷取宣告性結構定義的相關資訊，以及與其相關聯的時間序列資料：
+ 模型
+ 資產
+ 測量
+ 指標
+ 轉換
+ 彙總
這可以在單一 API 請求中使用 SQL，例如查詢陳述式。
**注意**
此功能適用於所有 AWS IoT SiteWise 可用區域，但 AWS GovCloud （美國西部）、加拿大 （中部）、中國 （北京） 和美國東部 （俄亥俄） 除外。
**Topics**
+ [的查詢語言參考 AWS IoT SiteWise](query-reference.md)
# 的查詢語言參考 AWS IoT SiteWise
AWS IoT SiteWise 支援豐富的查詢語言以使用您的資料。下列主題說明可用的資料類型、運算子、函數和建構。
請參閱 [查詢範例](sql-examples.md) 以使用查詢語言撰寫 AWS IoT SiteWise 查詢。
**Topics**
+ [查詢參考檢視](query-reference-views.md)
+ [支援的資料類型](supported-data-types.md)
+ [支援的子句](supported-clauses.md)
+ [邏輯運算子](sql-supported-logical.md)
+ [比較運算子](sql-supported-comparision.md)
+ [SQL 函數](sql-functions.md)
+ [查詢範例](sql-examples.md)
# 查詢參考檢視
本節提供的資訊可協助您了解 中的檢視 AWS IoT SiteWise，例如程序中繼資料和遙測資料。
下表提供檢視的檢視名稱和說明：
**資料模型**
| **檢視名稱** | **檢視說明** |
| --- | --- |
| 資產 | 包含資產和模型衍生的相關資訊。 |
| asset\$1property | 包含資產屬性結構的相關資訊。 |
| raw\$1time\$1series | 包含時間序列的歷史資料。 |
| latest\$1value\$1time\$1series | 包含時間序列的最新值。 |
| precomputed\$1aggregates | 包含自動計算的彙總資產屬性值。它們是一組在多個時間間隔內計算的基本指標。 |
下列檢視會列出每個檢視的資料欄名稱和資料類型。
**檢視：資產**
| **資料欄名稱** | **datatype** |
| --- | --- |
| asset\$1id | string |
| asset\$1name | string |
| asset\$1description | string |
| asset\$1model\$1id | string |
| parent\$1asset\$1id | string |
| asset\$1external\$1id | string |
| asset\$1model\$1external\$1id | string |
| hierarchy\$1id | string |
**檢視：asset\$1property**
| **資料欄名稱** | **datatype** |
| --- | --- |
| asset\$1id | string |
| property\$1id | string |
| property\$1name | string |
| property\$1alias | string |
| property\$1external\$1id | string |
| asset\$1composite\$1model\$1id | string |
| property\$1type | string |
| property\$1data\$1type | string |
| int\$1attribute\$1value | integer |
| double\$1attribute\$1value | double |
| boolean\$1attribute\$1value | boolean |
| string\$1attribute\$1value | string |
**檢視：raw\$1time\$1series**
| **資料欄名稱** | **datatype** |
| --- | --- |
| asset\$1id | string |
| property\$1id | string |
| property\$1alias | string |
| event\$1timestamp | timestamp |
| quality | string |
| boolean\$1value | boolean |
| int\$1value | integer |
| double\$1value | double |
| string\$1value | string |
**檢視：latest\$1value\$1time\$1series**
| **資料欄名稱** | **datatype** |
| --- | --- |
| asset\$1id | string |
| property\$1id | string |
| property\$1alias | string |
| event\$1timestamp | timestamp |
| quality | string |
| boolean\$1value | boolean |
| int\$1value | integer |
| double\$1value | double |
| string\$1value | string |
**檢視：precomputed\$1aggregates**
| **資料欄名稱** | **datatype** |
| --- | --- |
| asset\$1id | string |
| property\$1id | string |
| property\$1alias | string |
| event\$1timestamp | timestamp |
| quality | string |
| 解析度 | string |
| sum\$1value | double |
| count\$1value | integer |
| average\$1value | double |
| maximum\$1value | double |
| minimum\$1value | double |
| stdev\$1value | double |
# 支援的資料類型
AWS IoT SiteWise 查詢語言支援下列資料類型。
**純量值**
| **資料類型** | **Description** |
| --- | --- |
| `STRING` | 長度上限為 1024 位元組的字串。 |
| `INTEGER` | 帶正負號的 32 位元整數，範圍為 `-2,147,483,648 to 2,147,483,647` 。 |
| `DOUBLE` | 範圍為 `–10^100 to 10^100`或`IEEE 754`雙精度`Nan`的浮點數。 |
| `BOOLEAN` | `true` 或 `false` |
| `TIMESTAMP` | 符合 ISO-8601 的時間戳記： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/supported-data-types.html) |
**注意**
`Null`：指出`true`缺少已定義資料的布林值。
**Example**
`TIMESTAMP` 值範例：
```
TIMESTAMP '2025-12-21 23:59:59.999Z'
TIMESTAMP '2025-12-21 23:59:59+23:59'
'2025-12-21 23:59:59'
'2025-12-21T23:59:59.123+11:11'
```
**注意**
雙精確度資料並不精確。某些值不會完全轉換，而且由於精確度有限， 不會代表所有實際數字。查詢中的浮點資料可能與內部表示的值不同。如果輸入數字的精確度太高，則值會四捨五入。
# 支援的子句
`SELECT` 陳述式用於從一或多個檢視擷取資料。 AWS IoT SiteWise 支援 `JOIN`和 `INNER JOIN`操作。
檢視會以明確的語法聯結，或在 `JOIN` `FROM`子句中以逗號分隔的符號聯結。
**Example**
一般`SELECT`陳述式：
```
SELECT expression [, ...]
[ FROM table_name AS alias [, ...] ]
[ WHERE condition ]
[ GROUP BY expression [, ...] ]
[ HAVING condition ]
[ ORDER BY expression [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ] [, ...] ]
[ LIMIT expression ]
```
**Example**
具有不同子句的 SELECT 陳述式：
```
SELECT
a.asset_name,
a.asset_id,
p.property_type,
p.property_data_type,
p.string_attribute_value,
p.property_name
FROM asset a, asset_property p
WHERE a.asset_description LIKE '%description%'
AND p.property_type IN ('attribute', 'metric')
OR p.property_id IN (
SELECT property_id
FROM raw_time_series
WHERE event_timestamp BETWEEN TIMESTAMP '2025-01-01 00:00:00' AND TIMESTAMP '2025-01-02 00:00:00'
GROUP BY asset_id, property_id
HAVING COUNT(*) > 100
)
GROUP BY p.property_type
HAVING COUNT(*) > 5
ORDER BY a.asset_name ASC
LIMIT 20;
```
**注意**
隱含 `JOIN`會結合兩個或多個不同的資料表，而不根據 AWS IoT SiteWise內部結構描述使用`JOIN`關鍵字。這相當於`JOIN`在中繼資料`asset_id`和原始資料表之間的 和 `property_id` 欄位上執行 。此模式可讓 SiteWise 在從原始資料表擷取資料時，利用查詢中任何指定的中繼資料篩選條件，進而減少掃描的整體資料。
**Example 查詢的 ：**
```
SELECT a.asset_name, p.property_name, r.event_timestamp
FROM asset a, asset_property p, raw_time_series r
WHERE a.asset_name='my_asset' AND p.property_name='my_property'
```
上述範例只會從屬於指定中繼資料名稱的資產屬性掃描資料。
**Example 的最佳化程度低於上述查詢：**
```
SELECT a.asset_name, p.property_name, r.event_timestamp
FROM asset a
JOIN asset_property p ON a.asset_id=p.asset_id
JOIN raw_time_series r ON p.asset_id=r.asset_id AND p.property_id=r.property_id
WHERE a.asset_name='my_asset' AND p.property_name='my_property'
```
每個子句及其描述的說明如下所示：
| **子句** | **Signature** | **Description** |
| --- | --- | --- |
| `LIMIT` | LIMIT { count } | 此子句會將結果集限制為指定的資料列數。您可以使用 `LIMIT`搭配或不搭配 `ORDER BY`和 `OFFSET`子句。 `LIMIT` 僅適用於來自 【0，2147483647】 的非負整數。 |
| `ORDER BY` | ORDER BY expression
[ ASC | DESC ]
[ NULLS FIRST | NULLS LAST ]
| `ORDER BY` 子句會排序查詢的結果集。 在 `ORDER BY`子句的彙總中參考選取的資料欄時，請使用資料欄的順序索引，而不是名稱或別名。 SELECT AVG(t.double_value)
FROM latest_value_time_series t
GROUP BY t.asset_id
ORDER BY 1
|
| `GROUP BY` | GROUP BY expression [, ...]
| `GROUP BY` 子句識別查詢的分組資料欄。它與彙總表達式搭配使用。 |
| `HAVING` | HAVING boolean-expression
| `HAVING` 子句會篩選 GROUP BY 子句建立的群組資料列。 |
| `SUB SELECT` | SELECT column1, column2
FROM table1
WHERE column3 IN (SELECT column4 FROM table2);
| 內嵌在另一個`SELECT`陳述式中的`SELECT`陳述式。 |
| `JOIN` | SELECT column1, column2
FROM table1 JOIN table2
ON table1.column1 = table2.column1;
|
| `INNER JOIN` | SELECT columns
FROM table1
INNER JOIN table2 ON table1.column = table2.column;
| 會`INNER JOIN`傳回兩個資料表中符合聯結條件的所有資料列。 |
| `UNION` | query
{ UNION [ ALL ] }
another_query
| `UNION` 運算子會計算其兩個引數的集合聯集，自動從結果集中移除重複的記錄。 |
# 邏輯運算子
AWS IoT SiteWise 支援下列邏輯運算子。
| **運算子** | **Signature** | **Description** |
| --- | --- | --- |
| `AND` | a `AND` b | `TRUE` 如果兩個值都是 true |
| `OR` | a `OR` b | `TRUE` 如果一個值為 true |
| `NOT` | `NOT` 表達式 | `TRUE` 如果表達式為 false，且`FALSE`如果表達式為 true |
| `IN` | x `IN`表達式 | `TRUE` 如果表達式中的值 |
| `BETWEEN` | `BETWEEN` a `AND` b | `TRUE` 如果值介於上限和下限之間，且包含兩個限制 |
| `LIKE` | `LIKE` 模式 | `TRUE` 如果值處於模式 `LIKE` 支援萬用字元。如需範例，請參閱以下： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-supported-logical.html) |
所有邏輯運算子的範例：
| **函數** | **範例** |
| --- | --- |
| AND | SELECT a.asset_name
FROM asset AS a, latest_value_time_series AS t
WHERE t.int_value > 30 AND t.event_timestamp > TIMESTAMP '2025-05-15 00:00:01'
|
| 或 | SELECT a.asset_name
FROM asset AS a
WHERE a.asset_name like 'abc' OR a.asset_name like 'pqr'
|
| NOT | SELECT ma.asset_id AS a_id
FROM asset AS ma
WHERE (ma.asset_id NOT LIKE 'some%patterna%' escape 'a') AND ma.asset_id='abc'
|
| IN | SELECT a.asset_name
FROM asset AS a
WHERE a.asset_name IN ('abc', 'pqr')
|
| BETWEEN | SELECT asset_id, int_value, event_timestamp AS i_v
FROM raw_time_series
WHERE event_timestamp BETWEEN TIMESTAMP '2025-04-15 00:00:01' and TIMESTAMP '2025-05-15 00:00:01'
|
| LIKE | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-supported-logical.html) |
# 比較運算子
AWS IoT SiteWise 支援下列比較運算子。所有比較操作都可用於內建資料類型，並評估為布林值。
**邏輯運算子**
| **運算子** | **Description** |
| --- | --- |
| `<` | Less than |
| `>` | Greater than |
| `<=` | 小於或等於 |
| `>=` | 大於或等於 |
| `=` | Equals |
| `!=` | 不等於 |
**非數值的比較操作事實資料表**
| **類型** | **類型 >= x** | **類型 <= x** | **類型 > x** | **類型 < x** | **類型 = x** | **輸入 ！= x** |
| --- | --- | --- | --- | --- | --- | --- |
| `NULL` | `FALSE` | `FALSE` | `FALSE` | `FALSE` | `FALSE` | `TRUE` |
有些述詞的行為類似於運算子，但具有特殊語法。請參閱以下內容：
**比較述詞**
| **運算子** | **Description** |
| --- | --- |
| `IS NULL` | 測試值是否為 `NULL`。 |
| `IS NOT NULL` | 測試值是否不是 `NULL`。 |
## NaN 運算子
`NaN`或 'Not a Number' 是浮點算術中的特殊值。以下是`NaN`比較清單及其運作方式。
+ `NaN` 值必須括在單引號內。例如，'`NaN`'。
+ `NaN` 值會被視為彼此相等。
+ `NaN` 大於其他數值。
+ 在彙總函數中`STDDEV()`，例如 `AVG()`、 和 `SUM()`，如果任何值為 `NaN`，則結果為 `NaN`。
+ 在彙總函數中，例如 `MAX()`和 `MIN()`，`NaN`值會包含在計算中。
**NaN 值比較**
| **Comparison** (比較) | **結果** |
| --- | --- |
| `'NaN' ≥ x` | True |
| `'NaN' ≤ x` | 如果 x 等於 NaN，則為 true，否則為 False |
| `'NaN' > x` | 如果 x 等於 NaN，則為 False，否則為 True |
| `'NaN' < x` | False |
| `'NaN' = x` | 如果 x 等於 NaN，則為 true，否則為 False |
| `'NaN' != x` | 如果 x 等於 NaN，則為 False，否則為 True |
# SQL 函數
支援的函數群組包括：
**Topics**
+ [純量函數](sql-functions-scalar.md)
+ [彙總函數](sql-functions-aggregated.md)
# 純量函數
純量函數會取得一或多個輸入值，並傳回單一輸出值。它們廣泛用於 SQL （結構化查詢語言） 以進行資料處理和擷取，從而提高資料處理任務的效率。
**Topics**
+ [Null 資料函數](sql-functions-null.md)
+ [字串函數](sql-functions-string.md)
+ [數學函數](sql-functions-math.md)
+ [日期時間函數](sql-functions-date.md)
+ [類型轉換函數](sql-functions-type-conv.md)
# Null 資料函數
Null 資料函數會處理或操作 NULL 值，這表示沒有值。函數可讓您將 NULLs 取代為其他值、檢查值是否為 NULL，或執行以特定方式處理 NULLs 的操作。
| **函數** | **Signature** | **Description** |
| --- | --- | --- |
| `COALESCE` | COALESCE (expression1、 expression2、...、 expressionN) | 如果所有表達式都評估為 null，則 COALESCE 會傳回 null。運算式必須為相同類型。 |
**Example COALESCE 函數的**
```
SELECT COALESCE (l.double_value, 100) AS non_double_value FROM latest_value_time_series AS l LIMIT 1
```
# 字串函數
字串函數是用於操作和處理文字資料的內建工具。它們可在字串中啟用串連、擷取、格式化和搜尋等任務。這些函數對於清理、轉換和分析資料庫中以文字為基礎的資料至關重要。
**字串函數**
| **函數** | **Signature** | **Description** |
| --- | --- | --- |
| `LENGTH` | LENGTH （字串） | 傳回字串的長度。 |
| `CONCAT` | CONCAT （字串、字串） | 串連字串中的引數。 |
| `SUBSTR` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-string.html) | 傳回下列其中一項： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-string.html) 使用以 1 為基礎的索引做為啟動參數。 |
| `UPPER` | UPPER （字串） | 將輸入字串中的字元轉換為大寫。 |
| `LOWER` | LOWER （字串） | 將輸入字串中的字元轉換為小寫。 |
| `TRIM` | TRIM （字串） | 從字串的開頭、結尾或兩側移除任何空格字元。 |
| `LTRIM` | LTRIM （字串） | 從字串開頭移除任何空格字元。 |
| `RTRIM` | RTRIM （字串） | 從字串結尾移除任何空格字元。 |
| `STR_REPLACE` | STR\$1REPLACE （字串、從、到） | 以另一個指定的子字串取代指定子字串的所有出現次數。 |
所有 函數的範例：
| **函數** | **範例** |
| --- | --- |
| LENGTH | `SELECT LENGTH(a.asset_id) AS asset_id_length FROM asset AS a` |
| CONCAT | `SELECT CONCAT(p.property_id, p.property_name) FROM asset_property AS p` |
| SUBSTR | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-string.html) |
| UPPER | `SELECT UPPER(d.string_value) AS up_string FROM raw_time_series AS d` |
| LOWER | `SELECT LOWER(d.string_value) AS low_string FROM raw_time_series AS d` |
| TRIM | `SELECT TRIM(d.string_value) AS tm_string FROM raw_time_series AS d` |
| LTRIM | `SELECT LTRIM(d.string_value) AS ltrim_string FROM raw_time_series AS d` |
| RTRIM | `SELECT RTRIM(d.string_value) AS rtrim_string FROM raw_time_series AS d` |
| STR\$1REPLACE | `SELECT STR_REPLACE(d.string_value, 'abc', 'def') AS replaced_string FROM raw_time_series AS d` |
## 串連運算子
串連運算子 `||`或管道運算子將兩個字串聯結在一起。它提供 `CONCAT`函數的替代方案，並在結合多個字串時更容易讀取。
**Example 串連運算子的**
```
SELECT a.asset_name || ' - ' || p.property_name
AS full_name
FROM asset a, asset_property p
```
# 數學函數
數學函數是 SQL 查詢中用來對數值資料執行計算的預先定義數學操作。它們提供操作和轉換資料的方法，而不需要從資料庫擷取資料並單獨處理資料。
**數學函數**
| **函數** | **Signature** | **Description** |
| --- | --- | --- |
| `POWER` | POWER (int\$1double、int\$1double) | 傳回提升為第二個引數能力的第一個引數值。 |
| `ROUND` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-math.html) | 四捨五入至最接近的整數。 |
| `FLOOR` | FLOOR (int\$1double) | 傳回不超過指定值的最大整數。 |
所有 函數的範例：
| **函數** | **範例** |
| --- | --- |
| POWER | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-math.html) |
| ROUND | `ROUND (32.12435, 3)` |
| FLOOR | `FLOOR (21.2)` |
# 日期時間函數
日期時間函數適用於日期和時間。這些函數允許擷取日期的特定元件、執行計算和操作日期值。
這些函數中允許的識別符包括：
+ YEAR
+ MONTH
+ DAY
+ HOUR
+ MINUTE
+ SECOND
| **函數** | **Signature** | **Description** |
| --- | --- | --- |
| `NOW` | 現在 ( ) | 以毫秒精確度傳回目前的時間戳記。它提供在查詢中執行的確切時間。 |
| `DATE_ADD` | DATE\$1ADD （識別符、 interval\$1duration、資料欄） | 傳回日期/時間和天數/小時的總和，或日期/時間和日期/時間間隔的總和。 |
| `DATE_SUB` | DATE\$1SUB （識別符、 interval\$1duration、資料欄） | 傳回日期/時間和天數/小時之間的差異，或日期/時間和日期/時間間隔之間的差異。 |
| `TIMESTAMP_ADD` | TIMESTAMP\$1ADD （識別符、 interval\$1duration、資料欄） | 將指定時間單位的時間間隔新增至日期時間表達式。 |
| `TIMESTAMP_SUB` | TIMESTAMP\$1SUB （識別符、 interval\$1duration、資料欄） | 從日期時間表達式減去指定時間單位的時間間隔。 |
| `CAST` | CAST （表達式 AS TIMESTAMP FORMAT 模式） | 使用指定的格式模式將字串表達式轉換為時間戳記。標準日期時間格式`'yyyy-MM-dd HH:mm:ss'`的常見模式包括 。例如 `SELECT CAST('2023-12-25 14:30:00' AS TIMESTAMP) AS converted_timestamp` |
**Example 使用所列函數的 SQL 查詢：**
```
SELECT r.asset_id, r.int_value,
date_add(DAY, 7, r.event_timestamp) AS date_in_future,
date_sub(YEAR, 2, r.event_timestamp) AS date_in_past,
timestamp_add(DAY, 2, r.event_timestamp) AS timestamp_in_future,
timestamp_sub(DAY, 2, r.event_timestamp) AS timestamp_in_past,
now() AS time_now
FROM raw_time_series AS r
```
# 類型轉換函數
類型轉換函數用於將值的資料類型從一個變更為另一個。它們對於確保資料相容性和執行需要特定格式資料的操作至關重要。
| **函數** | **Signature** | **Description** |
| --- | --- | --- |
| `TO_DATE` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-type-conv.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-type-conv.html) |
| `TO_TIMESTAMP` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-type-conv.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-type-conv.html) |
| `TO_TIME` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-type-conv.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-type-conv.html) |
| `CAST` | CAST ( AS ) | 將評估為單一值的實體或表達式，從一種類型轉換為另一種類型。 支援的資料類型如下： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-type-conv.html) |
**Example 使用所列函數的 SQL 查詢：**
```
SELECT TO_TIMESTAMP (100) AS timestamp_value,
TO_DATE(r.event_timestamp) AS date_value,
TO_TIME(r.event_timestamp) AS time_value
FROM raw_time_series AS r
```
# 彙總函數
彙總函數是跨多資料列執行計算的資料庫操作，可產生單一摘要結果。這些函數會分析資料集，以傳回計算值，例如總和、平均值、計數或其他統計指標。
| **函數** | **Signature** | **Description** |
| --- | --- | --- |
| `AVG` | AVG （表達式） | 傳回數值表達式的平均值。 |
| `COUNT` | COUNT （表達式） | 傳回符合指定條件的資料列數。 |
| `MAX` | MAX （表達式） | 傳回所選表達式的最大值。 |
| `MIN` | MIN （表達式） | 傳回所選表達式的最小值。 |
| `SUM` | SUM （表達式） | 傳回數值表達式的總和。 |
| `STDDEV` | STDDEV （表達式） | 傳回範例標準差。 |
| `GROUP BY` | GROUP BY 運算式 | 傳回由分組資料欄建立的資料列。 |
| `HAVING` | HAVING 布林值表達式 | 傳回依`GROUP BY`子句篩選的群組資料列。 |
所有 函數的範例：
| **函數** | **範例** |
| --- | --- |
| AVG | SELECT d.asset_id, d.property_id, AVG(d.int_value) FROM raw_time_series AS d
|
| COUNT | SELECT COUNT(d.int_value) FROM raw_time_series AS d
|
| MAX | SELECT MAX(d.int_value) FROM raw_time_series AS d
|
| MIN | SELECT MIN(d.int_value) FROM raw_time_series AS d
|
| SUM | SELECT SUM(d.int_value) FROM raw_time_series AS d
|
| STDDEV | SELECT STDDEV(d.int_value) FROM raw_time_series AS d
|
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/iot-sitewise/latest/userguide/sql-functions-aggregated.html) | SELECT MAX(d.int_value) AS max_int_value, d.asset_id
FROM raw_time_series AS d
GROUP BY d.asset_id
HAVING MAX(d.int_value) > 5
|
# 查詢範例
## 中繼資料篩選
下列範例適用於使用 AWS IoT SiteWise 查詢語言的 `SELECT`陳述式進行中繼資料篩選：
```
SELECT a.asset_name, p.property_name
FROM asset a, asset_property p
WHERE a.asset_name LIKE 'Windmill%'
```
## 值篩選
以下是使用具有 AWS IoT SiteWise 查詢語言的`SELECT`陳述式篩選值的範例：
```
SELECT a.asset_name, r.int_value
FROM asset a, raw_time_series r
WHERE r.int_value > 30
AND r.event_timestamp > TIMESTAMP '2022-01-05 12:15:00'
AND r.event_timestamp < TIMESTAMP '2022-01-05 12:20:00'
```
# 查詢最佳化
## 中繼資料篩選條件
當您查詢中繼資料或原始資料時，請使用 `WHERE`子句依中繼資料欄位篩選，以減少掃描的資料量。使用下列運算子來限制中繼資料掃描：
+ 等於 (=)
+ 不等於 (！=)
+ LIKE
+ IN
+ AND
+ 或
對於屬性屬性，請使用下列欄位來篩選結果：
+ `double_attribute_value`
+ `int_attribute_value`
+ `boolean_attribute_value`
+ `string_attribute_value`
這些欄位為屬性類型的資產屬性提供比 **latest\$1value\$1time\$1series** 資料表更好的效能。
**注意**
使用運算子右側的常值來正確限制資料掃描。例如，下列查詢的效能比使用嚴格的字串常值差：
```
SELECT property_id FROM asset_property WHERE property_name = CONCAT('my', 'property')
```
**Example 對於中繼資料篩選條件：**
```
SELECT p.property_name FROM asset_property p
WHERE p.property_type = 'attribute' AND p.string_attribute_value LIKE 'my-property-%'
```
## 原始資料篩選條件
所有原始資料表 (**raw\$1time\$1series**、 **latest\$1value\$1time\$1series**、**precomputed\$1aggregates**) 都有與其資料列相關聯的時間戳記。除了中繼資料篩選條件之外，在 `event_timestamp` 欄位中使用`WHERE`子句篩選條件來減少掃描的資料量。使用下列操作來限制原始資料掃描：
+ 等於 (=)
+ 大於 (>)
+ 小於 (<)
+ 大於或等於 (>=)
+ 小於或等於 (<=)
+ BETWEEN
+ AND
**篩選條件範例**：
+ 查詢 **precomputed\$1aggregates** 資料表時，請務必在 `WHERE`子句中指定品質篩選條件。這可減少查詢掃描的資料量，尤其是在尋找 `BAD`或 `UNCERTAIN`資料時。
我們也強烈建議在查詢 **precomputed\$1aggregates** 資料表時使用解析度篩選條件 (1m、15m、1h 或 1d)。如果您未指定解析度篩選條件， AWS IoT SiteWise 會預設為對所有解析度進行完整資料表掃描，這是效率不佳的。
+ 查詢原始資料時，也可以在 `WHERE`子句中使用時間戳記函數來篩選掃描的資料量。例如，下列查詢只會從 **raw\$1time\$1series** 資料表掃描最後 30 分鐘的資料：
```
SELECT r.event_timestamp, r.double_value
FROM raw_time_series r
WHERE r.event_timestamp > TIMESTAMP_SUB(MINUTE, 30, NOW())
```
**注意**
不等於 `(!=)`且`OR`運算子通常不會將有意義的篩選條件套用至原始資料掃描。篩選原始資料值 (string\$1value、double\$1value 等） 也不會限制原始資料掃描。
## JOIN 最佳化
AWS IoT SiteWise SQL 支援將兩個資料表合併在一起的`JOIN`關鍵字。僅支援`JOIN`主動篩選欄位 （使用`ON`關鍵字） 的 。禁止完整笛卡爾聯結。
AWS IoT SiteWise 也支援隱含 `JOIN`而不使用 `JOIN`關鍵字。在不同中繼資料表和中繼資料表與原始資料表之間允許這些項目。例如，這個查詢：
```
SELECT a.asset_name, p.property_name FROM asset a, asset_property p
```
執行優於此對等查詢：
```
SELECT a.asset_name, p.property_name FROM asset a
JOIN asset_property p ON a.asset_id = p.asset_id
```
允許下列隱含聯結 （允許 O，禁止 X)：
| | 資產 | asset\$1property | latest\$1value\$1time\$1series | raw\$1time\$1series | precomputed\$1aggregates | subquery |
| --- | --- | --- | --- | --- | --- | --- |
| 資產 | X | O | O | O | O | X |
| asset\$1property | O | X | O | O | O | X |
| latest\$1value\$1time\$1series | O | O | X | X | X | X |
| raw\$1time\$1series | O | O | X | X | X | X |
| precomputed\$1aggregates | O | O | X | X | X | X |
| subquery | X | X | X | X | X | X |
盡可能使用隱含 `JOIN`。如果您必須使用 `JOIN`關鍵字，請在個別 `JOIN`ed 資料表上套用篩選條件，以將掃描的資料降至最低。例如， 而不是此查詢：
```
SELECT level1.asset_id, level2.asset_id, level3.asset_id
FROM asset AS level1
JOIN asset AS level2 ON level2.parent_asset_id = level1.asset_id
JOIN asset AS level3 ON level3.parent_asset_id = level2.asset_id
WHERE level1.asset_name LIKE 'level1%'
AND level2.asset_name LIKE 'level2%'
AND level3.asset_name LIKE 'level3%'
```
使用此更有效率的查詢：
```
SELECT level1.asset_id, level2.asset_id, level3.asset_id
FROM asset AS level1
JOIN (SELECT asset_id, parent_asset_id FROM asset WHERE asset_name LIKE 'level2%') AS level2 ON level2.parent_asset_id = level1.asset_id
JOIN (SELECT asset_id, parent_asset_id FROM asset WHERE asset_name LIKE 'level3%') AS level3 ON level3.parent_asset_id = level2.asset_id
WHERE level1.asset_name LIKE 'level1%'
```
透過將中繼資料篩選條件推送至子查詢，您可以確保在掃描程序期間篩選 `JOIN`中的個別資料表。您也可以在子查詢中使用 `LIMIT`關鍵字以獲得相同的效果。
## 大型查詢
對於產生超過預設值的資料列的查詢，請將 [ExecuteQuery](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ExecuteQuery.html) API 的頁面大小設定為最大值 20000。這可改善整體查詢效能。
使用 `LIMIT`子句來減少針對某些查詢掃描的資料量。請注意，彙總函數和某些全資料表子句 (`GROUP BY`、`ORDER BY`、`JOIN`) 需要完整掃描才能套用子`LIMIT`句。
**注意**
AWS IoT SiteWise 即使套用 `LIMIT`子句， 也可能掃描最少量的資料，尤其是掃描多個屬性的原始資料查詢。
# ODBC
的開放原始碼 [ODBC 驅動程式](https://github.com/awslabs/aws-iotsitewise-odbc-driver) AWS IoT SiteWise 為開發人員 AWS IoT SiteWise 提供 SQL 相關界面，並可從 Power BI Desktop 和 Microsoft Excel 等商業智慧 (BI) 工具進行連線。 AWS IoT SiteWise ODBC 驅動程式目前可在 [Windows](https://github.com/awslabs/aws-iotsitewise-odbc-driver/releases) 上使用，並支援 SSO with Okta and Microsoft Azure Active Directory (AD)。
如需詳細資訊，請參閱 [AWS IoT SiteWise GitHub 上的 ODBC 驅動程式文件](https://github.com/awslabs/aws-iotsitewise-odbc-driver/blob/main/docs/markdown/index.md)。
**Topics**
+ [ODBC 驅動程式的連線字串語法和選項](query-ODBC-connecting.md)
+ [AWS IoT SiteWise ODBC 驅動程式的連線字串範例](query-ODBC-connecting-examples.md)
+ [對與 ODBC 驅動程式的連線進行故障診斷](query-ODBC-connecting-troubleshooting.md)
# ODBC 驅動程式的連線字串語法和選項
指定 ODBC 驅動程式連線字串選項的語法如下：
```
Driver={AWS IoT SiteWise ODBC Driver};(option)=(value);
```
可用選項如下：
**驅動程式連線選項**
+ **`Driver`** *（必要）* – 與 ODBC 搭配使用的驅動程式。
預設為 AWS IoT SiteWise。
+ **`DSN`** – 用於設定連線的資料來源名稱 (DSN)。
預設值為 `NONE`。
+ **`Auth`** – 身分驗證模式。這必須是下列其中一項：
+ `AWS_PROFILE` – 使用預設登入資料鏈。
+ `IAM` – 使用 AWS IAM 登入資料。
+ `AAD` – 使用 Azure Active Directory (AD) 身分提供者。
+ `OKTA` – 使用 Okta 身分提供者。
預設值為 `AWS_PROFILE`。
**端點組態選項**
+ **`EndpointOverride`** – AWS IoT SiteWise 服務的端點覆寫。這是覆寫區域的進階選項。例如：
```
iotsitewise.us-east-1.amazonaws.com
```
+ **`Region`** – AWS IoT SiteWise 服務端點的簽署區域。
預設值為 `us-east-1`。
**登入資料提供者選項**
+ **`ProfileName`** – AWS 組態檔案中的設定檔名稱。
預設值為 `NONE`。
**AWS IAM 身分驗證選項**
+ **`UID`** 或 **`AccessKeyId`** – AWS 使用者存取金鑰 ID。如果連線字串中同時提供 `AccessKeyId` `UID`和 ，除非值為空白，否則將使用 `UID`值。
預設值為 `NONE`。
+ **`PWD`** 或 **`SecretKey`** – AWS 使用者私密存取金鑰。如果連線字串中同時提供 `SecretKey` `PWD`和 ，除非值為空白，否則將使用 搭配 `PWD`的值。
預設值為 `NONE`。
+ **`SessionToken`** – 存取已啟用多重要素驗證 (MFA) 的資料庫所需的臨時工作階段字符。請勿在輸入` = `中包含結尾。
預設值為 `NONE`。
**Okta 的 SAML 型身分驗證選項**
+ **`IdPHost`** – 指定 IdP 的主機名稱。
預設值為 `NONE`。
+ **`UID`** 或 **`IdPUserName`** – 指定 IdP 帳戶的使用者名稱。如果連線字串中同時提供 `IdPUserName` `UID`和 ，除非值為空白，否則將使用 `UID`值。
預設值為 `NONE`。
+ **`PWD`** 或 **`IdPPassword`** – 指定 IdP 帳戶的密碼。如果連線字串中同時提供 `IdPPassword` `PWD`和 ，除非值為空白，否則將使用 `PWD`值。
預設值為 `NONE`。
+ **`OktaApplicationID`** – 與 AWS IoT SiteWise 應用程式相關聯的唯一 Okta 提供的 ID。尋找應用程式 ID (AppId) 的位置位於應用程式中繼資料中提供的`entityID`欄位中。例如：
```
entityID="http://www.okta.com//(IdPAppID)
```
預設值為 `NONE`。
+ **`RoleARN`** – 發起人所擔任角色的 Amazon Resource Name (ARN)。
預設值為 `NONE`。
+ **`IdPARN`** – IAM 中描述 IdP 之 SAML 提供者的 Amazon Resource Name (ARN)。
預設值為 `NONE`。
**Azure Active Directory 的 SAML 型身分驗證選項**
+ **`UID`** 或 **`IdPUserName`** – 指定 IdP 帳戶的使用者名稱。
預設值為 `NONE`。
+ **`PWD`** 或 **`IdPPassword`** – 指定 IdP 帳戶的密碼。
預設值為 `NONE`。
+ **`AADApplicationID`** – Azure AD 上已註冊應用程式的唯一 ID。
預設值為 `NONE`。
+ **`AADClientSecret`** – 與 Azure AD 上已註冊應用程式相關聯的用戶端秘密，用於授權擷取字符。
預設值為 `NONE`。
+ **`AADTenant`** – Azure AD 租用戶 ID。
預設值為 `NONE`。
+ **`RoleARN`** – 發起人所擔任角色的 Amazon Resource Name (ARN)。
預設值為 `NONE`。
+ **`IdPARN`** – IAM 中描述 IdP 之 SAML 提供者的 Amazon Resource Name (ARN)。
預設值為 `NONE`。
**AWS SDK （進階） 選項**
+ **`RequestTimeout`** – SDK 在逾時之前 AWS 等待查詢請求的時間，以毫秒為單位。任何非正值都會停用請求逾時。
預設值為 `3000`。
+ **`ConnectionTimeout`** – SDK 在逾時之前 AWS 等待透過開放連線傳輸資料的時間，以毫秒為單位。值為 0 會停用連線逾時。此值不得為負數。
預設值為 `1000`。
+ **`MaxRetryCountClient`** – SDK 中具有 5xx 錯誤代碼的可重試錯誤重試嘗試次數上限。值不得為負。
預設值為 `0`。
+ **`MaxConnections`** – 允許同時開啟 AWS IoT SiteWise 服務 HTTP 連線的數量上限。值必須為正值。
預設值為 `25`。
**ODBC 驅動程式記錄選項**
+ **`LogLevel`** – 驅動程式記錄的日誌層級。必須是下列其中一個：
+ **0** (OFF)。
+ **1** (ERROR)。
+ **2** （警告）。
+ **3** (INFO)。
+ **4** (DEBUG)。
預設值為 `1`(ERROR)。
**警告：**使用 DEBUG 記錄模式時，驅動程式可以記錄個人資訊。
+ **`LogOutput`** – 要存放日誌檔案的 資料夾。
預設值為：
+ **Windows：**`%USERPROFILE%`，如果無法使用，則為 `%HOMEDRIVE%%HOMEPATH%`。
+ **macOS 和 Linux：**`$HOME`，如果無法使用，則為函數`getpwuid(getuid())`傳回值`pw_dir`中的 欄位。
**SDK 記錄選項**
AWS SDK 日誌層級與 AWS IoT SiteWise ODBC 驅動程式日誌層級不同。設定一個不會影響另一個。
使用環境變數 設定 SDK 日誌層級`SW_AWS_LOG_LEVEL`。有效的值如下：
+ `OFF`
+ `ERROR`
+ `WARN`
+ `INFO`
+ `DEBUG`
+ `TRACE`
+ `FATAL`
如果`SW_AWS_LOG_LEVEL`未設定 ，軟體開發套件日誌層級會設定為預設值，即 `WARN`。
## 透過代理連線
ODBC 驅動程式支援 AWS IoT SiteWise 透過代理連線至 。若要使用此功能，請根據您的代理設定設定下列環境變數：
+ **`SW_PROXY_HOST`** – 代理主機。
+ **`SW_PROXY_PORT`** – 代理連接埠號碼。
+ **`SW_PROXY_SCHEME`** – 代理結構描述， `http`或 `https`。
+ **`SW_PROXY_USER`** – 代理身分驗證的使用者名稱。
+ **`SW_PROXY_PASSWORD`** – 代理身分驗證的使用者密碼。
+ **`SW_PROXY_SSL_CERT_PATH`** – 用於連線至 HTTPS 代理的 SSL 憑證檔案。
+ **`SW_PROXY_SSL_CERT_TYPE`** – 代理用戶端 SSL 憑證的類型。
+ **`SW_PROXY_SSL_KEY_PATH`** – 用於連線至 HTTPS 代理的私有金鑰檔案。
+ **`SW_PROXY_SSL_KEY_TYPE`** – 用來連線至 HTTPS 代理的私有金鑰檔案類型。
+ **`SW_PROXY_SSL_KEY_PASSWORD`** – 用於連線至 HTTPS 代理的私有金鑰檔案的密碼短語。
# AWS IoT SiteWise ODBC 驅動程式的連線字串範例
## 使用 IAM 憑證連線至 ODBC 驅動程式的範例
```
Driver={AWS IoT SiteWise ODBC Driver};Auth=IAM;AccessKeyId=(your access key ID);SecretKey=(your secret key);SessionToken=(your session token);Region=us-east-1;
```
## 使用設定檔連線至 ODBC 驅動程式的範例
```
Driver={AWS IoT SiteWise ODBC Driver};ProfileName=(the profile name);region=us-east-1;
```
驅動程式會嘗試使用 中提供的登入資料進行連線`~/.aws/credentials`，或者如果在環境變數 中指定檔案`AWS_SHARED_CREDENTIALS_FILE`，則會使用該檔案中的登入資料進行連線。
## 使用 Okta 連線至 ODBC 驅動程式的範例
```
Driver={AWS IoT SiteWise ODBC Driver};Auth=OKTA;region=us-east-1;idPHost=(your host at Okta);idPUsername=(your user name);idPPassword=(your password);OktaApplicationID=(your Okta AppId);roleARN=(your role ARN);idPARN=(your Idp ARN);
```
## 使用 Azure Active Directory (AAD) 連線至 ODBC 驅動程式的範例
```
Driver={AWS IoT SiteWise ODBC Driver};Auth=AAD;region=us-east-1;idPUsername=(your user name);idPPassword=(your password);aadApplicationID=(your AAD AppId);aadClientSecret=(your AAD client secret);aadTenant=(your AAD tenant);roleARN=(your role ARN);idPARN=(your idP ARN);
```
## 連接至具有指定端點且日誌層級為 2 的 ODBC 驅動程式的範例 （警告）
```
Driver={AWS IoT SiteWise ODBC Driver};Auth=IAM;AccessKeyId=(your access key ID);SecretKey=(your secret key);EndpointOverride=iotsitewise.us-east-1.amazonaws.com;Region=us-east-1;LogLevel=2;
```
# 對與 ODBC 驅動程式的連線進行故障診斷
**注意**
如果 DSN 中已指定使用者名稱和密碼，請勿在 ODBC 驅動程式管理員要求時再次指定使用者名稱和密碼。
當連線字串選項在連線字串中傳遞超過一次時，`Re-writing (connection string option) (have you specified it several times?)`會發生`01S02`具有訊息的錯誤代碼 。多次指定選項會導致錯誤。與 DSN 和連線字串建立連線時，如果已在 DSN 中指定連線選項，請勿在連線字串中再次指定。