安裝及配置 Experience Service > 組態參數
  
組態參數
* 
如果使用安裝程式安裝 Experience Service，則由安裝程式配置此類參數。
本節說明可用於設定您 Experience Service 各個面向的不同組態參數。可透過下列任何方法來指定這些組態參數的數值：
1. 啟動服務時，在命令列上指定組態參數的值。在命令列上輸入參數名稱，而名稱前綴為雙破折號 (--)，其後立刻接上參數值。例如 --port 3000。
2. 使用環境變數來指定組態參數的值。建立環境變數，且其名稱需對應組態參數，並設定環境變數的值等於所需的參數值。環境變數的名稱應等於組態參數；但巢狀組態參數除外。在此情況下，必須以雙下底線 (__) 作為分隔符號；而非「點」(.) 作為分隔符號。舉例來說，若要指定 db.connectionString 的值，可建立名稱為 db__connectionString 的環境變數。
3. 在根安裝目錄中所建立的服務 configuration.json 檔案之內，指定組態參數的值。
基本驗證組態參數
* 
如果您要配置單一登入驗證，請參閱下方的〈單一登入 (SSO) 驗證組態參數〉一節。
Experience Service 使用 ThingWorx 進行驗證。安裝程式會設定 Experience Service 要使用您在安裝期間識別的 ThingWorx 伺服器進行驗證。
如有必要，您可透過下列組態參數來手動設定驗證：
參數
描述
authentication.type
如果使用「基本驗證」，則此參數必須設定為 twxUser。
authentication.baseURL
用於驗證的 ThingWorx 伺服器之網址。例如 https://twx.example.com:8443
authentication.authorization.appKey
ThingWorx 應用程式金鑰，將由 Experience Service 用以讀取 ThingWorx 群組的成員資格。群組成員資格用於判斷使用者所屬的 Experience Service 角色，以及已授與該使用者的權限。
如需有關設定授權應用程式金鑰的詳細資訊，請參閱 設定 ThingWorx 群組成員的存取權限。
authentication.authorization.refreshRate
此參數可決定 Experience Service 角色成員資格與 ThingWorx 群組成員資格之間的同步頻率。指定的值以毫秒為單位。
此項設定已預設為 5 分鐘。最高速率可設為 30 秒。
單一登入 (SSO) 驗證組態參數
本節描述其他驗證組態參數以及對所提供之現有組態參數的修改，以支援 Experience Service SSO 組態。
參數
描述
authentication.type
若將 Experience Service 配置為使用 SSO，則必須將此參數設定為 openidUser。
authentication.baseUrl
ThingWorx 伺服器的網址，該伺服器用於在使用基本驗證時進行驗證，以及用於群組成員同步 (不受驗證類型約束)。 例如，https://twx.example.com:8443。
authentication.authorization.refreshRate
此參數可決定 Experience Service 角色成員資格與 ThingWorx 群組成員資格之間的同步頻率。指定的值以毫秒為單位。
此項設定已預設為 5 分鐘。最高速率可設為 30 秒。
authentication.openid.issuer
將其設定為與〈PingFederate 組態範例〉的〈SSO 組態參數〉一節中識別的 <as-base-url> 參數相同的值。
authentication.openid.clientId
將其設定為與〈PingFederate 組態範例〉的〈SSO 組態參數〉一節中識別的 <es-client-id> 參數相同的值。
authentication.openid.clientSecret
將其設定為與〈PingFederate 組態範例〉的〈SSO 組態參數〉一節中識別的 <es-client-secret> 參數相同的值。
authentication.openid.redirectUri
將其設定為與〈PingFederate 組態範例〉的〈SSO 組態參數〉一節中識別的 <es-redirect-uri> 參數相同的值。
authentication.openid.session.maxAge
當使用者使用 OpenID Connect 與 Experience Service 進行驗證時，會為該使用者建立工作階段。此屬性可指定工作階段失效且使用者必須重新進行驗證的期限。此設定的預設單位為毫秒。但是，可透過將單位名稱附加到值，指定其他單位。例如，「10 小時」。支援以下單位︰
• 秒：seconds、s
• 分鐘：minutes、m
• 小時：hours、hrs、hour、h
• 天：days、day、d
authentication.openid.externalScope
使用 oauth2 存取 ThingWorx API 時需要此項。此值應設定為在 ThingWorx 中配置的值，以使用 ThingWorx 作為資源供應者。
authentication.openid.esScope
將其設定為與〈PingFederate 組態範例〉的〈SSO 組態參數〉一節中識別的 <es-scope> 參數相同的值。
authentication.openid.studioClientId
輸入 Studio 用戶端 ID 的名稱。此欄位的預設值為 PTC_Studio_Client_ID。但是，如果已配置為不同的值，請務必在此輸入。
authentication.openid.claimsMapping.username
將其設定為與您 OpenID Connect 原則中識別之 sub 屬性相同的值。如需詳細資訊，請參閱〈OpenID 原則組態〉的步驟 9。
以下是 JSON 範例，可用於配置 Experience Service，以使用 OpenID Connect 與 OAuth2︰
"authentication": {
"type": "openidUser",
"baseUrl": "https://twx.example.vuforia.io:8443",
"authorization": {
"appKey": "",
"refreshRate": "300000",
"useAclDbBackend": false
},
"openid": {
"issuer": "https://twx.example.vuforia.io:8443",
"clientId": "es-client",
"clientSecret": "es-client_1234",
"session:" {
"maxAge": "2 minutes",
"secret": "0c8ad6dkhd7976986knd87ea"
},
"externalScope": "THINGWORX"
}
},
內容儲存
Experience Service 在檔案系統上儲存專案和表示內容。以下列組態參數來設定這些儲存：
* 
如果已在叢集中部署 Experience Service，請確保叢集中執行的所有實例，均可存取資料儲存目錄 (projects.store、reps.store 與 upgrade.store)。
參數
描述
projects.storePath
儲存專案內容的目錄路徑。
projects.staticOps.maxAge
在將專案內容下載至用戶端時，指定回應所包含的最長時間標題 (max-age header) 的值。
reps.storePath
儲存表示庫藏內容的目錄路徑。
reps.staticOps.maxAge
在將表示內容下載至用戶端時，指定回應所包含的最長時間標題的值。
upgrade.storePath
儲存移轉程式成功檔案的目錄路徑。這些檔案用於指示升級移轉程式已成功完成其資料移轉工作，避免重複移轉。
* 
為這些組態參數指定的路徑，可以是絕對路徑或相對路徑。絕對路徑是以「/」開頭，且被視為相對於檔案系統的根目錄；而相對路徑以「./」開頭，且被視為相對於 Experience Service 的安裝目錄。
資料庫
Experience Service 支援下列資料庫軟體：
• SQLite
• PostgreSQL
* 
以 Experience Service 安裝 SQLite。必須取得 PostgreSQL 並單獨安裝。
首次啟動 Experience Service 時，隨即在資料庫中建立所有必要表格。以下列組態參數來設定 Experience Service 所將使用的資料庫：
參數
描述
dbHandler
將此參數設定為下列之一：
• 如果使用 SQLite，則為 SQLiteHandler
• 如果使用 PostgreSQL，則為 postgresHandler
db.datafilePath
只有在使用 SQLite 並指定 SQLite 資料檔案的路徑時，才適用此參數。啟動 Experience Service 之後，如果資料檔案不存在則隨即會建立。
* 
為此組態參數指定的路徑，可以是絕對路徑或相對路徑。絕對路徑是以「/」開頭，且被視為相對於檔案系統的根目錄；而相對路徑以「./」開頭，且被視為相對於 Experience Service 的安裝目錄。
在 Windows 上，絕對路徑可以以「/」或磁碟機代號開頭，例如「C:/」。如果絕對路徑以「/」開頭，則該路徑被視為包含 Experience Service 安裝目錄的相關驅動根目錄路徑。
db.connectionString
只有在使用 SQLite 並指定 SQLite 資料檔案的路徑時，才適用此參數。連接字串的格式如下：
postgres://<dbusername>:<dbpassword>@<host>:<port>/<database-name>
使用的憑證必須有足夠的權限，才能在 PostgreSQL 資料庫中建立新的資料庫表格。
* 
如果您所使用的 PostgreSQL 實例，與 ThingWorx 伺服器所使用的相同，則 Experience Service 使用的資料庫名稱和登入 / 使用者名稱，必須與 ThingWorx 伺服器使用的資料庫名稱和登入 / 使用者名稱相異。
網域名稱
在某些情況下，Experience Service 必須知道用以存取其服務的網域名稱。如果 Experience Service 已於全域體驗索引 (GXI) 中註冊，則 Experience Service 網域名稱必須與 GXI 中註冊的網域名稱相同。該值一般完全符合執行 Experience Service 的主機之網域名稱 (FQDN) 要求。然而，如果 Experience Service 是部署在 Proxy 之後，就會是 Proxy 的 FQDN。
一般會在安裝期間指定網域名稱的值。但您也可將 defaultDomainName 組態參數的值設定等於相應的值，來手動設定網域名稱。
IRS Federation
依預設，Experience Service 已設定為使用 IRS federation。當使用 IRS federation 時，如果 Experience Service 收到 ThingMark 非自身網域的查詢，Experience Service 會將該請求轉發至以該網域註冊的 Experience Service。Experience Service 將收集針對該 ThingMark 發佈的所有本機體驗，並結合以該網域註冊的 Experience Service 所回傳之結果。
參數
描述
enable_irs_federation
將此參數設定為「True」即可啟用 IRS federation；若設定為「False」則停用 IRS federation。
domain_id_resolver
基礎網址用以查詢來自於其他 Experience Service 的體驗。此只有在啟用 IRS federation 時才必要。一般而言，需針對全域體驗索引 (GXI) 所提供的 PTC，使用基礎網址：
https://gxi.vuforia.io/VuforiaExperienceService/id-resolution/resolutions/
如需詳細資訊，請參閱〈識別解析度服務 (IRS) 聯盟〉。
記錄檔案位置
Experience Service 將記錄訊息寫入 stdout 與 stderr，可讓系統管理員針對部署環境，以合適的方式來擷取記錄訊息。如果是在檔案中擷取記錄訊息，則可設定 Experience Service 以讓擁有適當權限的使用者下載這些記錄檔案。若要進一步瞭解記錄訊息的擷取與下載，請參閱〈擷取記錄訊息〉。
使用下列組態參數來設定記錄檔位置：
參數
描述
logsPath
Glob 模式將描述與記錄檔相對應的路徑。依預設，已設定為 /var/logs/thingserver.log*。如此一來，只要是在 /var/logs 中，且以 thingserver.log 開頭的所有檔案均可下載。
* 
針對此組態參數所指定的路徑是以「/」開頭，並指定相對於檔案系統根目錄的路徑。
在 Windows 上，絕對路徑可以以「/」或磁碟機代號開頭，例如「C:/」。如果絕對路徑以「/」開頭，則該路徑被視為包含 Experience Service 安裝目錄的相關驅動根目錄路徑。
連接埠
您可以使用連接埠組態參數來配置 Experience Service 接聽其連線的連接埠。
Proxy
在 Proxy 後方部署 Experience Service 會影響服務的某些功能。trustProxy 組態屬性可用於確保將 Experience Service 部署在 Proxy 後方時，Experience Service 可正常運作。正確設定此參數，可確保 Experience Service︰
• 包含已於記錄訊息中傳送請求之用戶端的正確 IP 位址
• 使用體驗清單隨附之體驗網址的正確通訊協定 (例如，在回應 Vuforia View 傳送的 ThingMark 查詢時)
trustProxy 組態屬性的值會確定 Experience Service 如何決定用戶端 IP 位址，以及如何決定應將哪種通訊協定用於體驗網址。
trustProxy 設定
用戶端 IP
通訊協定
false (預設)
已傳送請求之用戶端的 IP
請求的通訊協定
true
X-Forwarded-For 標題中最左側的輸入項
X-Forwarded-Proto 標題的值
IP 篩選器條件
篩選該清單以移除符合指定篩選器條件 (如需詳細瞭解如何建構篩選器條件，請參閱以下內容) 之任何輸入項後，X-Forwarded-For 標題中最右側的輸入項
X-Forwarded-Proto 標題的值
整數 (n)
X-Forwarded-For 標題中，從右側數來第 n 個輸入項
X-Forwarded-Proto 標題的值
除了按上述方式設定 Experience Service 之外，還必須將 Proxy 配置為傳送下列標題中的適當資訊︰
• X-Forwarded-For
• X-Forwarded-Proto
下列選項可用於建構在 X-Forwarded-For 標題中篩選 IP 位址的條件。
篩選器選項
要篩選的位址
loopback
屬於下列子網的任何位址：
• IPv4︰127.0.0.1/8
• IPv6︰::1/128
linklocal
屬於下列子網的任何位址：
• IPv4︰169.254.0.0/16
• IPv6︰fe80::/10
uniquelocal
屬於下列子網之一的任何位址：
• IPv4︰10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16
• IPv6︰fc00::/7
<ip address>
指定的 IP 位址 (例如，203.0.113.13)
可將此類選項組合為以逗號分隔的清單，其中需包含至少一個子網選項。如需查看範例篩選器條件，請參閱以下範例。
以下範例適用於 trustProxy 組態參數的有效設定。
使用案例
trustProxy 參數設定
略過 X-Forwarded-* 標題中的資訊。
false
將 X-Forwarded-For 標題中的所有輸入項 (最左側的輸入項除外) 視為已知的受信任 Proxy。最左側的輸入項會視為用戶端 IP。
true
僅將本機主機視為已知的受信任 Proxy。
"loopback"
將本機主機與 IP 位址 203.0.113.13 及 203.0.113.15 視為受信任 Proxy。
"loopback, 203.0.113.13,203.0.113.15"
將本機主機與本機網路上的任何主機視為已知的受信任 Proxy
"loopback, linklocal, uniquelocal"
領域
安裝程式會自動設定 Experience Service 所使用的領域，使其與 ThingWorx 伺服器使用相同領域。如果您需要手動設定領域，我們也提供了相關說明。
Experience Service 可設為納入 WWW-Authenticate 標題中的領域，而該標題另已包含於傳送至用戶端的驗證挑戰中。欲在 WWW-Authenticate 標題中設定 Experience Service 所包含的值，請將領域參數設定為所需領域的名稱。
依預設，Experience Service 使用的驗證領域為：*。
以下就是 ThingWorx 所使用的預設驗證領域：
• 針對 ThingWorx 8.0 或更早版本，則預設的驗證領域為：*
• 針對 ThingWorx 8.1 及更高版本，預設的驗證領域為：ThingWorx
* 
您的 ThingWorx 伺服器可能已設為非預設領域。
欲確定 ThingWorx 所使用的驗證領域：
1. 開啟終端機並於命令列中輸入下列命令：
curl -is https://<ThingWorx-Core-Host-Port>/ThingWorx/Things | grep -i www-authenticate
其中的 <ThingWorx-Core-Host-Port> 應以 ThingWorx 伺服器的適當主機名稱與埠號所取代。例如：
curl -is https://my-twx.example.com:3124/ThingWorx/Things | grep -i www-authenticate
2. 輸出看起來應如下：
www-authenticate: Basic realm=*
接著 realm= 之後的值，即為 ThingWorx 伺服器所使用的驗證領域。
ThingWorx Proxy
Experience Service 需要 ThingWorx 伺服器來驗證使用者，並管理使用者群組的成員資格。此外，針對 Vuforia Studio 與 Vuforia View 所使用的 ThingWorx 伺服器，Experience Service 即做為其 Proxy。安裝程式將設定 Experience Service 來做為安裝期間識別的 ThingWorx 伺服器之 Proxy。若有必要，您可使用下列組態參數來手動設定 ThingWorx Proxy：
參數
描述
proxies.0.autoRewrite
如果設定為「True」，則 Experience Service 將變更 ThingWorx 伺服器所提供的任何重新導向統一資源識別元 (URI)，以便透過 Proxy 重新導回用戶端。我們假設 Experience ServiceThingWorx Proxy 位於 https://es.example.com/Thingworx，且作為 Proxy 的 ThingWorx 伺服器位於 https://twx.example.com/Thingworx。如果 ThingWorx 伺服器將用戶端重新導向至 https://twx.example.com/Thingworx/something，則 Experience Service 會將此網址重寫為 https://es.example.com/Thingworx/something。如果將此屬性設定為「False」，則 Experience Service 不會重寫這些重新導向 URI。
proxies.0.protocolRewrite
在重寫這些重新導向的 URI 時，此參數會識別所使用的通訊協定。再假設 Experience Service 是以安全 HTTPS 模式執行，但 ThingWorx 伺服器以不安全的 HTTP 模式執行。在此情況下，此參數必須設定為等於 HTTPS，以便在重寫重新導向 URI 時，即重寫為使用 Experience Service Proxy 所使用的通訊協定。
proxies.0.secure
如果設定為「True」，Experience ServiceThingWorx Proxy 將拒絕作為 Proxy 的 ThingWorx 伺服器所使用之未經授權 (自我簽署) 憑證。因此，如果作為 Proxy 的ThingWorx 伺服器使用自我簽署憑證，則此參數必須設定為「False」。
websocketProxies.0.autoRewrite
此參數針對網路通訊端 Proxy 的重新導向重寫行為之控制方式，與 proxies.0.autoRewrite 參數針對 HTTP Proxy 的重寫行為之控制方式完全相同。
websocketProxies.0.protocolRewrite
此參數將透過 proxies.0.protocolRewrite 參數控制 HTTP Proxy 重寫行為的相同方式，來控制網路通訊端 Proxy 重寫重新導向 URI 所使用的通訊協定。有效的通訊協定為 ws 或 wss。
websocketProxies.0.secure
此參數在控制網路通訊端 Proxy 是否拒絕未經授權 (自我簽署) 憑證的方式，就與 proxies.0.secure 參數控制 HTTP Proxy 是否拒絕未經授權 (自我簽署) 憑證的方式完全相同。
proxies.0.disabled
如果設定為「True」，此參數則會停用 ThingWorx Proxy。如果設定為「False」，則會啟用 Proxy。
proxies.0.target
ThingWorx 伺服器的基礎網址。此網址必須以 /Thingworx 結尾。例如 https://twx.acme.com:8443/Thingworx。
proxies.0.appKey
Experience Service 使用的 ThingWorx 應用程式金鑰，會授與公用體驗存取 ThingWorx 資料的權限。欲進一步了解共用體驗，並設定 ThingWorx 的共用存取，請參閱〈設定 ThingWorx 的公用存取〉。
websocketProxies.0.disabled
如果設定為「True」，此參數則會停用 ThingWorx 網路通訊端 Proxy。如果設定為「False」，則會啟用 Proxy。
websocketProxies.0.target
基礎網址可於用戶端與 ThingWorx 伺服器之間建立網路通訊端。此網址必須相容於 proxies.0.target 所指定的值。舉例來說，如果 proxies.0.target 設定為 https://twx.acme.com:8443/Thingworx，則此參數必須設定為 wss://twx.acme.com:8443。
* 
若要將 Edge 裝置與混搭連接至 ThingWorx 伺服器，請勿使用 Experience ServiceThingWorx Proxy。相反的，應直接連至 ThingWorx 伺服器 (使用替代連接埠、ELB 等)。Experience ServiceThingWorx Proxy 並非用於處理與 Edge 裝置流量關聯的負載，且特定的 Edge SDK 無法透過 Proxy 運作。
TLS 憑證
* 
如果已在叢集中部署 Experience Service，請確定叢集中執行的所有實體，均可存取金鑰和憑證檔案位置。
依預設，Experience Service 會透過 HTTPS 通訊協定來加密服務與用戶端之間的通訊。
如需詳細資訊，請參閱〈傳輸層安全性 (TLS) 憑證〉。
下列組態參數可設定用於加密的憑證：
* 
可以針對 PEM 屬性（httpsKeyPath、httpsCrtPath 與 httpsCaPath）或 PCKS12 (PFX) 屬性（httpsPfxPath）指定值，但不能同時針對這兩者。
參數
描述
httpsKeyPath
包含 PEM 編碼私密金鑰的檔案路徑。
httpsCrtPath
包含 PEM 編碼公開憑證的檔案路徑。
httpsCaPath
包含中繼憑證授權單位之 PEM 編碼公開憑證的憑證組合檔案路徑。
httpsCertPassphrase
用來解密 PEM 編碼私密金鑰或 PCKS12 (PFX) 編碼封存檔案的密碼。
httpsPfxPath
包含 PCKS12 (PFX) 編碼封存檔案的檔案路徑。
* 
為這些組態參數指定的路徑，可以是絕對路徑或相對路徑。絕對路徑是以「/」開頭，且被視為相對於檔案系統的根目錄；而相對路徑以「./」開頭，且被視為相對於 Experience Service 的安裝目錄。
在 Windows 上，絕對路徑可以以「/」或磁碟機代號開頭，例如「C:/」。如果絕對路徑以「/」開頭，則該路徑被視為包含 Experience Service 安裝目錄的相關驅動根目錄路徑。
選用參數
您可以將下列選用的配置參數手動新增至「configuration.json」檔案。
參數
描述
nohttp2
新增此參數並將其設定為 true，以將於體驗期間使用相機小工具拍攝的圖像儲存至 ThingWorx 中的存放庫。
例如：
{
…..
"nossl":true,
"nohttp2":true
}
進階模型目標參數
您可以將下列選用的配置參數手動新增至「configuration.json」檔案。
參數
描述
hmtg.credentials.baseUrl
模型目標服務的 URL。系統將為您填入參數。值為：
https://vws.vuforia.com
hmtg.credentials.tokenPath
OAuth2 驗證的 HTTP 請求路徑。系統將為您填入參數。值為：
oauth2/token
hmtg.credentials.amtgPath
進階模型目標產生的 HTTP 請求路徑。系統將為您填入參數。值為：
modeltargets/advancedDatasets
hmtg.credentials.accessKey
請務必聯絡 PTC 技術支援取得此參數值。如需詳細資訊，請參閱〈請求資訊以啟用進階模型目標產生〉。
hmtg.credentials.secretKey
請務必聯絡 PTC 技術支援取得此參數值。如需詳細資訊，請參閱〈請求資訊以啟用進階模型目標產生〉。
發佈參數
您可以將下列選用的配置參數手動新增至「configuration.json」檔案。
參數
描述
publicAccess
在 Vuforia Studio 停用或啟用發佈「存取」欄位設定為「公開」之專案的功能。
例如：
{
…..
"publicAccess":{
"disabled": true
}