為Adobe Experience Manager as a Cloud Service設定OSGi configuring-osgi-for-aem-as-a-cloud-service

OSGi是Adobe Experience Manager (AEM)技術棧疊中的基本元素。 它可用來控制AEM的複合套件組合及其組態。

OSGi提供標準化的原語，允許使用小型、可重複使用的合作元件來建構應用程式。 這些元件可組成應用程式並進行部署。 這可讓您輕鬆管理OSGi套件組合，因為它們可以個別停止、安裝和啟動。 系統會自動處理相依性。 每個OSGi元件都包含在各種套件組合中。 如需詳細資訊，請參閱OSGi規格。

您可以透過AEM程式碼專案一部分的組態檔案來管理OSGi元件的組態設定。

OSGi組態檔 osgi-configuration-files

組態變更在AEM Project的程式碼封裝(ui.config)中定義為runmode特定組態資料夾下的組態檔(.cfg.json)：

/apps/example/config.<runmode>

OSGi設定檔案的格式是以JSON為基礎，使用Apache Sling專案定義的.cfg.json格式。

OSGi設定會透過元件的持續身分識別(PID) (預設為OSGi元件的Java™類別名稱)來鎖定OSGi元件。 例如，若要為以下實施的OSGi服務提供OSGi設定：

com.example.workflow.impl.ApprovalWorkflow.java

OSGi設定檔案定義於：

/apps/example/config/com.example.workflow.impl.ApprovalWorkflow.cfg.json

遵循cfg.json OSGi設定格式。

執行模式解析度 runmode-resolution

特定OSGi設定可以透過使用執行模式以特定AEM執行個體為目標。 若要使用runmode，請在/apps/example下建立設定資料夾（範例為專案名稱），格式為：

/apps/example/config.<author|publish>.<dev|stage|prod>/

如果設定資料夾名稱中定義的執行模式符合AEM使用的執行模式，則會使用此類資料夾中的任何OSGi設定。

例如，如果AEM使用runmodes author和dev，則套用/apps/example/config.author/和/apps/example/config.author.dev/中的設定節點，但未套用/apps/example/config.publish/和/apps/example/config.author.stage/中的設定節點。

如果同一PID適用多個設定，則會套用符合執行模式數量最多的設定。

此規則的詳細程度位於PID層級。 這表示您無法在/apps/example/config.author/中為同一個PID定義某些屬性，也無法在/apps/example/config.author.dev/中為同一個PID定義更具體的屬性。 符合執行模式數量最多的設定對整個PID有效。

在本機開發時，執行模式啟動參數 -r 用於指定執行模式 OSGI 設定。

$ java -jar aem-sdk-quickstart-xxxx.x.xxx.xxxx-xxxx.jar -r publish,dev

驗證執行模式

AEM as a Cloud Service執行模式會根據環境型別和服務妥善定義。 檢閱可用AEM as a Cloud Service執行模式的完整清單。

可由以下驗證執行模式指定的OSGi設定值：

產生的檢視會顯示所選階層的所有OSGi元件設定及其適用的OSGi設定值。 這些值可以與AEM專案原始程式碼中/apps/example/osgiconfig/config.<runmode(s)>下的OSGi設定值互動參照。

若要確認已套用適當的OSGi設定值：

OSGi設定值的型別 types-of-osgi-configuration-values

有三種不同的OSGi設定值可與Adobe Experience Manager as a Cloud Service搭配使用。

如何選擇適當的OSGi設定值型別 how-to-choose-the-appropriate-osgi-configuration-value-type

OSGi的常見情況是使用內嵌OSGi設定值。 特定環境的設定僅用於開發環境之間值不同的特定使用案例。

環境特定設定擴充了包含內嵌值的傳統、靜態定義的OSGi設定，提供透過Cloud Manager API從外部管理OSGi設定值的功能。 瞭解何時應該使用定義內嵌值並將其儲存在Git中的常見和傳統方法，而不是將值抽象為特定於環境的設定時，這一點很重要。

以下指南說明何時使用非機密和機密環境特定設定：

何時使用內嵌設定值 when-to-use-inline-configuration-values

內嵌組態值會視為標準方法，並應儘可能使用。 內嵌組態具備以下優點：

每當定義OSGi設定值時，請從內嵌值開始，並根據使用案例的需要僅選取密碼或環境特定的設定。

何時使用非機密環境特定設定值 when-to-use-non-secret-environment-specific-configuration-values

只有在預覽層的值不同或開發環境的值不同時，才使用非機密組態值的環境特定組態($[env:ENV_VAR_NAME])。 這包括本機開發執行個體和任何Adobe Experience Manager as a Cloud Service開發環境。 除了為預覽層級設定唯一值外，請避免對Adobe Experience Manager as a Cloud Service中繼或生產環境使用非機密環境專屬設定。

何時使用機密環境特定的設定值 when-to-use-secret-environment-specific-configuration-values

