使用內容類型以將 JSON 索引鍵值儲存在應用程式組態

發行項
04/09/2024

資料會在應用程式組態儲存為索引鍵值，其中預設會將值視為字串類型。不過，您可以使用與每個索引鍵值相關的內容類型屬性來指定自訂類型。此流程會保留您資料的原始類型，或讓應用程式根據內容類型以不同的方式運作。

概觀

在應用程式組態中，您可以將 JSON 媒體類型當作索引鍵/值的內容類型使用，以取得下列優勢：

更簡易的資料管理：管理索引鍵值，例如在 Azure 入口網站中管理陣列將會變得更容易。
增強型資料匯出：在資料匯出期間將會保留基本類型、陣列及 JSON 物件。
與應用程式組態提供者搭配運作的原生支援：當應用程式中應用程式組態提供者程式庫取用時，具有 JSON 內容類型的索引鍵值將會正常運作。

有效的 JSON 內容類型

此處定義的媒體類型可以指派給與每個索引鍵值相關的內容類型。媒體類型由類型和子類型組成。如果類型為 application，且子類型 (或後置詞) 為 json，媒體類型將會被視為有效的 JSON 內容類型。一些有效的 JSON 內容類型範例如下：

application/json
application/activity+json
application/vnd.foobar+json;charset=utf-8

有效的 JSON 值

當索引鍵值具有 JSON 內容類型時，其值必須使用有效的 JSON 格式，用戶端電腦才能以正確方始處理。否則，用戶端電腦可能會失敗或回復，並將其視為字串格式。一些有效的 JSON 值範例如下：

"John Doe"
723
false
null
"2020-01-01T12:34:56.789Z"
[1, 2, 3, 4]
{"ObjectSetting":{"Targeting":{"Default":true,"Level":"Information"}}}

注意

在本文的其餘部分，應用程式組態中具有有效的 JSON 內容類型和有效的 JSON 值的任何索引鍵值都會稱為 JSON 索引鍵值。

在本教學課程中，您將了解如何：

在應用程式組態中建立 JSON 索引鍵值。
從 JSON 檔案匯入 JSON 索引鍵值。
將 JSON 索引鍵值匯出至 JSON 檔案。
在您的應用程式中取用 JSON 索引鍵值。

如果您沒有 Azure 訂閱，請在開始之前，先建立 Azure 免費帳戶。

必要條件

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

應用程式組態存放區。建立存放區。
本教學課程需要 2.10.0 版或更新版本的 Azure CLI。如果您是使用 Azure Cloud Shell，就已安裝最新版本。

在應用程式組態中建立 JSON 機碼值

您可以使用 Azure 入口網站、Azure CLI 或從 JSON 檔案匯入來建立 JSON 索引鍵值。在本節中，您會見到如何使用這三種方法建立相同 JSON 索引鍵值的指示。

使用 Azure 入口網站來建立 JSON 機碼值

將下列金鑰值新增至應用程式組態存放區。保留 [標籤] 與其預設值。如需如何使用 Azure 入口網站或 CLI 將金鑰值新增至存放區的詳細資訊，請移至建立金鑰值。

