使用就地移轉功能將 App Service 環境 v1 和 v2 移轉至 App Service 環境 v3
注意
本文所述的移轉功能會用於將 App Service 環境 v1 和 v2 自動就地 (相同子網路) 移轉至 App Service 環境 v3。 如果您要在並存移轉功能上尋找資訊，請參閱使用並存移轉功能移轉至 App Service 環境 v3。 如果您要尋找手動移轉選項的相關資訊，請參閱手動移轉選項。 如需有助於決定適合您移轉選項的說明，請參閱移轉路徑決策樹。 如需 App Service 環境 v3 的詳細資訊，請參閱 App Service 環境 v3 概觀。
您可以使用就地移轉功能，自動將 App Service 環境 v1 和 v2 移轉至 App Service 環境 v3。 若要深入了解移轉流程，以及查看您的 App Service 環境目前是否支援移轉，請參閱就地移轉功能的概觀。
重要
建議您先將此功能用於開發環境，再移轉任何生產環境，以避免發生非預期的問題。 請使用頁面底部的按鈕，提供與本文或功能相關的任何意見反應。
必要條件
確保您了解移轉至 App Service 環境 v3 如何影響您的應用程式。 檢閱移轉流程，以了解流程時間軸，以及何時何處需要您參與。 另請檢閱常見問題集，其可回答您的一些問題。
確保您的虛擬網路、資源群組、資源或訂用帳戶上沒有任何鎖定。 鎖定會在移轉期間封鎖平台作業。
確保沒有任何 Azure 原則會封鎖移轉所需的動作，包括子網路修改和 Azure App Service 資源建立。 封鎖資源修改和建立的原則可能會導致移轉停滯或失敗。
移轉期間會封鎖調整規模，因此您應該在開始移轉之前，將環境調整為所需的大小。 如果您需要在移轉之後調整環境，您可以在移轉完成後執行此動作。
建議您使用 Azure 入口網站以進行就地移轉體驗。 如果您決定使用 Azure CLI 進行移轉，請遵循此處所述的步驟，並依照撰寫的內容依序進行，因為您正在進行 Azure REST API 呼叫。 建議您使用 Azure CLI 進行這些 API 呼叫。 如需其他方法的相關資訊，請參閱 Azure REST API 參考。
針對本指南， 請安裝 Azure CLI 或使用 Azure Cloud Shell ，並使用 Bash 殼層。
注意
建議您使用 Bash 殼層來執行本指南中提供的命令。 命令可能與 PowerShell 慣例和逸出字元不相容。
1.取得您的 App Service 環境識別碼
執行下列命令來取得您的 App Service 環境識別碼，並將其儲存為環境變數。 將名稱和資源群組的預留位置取代為您所要移轉 App Service 環境的值。 如果您的虛擬網路和 App Service 環境位於相同的資源群組中，則 ASE_RG 和 VNET_RG 會相同。
ASE_NAME=<Your-App-Service-Environment-name>
ASE_RG=<Your-ASE-Resource-Group>
VNET_RG=<Your-VNet-Resource-Group>
ASE_ID=$(az appservice ase show --name $ASE_NAME --resource-group $ASE_RG --query id --output tsv)
2.驗證是否支援移轉
下列命令會檢查是否支援您的 App Service 環境進行移轉。 如果您收到錯誤，或如果您的 App Service 環境處於狀況不良或暫停狀態，則目前無法移轉。 如需您可能會收到的潛在錯誤訊息描述，請參閱疑難排解一節。 如果您的環境不支援使用就地移轉功能移轉，或您想要在不使用就地移轉功能的情況下移轉至 App Service 環境 v3，請參閱手動移轉選項。 此命令也會驗證您的 App Service 環境 是否位於支援的組建版本以進行移轉。 如果您的 App Service 環境 不在支援的組建版本上，您必須自行開始升級，視環境的大小而定，可能需要 8-12 小時或更長的時間。 如需預先移轉升級的詳細資訊，請參閱使用您 App Service 環境 的就地移轉功能驗證是否支援移轉。
az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=validation"
如果沒有錯誤，則支援您的移轉，而且您可以繼續進行下一個步驟。
如果您需要開始升級，將 App Service 環境 升級至支援的組建版本，請執行下列命令。 只有在驗證步驟失敗，並指示升級您的 App Service 環境 時，才執行此命令。
az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=PreMigrationUpgrade"
3.為您的新 App Service 環境 v3 資源產生 IP 位址
執行下列命令以建立新的 IP 位址。 此步驟約需要 15 分鐘來完成。 請不要在這段時間調整或變更您現有的 App Service 環境。
az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=premigration"
執行下列命令檢查此步驟的狀態：
az rest --method get --uri "${ASE_ID}?api-version=2021-02-01" --query properties.status
如果步驟進行中，您會取得 Migrating 的狀態。 取得 Ready 的狀態之後，執行下列命令來檢視新的 IP。 如果您沒有立即看到新的 IP，請稍候幾分鐘，然後再試一次。
az rest --method get --uri "${ASE_ID}/configurations/networking?api-version=2021-02-01"
注意
由於已知錯誤，針對 ELB App Service 環境 移轉，輸入 IP 位址可能會在移轉步驟完成之後再次變更。 準備在移轉步驟完成之後，使用新的輸入IP位址再次更新相依資源。 正在處理這個 Bug，並會儘快修正。 如果您有此問題的任何問題或疑慮，或需要移轉程式的協助，請開啟支援案例。
4.使用新的 IP 更新相依資源
使用新的 IP，更新您的任何資源或網路元件，以確保新的環境功能在移轉完成後如預期般運作。 進行任何必要的更新，這是您的責任。
此步驟也是在移至 App Service 環境 v3 時檢閱輸入和輸出網路相依性變更的好時機。 這些變更包括 Azure Load Balancer 的連接埠變更，其現在會使用連接埠 80。 在完成此步驟之前，請勿移轉。
5.委派您的 App Service 環境子網路
App Service 環境 v3 需要其所位在的子網路具有 Microsoft.Web/hostingEnvironments 的單一委派。 舊版不需要此委派。 您必須確認已正確委派子網路，並在移轉之前更新委派 (如必要)。 您可以執行下列命令或移至 Azure 入口網站中的子網路來更新委派。
az network vnet subnet update --resource-group $VNET_RG --name <subnet-name> --vnet-name <vnet-name> --delegations Microsoft.Web/hostingEnvironments
6.確認虛擬網路上沒有鎖定
虛擬網路鎖定將會在移轉期間封鎖平台作業。 如果虛擬網路具有鎖定，則您需要先將其移除，才能進行移轉。 如有必要，您可以在移轉完成後再新增鎖定。
鎖定可以存在於三個範圍：訂用帳戶、資源群組和資源。 當您在父範圍套用鎖定時，該範圍內的所有資源都會都繼承相同的鎖定。 如果您已在訂用帳戶、資源群組或資源範圍套用鎖定，則需要在移轉之前移除。 如需鎖定和鎖定繼承的詳細資訊，請參閱鎖定您的資源以保護基礎結構。
使用下列命令來檢查您的虛擬網路是否具有任何鎖定：
az lock list --resource-group $VNET_RG --resource <vnet-name> --resource-type Microsoft.Network/virtualNetworks
使用下列命令來刪除任何現有的鎖定：
az lock delete --resource-group $VNET_RG --name <lock-name> --resource <vnet-name> --resource-type Microsoft.Network/virtualNetworks
如需檢查訂用帳戶或資源群組是否具有鎖定的相關命令，請參閱鎖定的 Azure CLI 參考。
7.準備您的設定
如果您的現有環境位於支援區域備援的區域，您可以讓新的 App Service 環境 v3 資源區域做為備援。 您可以將 zoneRedundant 屬性設定為 true，以設定區域備援。
區域備援是選擇性設定。 您只能在建立新的 App Service 環境 v3 資源期間加以設定。 您稍後無法將其移除。 如需詳細資訊，請參閱選擇您的 App Service 環境 v3 設定。 如果您不想設定區域備援，則請勿包含 zoneRedundant 參數。
如果您的現有 App Service 環境使用自訂網域尾碼，您必須在移轉程序期間，為新的 App Service 環境 v3 資源設定自訂網域尾碼。 如果您未設定自訂網域尾碼，且目前使用一個自訂網域尾碼，移轉會失敗。 如果您嘗試在移轉期間將自訂網域尾碼新增至未設定網域的環境，則移轉也會失敗。 如需關於 App Service 環境 v3 自訂網域尾碼的詳細資訊，包括需求、逐步指示和最佳做法，請參閱 App Service 環境的自訂網域尾碼。
注意
如果您要設定自訂網域尾碼，當您在 Azure Key Vault 上新增網路權限時，請確定您的金鑰保存庫允許從您在步驟 3 中產生的 App Service 環境的新輸出 IP 位址存取。 如果您使用私人端點存取金鑰保存庫，請確定您已正確設定私人存取。
如果您的移轉不包含自訂網域尾碼，且您未啟用區域備援，則您可以繼續進行移轉。
若要進行這些設定，請根據您的案例，使用下列詳細資料建立名為 parameters.json 的檔案。 如果此功能不適合您的移轉，則請勿包含自訂網域尾碼屬性。 注意 zoneRedundant 屬性的值，因為此設定在移轉之後無法復原。 根據您現有的App Service 環境版本來設定 kind 屬性的值。 kind 屬性可接受的值為 ASEV1 和 ASEV2。
如果您要在不使用自訂網域尾碼並且啟用區域備援的情況下進行移轉，請使用此程式碼：
{
"type": "Microsoft.Web/hostingEnvironments",
"name": "sample-ase-migration",
"kind": "ASEV2",
"location": "westcentralus",
"properties": {
"zoneRedundant": true
}
}
如果您要針對您的自訂網域尾碼設定使用使用者指派的受控識別，並且啟用區域備援，請使用此程式碼：
{
"type": "Microsoft.Web/hostingEnvironments",
"name": "sample-ase-migration",
"kind": "ASEV2",
"location": "westcentralus",
"properties": {
"zoneRedundant": true,
"customDnsSuffixConfiguration": {
"dnsSuffix": "internal.contoso.com",
"certificateUrl": "https://contoso.vault.azure.net/secrets/myCertificate",
"keyVaultReferenceIdentity": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/asev3-migration/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ase-managed-identity"
}
}
}
如果您要針對您的自訂網域尾碼設定使用系統指派的受控識別，並且不要啟用區域備援，請使用此程式碼：
{
"type": "Microsoft.Web/hostingEnvironments",
"name": "sample-ase-migration",
"kind": "ASEV2",
"location": "westcentralus",
"properties": {
"customDnsSuffixConfiguration": {
"dnsSuffix": "internal.contoso.com",
"certificateUrl": "https://contoso.vault.azure.net/secrets/myCertificate",
"keyVaultReferenceIdentity": "SystemAssigned"
}
}
}
8.移轉至 App Service 環境 v3 並檢查狀態
完成上述所有步驟之後，您就可以開始移轉。 請確定您了解移轉的影響。
此步驟最多需要三到六小時才能將 v2 移轉到 v3，以及最多需要六小時才能將 v1 移轉到 v3，視環境大小而定。 在該期間，應用程式大約會有一小時的停機。 在此步驟期間，將會封鎖對現有 App Service 環境的調整、部署和修改。
如果您要啟用區域備援和/或設定自訂網域尾碼，則在下列命令中包含 body 參數。 如果這兩個設定都不適合您的移轉，您可以從命令中移除參數。
az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=fullmigration" --body @parameters.json
執行下列命令來檢查移轉的詳細狀態。 如需狀態的詳細資訊，請參閱移轉狀態描述。
第一個命令會取得移轉的作業識別碼。 複製 ID 屬性的值。
az rest --method get --uri "${ASE_ID}/operations?api-version=2022-03-01"
將下列命令中作業識別碼的預留位置取代為您複製的值。 此命令會傳回移轉的詳細狀態。 您可以視需要執行此命令，以取得最新的狀態。
az rest --method get --uri "${ASE_ID}/operations/<operation-id>/details/default?api-version=2022-09-01"
取得 Ready 狀態之後，移轉即已完成，且您會有 App Service 環境 v3 資源。 您的應用程式現在正在您的新環境中執行。
執行下列命令或移至 Azure 入口網站，以取得新環境的詳細資料。
az appservice ase show --name $ASE_NAME --resource-group $ASE_RG
注意
由於已知錯誤，ELB App Service 環境 移轉，輸入IP位址可能會在移轉步驟完成之後變更。 檢查 v3 的IP位址 App Service 環境，並在IP產生步驟之後發生變更時進行任何必要的更新。 如果您有此問題的任何問題或疑慮，或需要確認新IP的協助，請開啟支援案例。
1.驗證是否支援移轉
在 Azure 入口網站中，移至您要移轉的 App Service 環境的 [移轉] 頁面。 您可以選取 App Service 環境 [概觀] 頁面頂端的橫幅，或選取左側功能表上的 [移轉] 項目，以移至 [移轉] 頁面。
在 [移轉] 頁面上，平台會驗證是否支援您的 App Service 環境進行移轉。 選取 [驗證]，然後確認您要繼續進行驗證。 驗證程序需要幾秒鐘的時間。
如果不支援您的環境進行移轉，橫幅會出現在頁面頂端，並包括錯誤訊息與原因。 如需在您不符合移轉資格時會出現的錯誤訊息描述，請參閱疑難排解。
如果您目前不支援 App Service 環境進行移轉，或您的環境處於狀況不良或暫停狀態，將無法使用移轉功能。 如果您的環境不支援使用就地移轉功能移轉，或您想要在不使用就地移轉功能的情況下移轉至 App Service 環境 v3，請參閱手動移轉選項。
如果您需要開始升級，將 App Service 環境 升級至支援的組建版本，系統會提示您啟動升級，視環境大小而定，可能需要 8-12 小時或更長的時間。 選取 [ 升級 ] 以開始升級。 升級完成時，您可以通過驗證，並使用移轉功能來開始移轉。
如果支援您的 App Service 環境進行移轉，請繼續進行流程中的下一個步驟。 [移轉] 頁面會透過一系列步驟引導您完成移轉。
2.為您的新 App Service 環境 v3 資源產生 IP 位址
在 [取得新的 IP 位址] 底下，確認您了解含意，然後選取 [開始] 按鈕。 此步驟約需要 15 分鐘來完成。 您無法在此期間調整或變更您現有的 App Service 環境。
3.使用新的 IP 更新相依資源
當上一個步驟完成時，將顯示新 App Service 環境 v3 資源的 IP 位址。 使用新的 IP 來更新任何資源和網路元件，使得新的環境功能在移轉完成後如預期般運作。 進行任何必要的更新，這是您的責任。
此步驟也是在移至 App Service 環境 v3 時檢閱輸入和輸出網路相依性變更的好時機。 這些變更包括 Azure Load Balancer 的連接埠變更，其現在會使用連接埠 80。 在您確認已進行這些更新之前，請勿移至下一個步驟。
4.委派您的 App Service 環境子網路
App Service 環境 v3 需要其所位在的子網路具有 Microsoft.Web/hostingEnvironments 的單一委派。 舊版不需要此委派。 您必須確認已正確委派子網路，並在移轉之前更新委派 (如必要)。 入口網站會顯示子網路的連結，以便您可以確認並視需要更新。
5.確認執行個體大小變更
您的 App Service 方案會從隔離式轉換為對應的隔離式 v2 層。 例如，I2 會轉換成 I2v2。 應用程式可能會在移轉後過度佈建，因為隔離式 v2 層對於每個對應的執行個體大小具有更多記憶體和 CPU。 移轉完成後，您將有機會視需要調整環境。 如需詳細資訊，請檢閱價格詳細資料。
6.確認虛擬網路沒有鎖定
虛擬網路鎖定將會在移轉期間封鎖平台作業。 如果虛擬網路具有鎖定，則您需要先將其移除，才能進行移轉。 如有必要，您可以在移轉完成後再新增鎖定。
鎖定可以存在於三個範圍：訂用帳戶、資源群組和資源。 當您在父範圍套用鎖定時，該範圍內的所有資源都會都繼承相同的鎖定。 如果您已在訂用帳戶、資源群組或資源範圍套用鎖定，則需要在移轉之前移除。 如需鎖定和鎖定繼承的詳細資訊，請參閱鎖定您的資源以保護基礎結構。
如需如何檢查訂用帳戶或資源群組是否具有鎖定的詳細資料，請參閱設定鎖定。
7.選擇您的設定
如果您的現有環境位於支援區域備援的區域，您可以讓新的 App Service 環境 v3 資源區域做為備援。 區域備援是選擇性設定。 您只能在建立新的 App Service 環境 v3 資源期間加以設定。 您稍後無法將其移除。 如需詳細資訊，請參閱選擇您的 App Service 環境 v3 設定。
如果要設定區域備援，請選取 [已啟用] 核取方塊。
如果您的環境位於不支援區域備援的區域，該核取方塊就會停用。 如果您需要區域備援 App Service 環境 v3 資源，請使用其中一個手動移轉選項，並在支援區域備援的其中一個區域中建立該資源。
如果您的現有 App Service 環境使用自訂網域尾碼，則必須為新的 App Service 環境 v3 資源設定自訂網域尾碼。 如果此情況適合您，則會出現用於自訂網域尾碼的設定選項。 在提供必要資訊之前，您無法移轉。
如果您要使用自訂網域尾碼，但目前尚未設定尾碼，則您可以在移轉完成後設定一個自訂網域尾碼。 如需關於 App Service 環境 v3 自訂網域尾碼的詳細資訊，包括需求、逐步指示和最佳做法，請參閱 App Service 環境的自訂網域尾碼。
注意
如果您要設定自訂網域尾碼，當您在 Azure Key Vault 上新增網路權限時，請確定您的金鑰保存庫允許從您在步驟 2 中產生的 App Service 環境的新輸出 IP 位址存取。 如果您使用私人端點存取金鑰保存庫，請確定您已正確設定私人存取。
新增自訂網域尾碼的詳細資料之後，即可使用 [移轉] 按鈕。
8.移轉至 App Service 環境 v3
完成上述所有步驟之後，您就可以開始移轉。 確定您了解移轉的影響，包括這段時間會發生什麼情況。
此步驟最多需要三到六小時才能將 v2 移轉到 v3，以及最多需要六小時才能將 v1 移轉到 v3，視環境大小而定。 在此步驟期間，將會封鎖對現有 App Service 環境的調整和修改。
注意
在罕見的情況下，開始移轉之後，您可能會在入口網站中看到「移轉至 App Service 環境 v3 失敗」的通知。 有一個已知的錯誤，即使移轉正在進行，也有可能觸發此通知。 檢查 App Service 環境的活動記錄檔，以判斷此錯誤訊息的有效性。 在大部分情況下，重新整理頁面可解決問題，且錯誤訊息會消失。 如果錯誤訊息持續發生，請連絡支援人員以尋求協助。
目前，只有當您使用 Azure CLI 時，才能取得詳細的移轉狀態。 如需詳細資訊，請參閱移轉至 App Service 環境 v3 的 Azure CLI 小節。 即使使用入口網站執行移轉，您也可以使用 CLI 檢查移轉的狀態。
移轉完成時，您會具有 App Service 環境 v3 資源，而且您的所有應用程式都會在新環境中執行。 您可以檢查 App Service 環境的 [設定] 頁面，以確認環境的版本。
注意
由於已知錯誤，ELB App Service 環境 移轉，輸入IP位址可能會在移轉步驟完成之後變更。 請檢查您的 App Service 環境 v3 IP 位址，並在IP產生步驟之後發生變更時進行任何必要的更新。 如果您有此問題的任何問題或疑慮，或需要確認新IP的協助，請開啟支援案例。
如果您的移轉包含自定義網域後綴，則網域會出現在入口網站 App Service 環境 v1/v2 的 [概觀] 頁面的 [基本資訊] 區段中，但 App Service 環境 v3 中不再出現。 相反地，針對 App Service 環境 v3，請移至 [自訂網域尾碼] 頁面，以確認已正確設定自訂網域尾碼。 如果您不再需要該設定，也可以將設定移除，或如果您先前沒有設定，則可進行設定。
注意
如果您的移轉包含自定義網域後綴，您的自定義網域後綴組態可能會在移轉完成後顯示為降級，因為已知錯誤。 您的 App Service 環境 仍應如預期般運作。 降級的狀態應該會在 6-8 小時內自行解決。 如果設定在8小時后降級，或您的自定義網域後綴無法運作，請連絡支持人員。