Adobe Experience Manager as a Cloud Service要求針對任何機密的OSGi設定值（例如密碼、私人API金鑰或任何其他基於安全原因而無法儲存在Git中的值），使用特定於環境的設定($[secret:SECRET_VAR_NAME])。

使用秘密環境特定的設定，以儲存所有Adobe Experience Manager as a Cloud Service環境（包括中繼和生產環境）的秘密值。

建立OSGi設定 creating-osgi-configurations

建立OSGi設定的方式有兩種，如下所述。 前者通常用於設定自訂OSGi元件，這些元件具有開發人員熟知的OSGi屬性和值，而後者則用於AEM提供的OSGi元件。

寫入OSGi設定 writing-osgi-configurations

JSON格式的OSGi設定檔案可直接在AEM專案中手動撰寫。 這通常是建立已知OSGi元件（尤其是自訂OSGi元件）的OSGi設定的最快方法，這些元件是由定義設定的相同開發人員設計和開發的。 此方法也可用於跨各種執行模式資料夾，複製/貼上及更新相同OSGi元件的設定。

使用AEM SDK快速入門產生OSGi設定 generating-osgi-configurations-using-the-aem-sdk-quickstart

AEM SDK快速入門Jar的AEM Web主控台可用於設定OSGi元件，以及將OSGi設定匯出為JSON。 這對於設定AEM提供的OSGi元件而言，若開發人員在AEM專案中定義OSGi設定，可能無法深入瞭解這些元件的OSGi屬性及其值格式。

OSGi設定屬性格式 osgi-configuration-property-formats

內嵌值 inline-values

內嵌值的格式為遵循標準JSON語法的標準名稱 — 值組。 例如：

{
   "my_var1": "val",
   "my_var2": [ "abc", "def" ],
   "my_var3": 500
}

環境特定的設定值 environment-specific-configuration-values

OSGi設定應為要根據環境定義的變數指派預留位置：

use $[env:ENV_VAR_NAME]

客戶應該僅將此技巧用於與其自訂程式碼相關的OSGi設定屬性；不得使用此技巧來覆寫Adobe定義的OSGi設定。

密碼設定值 secret-configuration-values

OSGi設定應為要根據環境定義的密碼指派預留位置：

use $[secret:SECRET_VAR_NAME]

變數命名 variable-naming

以下適用於特定環境和密碼設定值。

變數名稱必須符合下列規則：

變數的值不得超過2048個字元。

預設值 default-values

以下適用於特定環境和密碼設定值。

如果未設定每個環境的值，則在執行階段不會取代預留位置，而且由於未發生內插，因此會保留預留位置。 為避免此問題，可以使用以下語法在預留位置中提供預設值：

$[env:ENV_VAR_NAME;default=<value>]

在提供預設值時，預留位置會取代為根據環境提供的值或提供的預設值。

本機開發 local-development

以下適用於特定環境和密碼設定值。

變數可在本機環境中定義，以便由本機AEM在執行階段擷取。 例如，在Linux®上：

export ENV_VAR_NAME=my_value

建議撰寫簡單的bash指令碼，此指令碼會設定設定中使用的環境變數，並在啟動AEM之前執行。 https://direnv.net/等工具有助於簡化此方法。 根據值的型別，如果可在所有人之間共用，這些值可能會被簽入原始程式碼管理。

密碼的值會從檔案中讀取。 因此，必須為使用密碼的每個預留位置建立包含密碼值的文字檔案。

例如，如果使用$[secret:server_password]，則必須建立名為​ server_password ​的文字檔。 所有這些機密檔案必須儲存在相同的目錄中，而且架構屬性org.apache.felix.configadmin.plugin.interpolation.secretsdir必須設定為該本機目錄。