機碼	值	內容類型
Settings:BackgroundColor	"Green"	application/json
Settings:FontSize	24	application/json
Settings:UseDefaultRouting	false	application/json
Settings:BlockedUsers	null	application/json
Settings:ReleaseDate	"2020-08-04T12:34:56.789Z"	application/json
Settings:RolloutPercentage	[25,50,75,100]	application/json
Settings:Logging	{"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}}	application/json

選取套用。

使用 Azure CLI 來建立 JSON 機碼值

下列命令將會在應用程式組態存放區中建立 JSON 機碼值。將 <appconfig_name> 取代為您應用程式組態存放區的名稱。

appConfigName=<appconfig_name>
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:BackgroundColor --value \"Green\"
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:FontSize --value 24
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:UseDefaultRouting --value false
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:BlockedUsers --value null
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:ReleaseDate --value \"2020-08-04T12:34:56.789Z\"
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:RolloutPercentage --value [25,50,75,100]
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:Logging --value {\"Test\":{\"Level\":\"Debug\"},\"Prod\":{\"Level\":\"Warning\"}}

重要

如果您使用 Azure CLI 或 Azure Cloud Shell 來建立 JSON 索引鍵值，則所提供的值必須是逸出 JSON 字串。

從檔案匯入 JSON 機碼值

使用下列內容建立名為 Import.json 的 JSON 檔案，並將其以索引鍵值形式匯入應用程式組態：

{
  "Settings": {
    "BackgroundColor": "Green",
    "BlockedUsers": null,
    "FontSize": 24,
    "Logging": {"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}},
    "ReleaseDate": "2020-08-04T12:34:56.789Z",
    "RolloutPercentage": [25,50,75,100],
    "UseDefaultRouting": false
  }
}

az appconfig kv import -s file --format json --path "~/Import.json" --content-type "application/json" --separator : --depth 2

注意

--depth 引數用於將檔案中的階層式資料壓平合併成索引鍵值。在本教學課程中，指定了深度來示範您也可以將 JSON 物件儲存為應用程式組態中的值。如果未指定深度，JSON 物件因預設會壓平合併為最深層級。

您建立的 JSON 機碼值在應用程式組態中看起來應該如下：

Screenshot that shows the Config store containing JSON key-values.

若要檢查這點，請在 Azure 入口網站中開啟您的 [應用程式組態] 資源，然後移至 [組態總管]。

將 JSON 機碼值匯出至檔案

使用 JSON 機碼值的主要優勢之一，是在匯出時可以保留值的原始資料類型。如果應用程式組態中的索引鍵值沒有包含 JSON 內容類型，則會將其值視為字串。

請考慮下列不含 JSON 內容類型的索引鍵值：

機碼	值	內容類型
Settings:FontSize	24
Settings:UseDefaultRouting	false

當您將這些機碼值匯出至 JSON 檔案時，該值將會以字串形式匯出：

{
  "Settings": {
    "FontSize": "24",
    "UseDefaultRouting": "false"
  }
}

不過，當您將 JSON 機碼值匯出至檔案時，所有值都會保留其原始資料類型。若要確認此流程，請將索引鍵值從您的應用程式組態匯出至 JSON 檔案。您將會看到匯出的檔案的內容與您先前匯入的 Import.json 檔案相同。

az appconfig kv export -d file --format json --path "~/Export.json" --separator :

注意

如果您的應用程式組態存放區存在無具備 JSON 內容類型的索引鍵值，其也會以字串格式匯出至相同的檔案。

在應用程式中取用 JSON 機碼值

若要在應用程式中取用 JSON 機碼值，透過應用程式組態提供者程式庫是最簡易的方式。使用提供者程式庫時，您不需要在應用程式中實作 JSON 機碼值的特殊處理。其將會經過剖析和轉換，以符合應用程式的原生設定。

例如，如果您在應用程式組態中有下列機碼值：

機碼	值	內容類型
設定	{"FontSize":24,"UseDefaultRouting":false}	application/json

您 .NET 應用程式組態的機碼值將會如下列所示：

機碼	值
Settings:FontSize	24
Settings:UseDefaultRouting	false

您可以直接存取新的金鑰，或者您可以選擇將設定值繫結至 .NET 物件的執行個體。

重要

.NET 組態提供者 4.0.0 版 (或更新版本) 提供 JSON 機碼值的原生支援。如需詳細資訊，請前往後續步驟一節。

如果您使用 SDK 或 REST API，根據內容類型從應用程式組態讀取索引鍵值，您的應用程式會負責剖析 JSON 索引鍵值的值。

清除資源

如果您不想繼續使用本文中建立的資源，請刪除在此處建立的資源群組，以避免產生費用。

重要

刪除資源群組是無法回復的動作。資源群組和其中的所有資源都將被永久刪除。請確定您不會誤刪錯誤的資源群組或資源。如果您是在包含需保留其他資源的資源群組內部，建立本文的資源，則可以從每個資源各自的窗格中個別刪除每個資源，而不必刪除整個資源群組。

登入 Azure 入口網站，然後選取 [資源群組]。
在 [依名稱篩選] 方塊中，輸入您資源群組的名稱。
在結果清單中，選取資源群組名稱以查看概觀。
選取 [刪除資源群組]。
系統將會要求您確認是否刪除資源群組。輸入您資源群組的名稱以進行確認，然後選取 [刪除]。

不久後，系統便會刪除該資源群組及其所有的資源。

下一步

既然您已了解如何在應用程式組態存放區中使用 JSON 機碼值，請建立應用程式來取用這些機碼值：

ASP.NET Core 快速入門

.NET Core 快速入門

Share via