org.apache.felix.configadmin.plugin.interpolation.secretsdir是Sling架構屬性；因此此屬性不是在felix主控台(https://experienceleague.adobe.com/system/console?lang=zh-Hant)中設定，而是在系統啟動時使用的sling.properties檔案中設定。 此檔案可在解壓縮的Jar/install資料夾(crx-quickstart/conf)的/conf子目錄中找到。

範例：將此行新增到「crx-quickstart/conf/sling.properties」檔案的結尾以將「crx-quickstart/secretsdir」設定為機密資料夾：

org.apache.felix.configadmin.plugin.interpolation.secretsdir=${sling.home}/secretsdir

作者與Publish設定 author-vs-publish-configuration

如果OSGi屬性對author和publish需要不同的值：

設定範例 configuration-examples

在以下範例中，假設除了舞台和生產環境外，還有三個開發環境。

範例 1

目的是讓OSGi屬性my_var1的值在階段和生產環境中相同，但三個開發環境的每一個不同。

{
 "my_var1"： "val"，
 "my_var2"： "abc"，
 "my_var3"：500
}

{
 "my_var1" ： "$[env：my_var1]"
 "my_var2"： "abc"，
 "my_var3"：500
}

範例 2

目的是讓OSGi屬性my_var1的值在階段、生產以及三個開發環境的每一個中有所不同。 因此，必須呼叫Cloud Manager API來為每個開發環境設定my_var1的值。

{
 "my_var1"： "val1"，
 "my_var2"： "abc"，
 "my_var3"：500
}

{
 "my_var1"： "val2"，
 "my_var2"： "abc"，
 "my_var3"：500
}

{
 "my_var1" ： "$[env：my_var1]"
 "my_var2"： "abc"，
 "my_var3"：500
}

範例 3

目的是為了讓OSGi屬性my_var1的值在暫存、生產及其中一個開發環境中相同，但在其他兩個開發環境中不同。 在此情況下，必須呼叫Cloud Manager API來為每個開發環境設定my_var1的值，包括應具有與中繼和生產環境相同值的開發環境。 它不會繼承資料夾​ config ​中設定的值。

{
 "my_var1"： "val1"，
 "my_var2"： "abc"，
 "my_var3"：500
}

{
 "my_var1" ： "$[env：my_var1]"
 "my_var2"： "abc"，
 "my_var3"：500
}

完成此任務的另一種方法是為config.dev資料夾中的取代權杖設定預設值，使其與​ config ​資料夾中的值相同。

{
 "my_var1"： "val1"，
 "my_var2"： "abc"，
 "my_var3"：500
}

{
 "my_var1"： "$[env：my_var1；default=val1]"
 "my_var2"： "abc"，
 "my_var3"：500
}

用於設定屬性的Cloud Manager API格式 cloud-manager-api-format-for-setting-properties

如需Cloud Manager API的相關資訊以及設定方式，請參閱在Adobe Developer網站上AdobeCloud Manager 。

透過API設定值 setting-values-via-api

呼叫API會將新變數和值部署至雲端環境，類似於典型的客戶程式碼部署管道。 作者和發佈服務會重新啟動，並參考新值，通常需要幾分鐘的時間。

PATCH /program/{programId}/environment/{environmentId}/variables

[
        {
                "name" : "MY_VAR1",
                "value" : "plaintext value",
                "type" : "string"  <---default
        },
        {
                "name" : "MY_VAR2",
                "value" : "<secret value>",
                "type" : "secretString"
        }
]

透過API取得值 getting-values-via-api

GET /program/{programId}/environment/{environmentId}/variables

如需詳細資訊，請參閱Cloud Manager API。

透過API刪除值 deleting-values-via-api

PATCH /program/{programId}/environment/{environmentId}/variables

若要刪除變數，請將其納入空白值。

如需詳細資訊，請參閱Cloud Manager API。

透過命令列取得值 getting-values-via-cli

$ aio cloudmanager:list-environment-variables ENVIRONMENT_ID
Name     Type         Value
MY_VAR1  string       plaintext value
MY_VAR2  secretString ****

透過命令列設定值 setting-values-via-cli

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --variable MY_VAR1 "plaintext value" --secret MY_VAR2 "some secret value"

透過命令列刪除值 deleting-values-via-cli

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --delete MY_VAR1 MY_VAR2

變數數量 number-of-variables

每個環境最多可以宣告200個變數。

秘密和環境特定設定值的部署考量事項 deployment-considerations-for-secret-and-environment-specific-configuration-values

由於機密和特定環境的設定值位於Git之外，因此不屬於正式的Adobe Experience Manager as a Cloud Service部署機制，因此客戶應管理、控管並整合至Adobe Experience Manager as a Cloud Service部署程式。

如上所述，呼叫API會將新變數和值部署到雲端環境，類似於典型的客戶程式碼部署管道。 作者和發佈服務會重新啟動，並參考新值，通常需要幾分鐘的時間。 在此過程中，Cloud Manager在定期程式碼部署期間執行的品質閘道和測試不會執行。

通常，客戶在部署在Cloud Manager中依賴環境變數的程式碼之前，會呼叫API來設定環境變數。 在某些情況下，您可能想要在部署程式碼後修改現有變數。

在某些情況下，已排程的客戶程式碼部署會依賴現有變數來擁有新值，而這對目前的程式碼而言是不合適的。 如果這令人擔憂，建議以累加方式進行變數修改。 若要這麼做，請建立新的變數名稱，而非只變更舊變數的值，讓舊程式碼絕不會參考新值。 然後，當新的客戶版本看起來穩定時，您可以選擇移除舊的值。

同樣地，由於變數的值未建立版本，程式碼復原可能會導致它參考較新的值，進而導致問題。 前述的加法變數策略在此也有幫助。

此附加變數策略也適合用於需要重新部署數天前程式碼的災害復原情況，其參照的變數名稱和值將維持不變。 這有賴於客戶在移除這些舊版變數前會等待數天的策略，否則舊版程式碼將沒有適當的變數可參照。