Come implementare il ripristino di emergenza usando il backup e il ripristino dei servizi in Gestione API di Azure

SI APPLICA A: Sviluppatore | Basic | Standard | Premium

Pubblicando e gestendo le API tramite Gestione API di Azure è possibile sfruttare funzionalità di tolleranza di errore e di infrastruttura che sarebbe altrimenti necessario progettare, implementare e gestire manualmente. La piattaforma di Azure permette di mitigare una vasta gamma di potenziali errori a un costo nettamente inferiore.

Per risolvere i problemi di disponibilità che interessano il servizio Gestione API, è possibile ricostituire il servizio in un'altra area in qualsiasi momento. A seconda dell'obiettivo del tempo di ripristino, è possibile mantenere un servizio di standby in una o più aree. È anche possibile provare a mantenere la configurazione e il contenuto sincronizzati con il servizio attivo in base all'obiettivo del punto di ripristino. Le funzionalità di backup e ripristino di Gestione API forniscono i blocchi predefiniti necessari per implementare la strategia di ripristino di emergenza.

Le operazioni di backup e ripristino possono essere usate anche per replicare la configurazione del servizio Gestione API tra ambienti operativi, ad esempio sviluppo e gestione temporanea. Tenere presente che verranno copiati anche i dati di runtime, ad esempio utenti e sottoscrizioni, che potrebbero non essere sempre auspicabili.

Questo articolo illustra come automatizzare le operazioni di backup e ripristino dell'istanza di Gestione API usando un account di archiviazione esterno. I passaggi illustrati di seguito usano i cmdlet di Azure PowerShell Backup-AzApi Management e Restore-AzApiManagement, oppure il servizio Gestione API - Backup e le API REST Servizio Gestione API - Ripristinare.

Avviso

Ogni backup scade dopo 30 giorni. Se si tenta di ripristinare un backup dopo la scadenza del periodo di 30 giorni, il ripristino avrà esito negativo e verrà visualizzato il messaggio Cannot restore: backup expired.

Importante

L'operazione di ripristino non modifica la configurazione del nome host personalizzato del servizio di destinazione. È consigliabile usare lo stesso nome host personalizzato e lo stesso certificato TLS per i servizi attivi e standby, in modo che, dopo il completamento dell'operazione di ripristino, il traffico possa essere reindirizzato all'istanza di standby da una semplice modifica di CNAME DNS.

Nota

È consigliabile usare il modulo Azure Az PowerShell per interagire con Azure. Per iniziare, vedere Installare Azure PowerShell. Per informazioni su come eseguire la migrazione al modulo AZ PowerShell, vedere Eseguire la migrazione di Azure PowerShell da AzureRM ad Az.

Prerequisiti

• Istanza del servizio Gestione API. Se non è disponibile, vedere Creare un'istanza del servizio Gestione API.

• Un account di archiviazione di Azure. Se non è disponibile, vedere Creare un account di archiviazione.

  • Creare un contenitore nell'account di archiviazione per contenere i dati di backup.

• La versione più recente di Azure PowerShell, se si prevede di usare i cmdlet di Azure PowerShell. Se non è già stato fatto, installare Azure PowerShell.

Configurare l'accesso all'account di archiviazione

Quando si esegue un'operazione di backup o ripristino, è necessario configurare l'accesso all'account di archiviazione. Gestione API supporta due meccanismi di accesso alle risorse di archiviazione: una chiave di accesso di Archiviazione di Azure o un'identità gestita di Gestione API.

Configurare la chiave di accesso dell'account di archiviazione

Azure genera due chiavi di accesso dell'account di archiviazione a 512 bit per ogni account di archiviazione. Queste chiavi possono essere usate per autorizzare l'accesso ai dati nell'account di archiviazione tramite l'autorizzazione con chiave condivisa. Per visualizzare, recuperare e gestire le chiavi, vedere Gestire le chiavi di accesso dell'account di archiviazione.

Configurare l'identità gestita di Gestione API

Nota

L'uso di un'identità gestita di Gestione API per le operazioni di archiviazione durante il backup e il ripristino è supportato nella versione dell'API REST di Gestione API 2021-04-01-preview o versione successiva.

1. Abilitare un'identità gestita assegnata dal sistema o assegnata dall'utente per Gestione API nell'istanza di Gestione API.

   • Se si abilita un'identità gestita assegnata dall'utente, prendere nota dell'ID client dell'identità.
   • Se si esegue il backup e il ripristino in istanze di Gestione API diverse, abilitare un'identità gestita nelle istanze di origine e di destinazione.

2. Assegnare l'identità al ruolo Collaboratore ai dati dei BLOB di archiviazione, con ambito per l'account di archiviazione usato per il backup e il ripristino. Per assegnare il ruolo, usare il portale di Azure o altri strumenti di Azure.

Backup di un servizio di Gestione API

PowerShell

Accedere con Azure PowerShell.

Negli esempi seguenti:

• Un'istanza di Gestione API denominata myapim si trova nel gruppo di risorse apimresourcegroup.
• Un account di archiviazione denominato backupstorageaccount si trova nel gruppo di risorse storageresourcegroup. L'account di archiviazione ha un contenitore denominato backup.
• Verrà creato un BLOB di backup con il nome ContosoBackup.apimbackup.

Impostare le variabili in PowerShell:

$apiManagementName="myapim";
$apiManagementResourceGroup="apimresourcegroup";
$storageAccountName="backupstorageaccount";
$storageResourceGroup="storageresourcegroup";
$containerName="backups";
$blobName="ContosoBackup.apimbackup"

Accesso tramite la chiave di accesso alle risorse di archiviazione

$storageKey = (Get-AzStorageAccountKey -ResourceGroupName $storageResourceGroup -StorageAccountName $storageAccountName)[0].Value

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName -StorageAccountKey $storageKey

Backup-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -TargetContainerName $containerName -TargetBlobName $blobName

Accesso tramite l'identità gestita

Per configurare un'identità gestita nell'istanza di Gestione API per accedere all'account di archiviazione, vedere Configurare un'identità gestita, più indietro in questo articolo.

Accesso tramite l'identità gestita assegnata dal sistema

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName

Backup-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -TargetContainerName $containerName `
    -TargetBlobName $blobName -AccessType "SystemAssignedManagedIdentity"

Accesso tramite l'identità gestita assegnata dall'utente

In questo esempio un'identità gestita assegnata dall'utente denominata myidentity si trova nel gruppo di risorse identityresourcegroup.

$identityName = "myidentity";
$identityResourceGroup = "identityresourcegroup";

$identityId = (Get-AzUserAssignedIdentity -Name $identityName -ResourceGroupName $identityResourceGroup).ClientId

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName

Backup-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -TargetContainerName $containerName `
    -TargetBlobName $blobName -AccessType "UserAssignedManagedIdentity" ` -identityClientId $identityid

Il backup è un'operazione a esecuzione prolungata che può richiedere alcuni minuti. Durante questo periodo il gateway API continua a gestire le richieste, ma lo stato del servizio è In aggiornamento.

CLI

Accedere con l'interfaccia della riga di comando di Azure.

Negli esempi seguenti:

• Un'istanza di Gestione API denominata myapim si trova nel gruppo di risorse apimresourcegroup.
• Un account di archiviazione denominato backupstorageaccount si trova nel gruppo di risorse storageresourcegroup. L'account di archiviazione ha un contenitore denominato backup.
• Verrà creato un BLOB di backup con il nome ContosoBackup.apimbackup.

Impostare le variabili in Bash:

apiManagementName="myapim";
apiManagementResourceGroup="apimresourcegroup";
storageAccountName="backupstorageaccount";
storageResourceGroup="storageresourcegroup";
containerName="backups";
backupName="ContosoBackup.apimbackup";

Accesso tramite la chiave di accesso alle risorse di archiviazione

storageKey=$(az storage account keys list --resource-group $storageResourceGroup --account-name $storageAccountName --query [0].value --output tsv)

az apim backup --resource-group $apiManagementResourceGroup --name $apiManagementName \
    --storage-account-name $storageAccountName --storage-account-key $storageKey --storage-account-container $containerName --backup-name $backupName

Il backup è un'operazione a esecuzione prolungata che può richiedere alcuni minuti. Durante questo periodo il gateway API continua a gestire le richieste, ma lo stato del servizio è In aggiornamento.

REST

Per informazioni sull'autenticazione e la chiamata alle API REST di Azure, vedere Informazioni di riferimento sull'API REST di Azure.

Per eseguire il backup di un servizio di gestione API, emettere la seguente richiesta HTTP:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/backup?api-version={api-version}

dove:

• subscriptionId: ID della sottoscrizione contenente il servizio Gestione API di cui si sta tentando di eseguire il backup
• resourceGroupName: nome del gruppo di risorse del servizio Gestione API di Azure
• serviceName : il nome del servizio di Gestione API di cui sta eseguendo il backup specificato quando è stato creato
• api-version : una versione valida dell'API REST, ad esempio 2021-08-01 o 2021-04-01-preview.

Nel corpo della richiesta specificare il nome dell'account di archiviazione di destinazione, il nome del contenitore BLOB, il nome del backup e il tipo di accesso all'archiviazione. Se il contenitore di archiviazione non esiste, l'operazione di backup la crea.

Accesso tramite la chiave di accesso alle risorse di archiviazione

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessKey": "{access key for the account}"
}

Accesso tramite l'identità gestita

Nota

L'uso di un'identità gestita di Gestione API per le operazioni di archiviazione durante il backup e il ripristino richiede la versione 2021-04-01-preview dell'API REST di Gestione API o versioni successive.

Accesso tramite l'identità gestita assegnata dal sistema

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessType": "SystemAssignedManagedIdentity"
}

Accesso tramite l'identità gestita assegnata dall'utente

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessType": "UserAssignedManagedIdentity",
    "clientId": "{client ID of user-assigned identity}"
}

Impostare il valore dell'intestazione della richiesta Content-Type su application/json.

Il backup è un'operazione a esecuzione prolungata che può richiedere alcuni minuti. Se la richiesta viene eseguita correttamente e il processo di backup è iniziato, si riceverà un codice di stato risposta 202 Accepted con un'intestazione Location. Effettuare richieste GET all'URL nell'intestazione Location per individuare lo stato dell'operazione. Mentre è in corso il backup, si continua a ricevere un codice di stato 202 Accepted. Durante questo periodo il gateway API continua a gestire le richieste, ma lo stato del servizio è In aggiornamento. Il codice risposta 200 OK indicherà il completamento dell'operazione di backup.

Ripristino di un servizio di Gestione API

Attenzione

Evitare modifiche alla configurazione del servizio (ad esempio, API, criteri, aspetto del portale per sviluppatori) mentre l'operazione di ripristino è in corso. È possibile sovrascrivere le modifiche.

PowerShell

Negli esempi seguenti,

• Un'istanza di Gestione API denominata myapim viene ripristinata dal BLOB di backup denominato ContosoBackup.apimbackup nell'account di archiviazione backupstorageaccount.
• Il BLOB di backup si trova in un contenitore denominato backup.

Impostare le variabili in PowerShell:

$apiManagementName="myapim";
$apiManagementResourceGroup="apimresourcegroup";
$storageAccountName="backupstorageaccount";
$storageResourceGroup="storageresourcegroup";
$containerName="backups";
$blobName="ContosoBackup.apimbackup"

Accesso tramite la chiave di accesso alle risorse di archiviazione

$storageKey = (Get-AzStorageAccountKey -ResourceGroupName $storageResourceGroup -StorageAccountName $storageAccountName)[0].Value

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName -StorageAccountKey $storageKey

Restore-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -SourceContainerName $containerName -SourceBlobName $blobName

Accesso tramite l'identità gestita

Per configurare un'identità gestita nell'istanza di Gestione API per accedere all'account di archiviazione, vedere Configurare un'identità gestita, più indietro in questo articolo.

Accesso tramite l'identità gestita assegnata dal sistema

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName

Restore-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -SourceContainerName $containerName `
    -SourceBlobName $blobName -AccessType "SystemAssignedManagedIdentity"

Accesso tramite l'identità gestita assegnata dall'utente

In questo esempio un'identità gestita assegnata dall'utente denominata myidentity si trova nel gruppo di risorse identityresourcegroup.

$identityName = "myidentity";
$identityResourceGroup = "identityresourcegroup";

$identityId = (Get-AzUserAssignedIdentity -Name $identityName -ResourceGroupName $identityResourceGroup).ClientId

$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName

Restore-AzApiManagement -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName `
    -StorageContext $storageContext -SourceContainerName $containerName `
    -SourceBlobName $blobName -AccessType "UserAssignedManagedIdentity" ` -identityClientId $identityid

Il ripristino è un'operazione a esecuzione prolungata che può richiedere fino a 45 minuti o più per il completamento.

CLI

Negli esempi seguenti,

• Un'istanza di Gestione API denominata myapim viene ripristinata dal BLOB di backup denominato ContosoBackup.apimbackup nell'account di archiviazione backupstorageaccount.
• Il BLOB di backup si trova in un contenitore denominato backup.

Impostare le variabili in Bash:

apiManagementName="myapim";
apiManagementResourceGroup="apimresourcegroup";
storageAccountName="backupstorageaccount";
storageResourceGroup="storageresourcegroup";
containerName="backups";
backupName="ContosoBackup.apimbackup"

Accesso tramite la chiave di accesso alle risorse di archiviazione

storageKey=$(az storage account keys list --resource-group $storageResourceGroup --account-name $storageAccountName --query [0].value --output tsv)

az apim restore --resource-group $apiManagementResourceGroup --name $apiManagementName \
    --storage-account-name $storageAccountName --storage-account-key $storageKey --storage-account-container $containerName --backup-name $backupName

Il ripristino è un'operazione a esecuzione prolungata che può richiedere fino a 45 minuti o più per il completamento.

REST

Per ripristinare un servizio di Gestione API da un backup creato in precedenza, creare la seguente richiesta HTTP:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/restore?api-version={api-version}

dove:

• subscriptionId : ID della sottoscrizione contenente il servizio di Gestione API in cui si sta ripristinando un backup
• resourceGroupName: nome del gruppo di risorse contenente il servizio di Gestione API in cui si sta ripristinando un backup
• serviceName : il nome del servizio di Gestione API in cui si sta effettuando il ripristino specificato quando è stato creato
• api-version : una versione valida dell'API REST, ad esempio 2021-08-01 o 2021-04-01-preview

Nel corpo della richiesta specificare il nome dell'account di archiviazione esistente, il nome del contenitore BLOB, il nome del backup e il tipo di accesso all'archiviazione.

Accesso tramite la chiave di accesso alle risorse di archiviazione

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessKey": "{access key for the account}"
}

Accesso tramite l'identità gestita

Nota

L'uso di un'identità gestita di Gestione API per le operazioni di archiviazione durante il backup e il ripristino richiede la versione 2021-04-01-preview dell'API REST di Gestione API o versioni successive.

Accesso tramite l'identità gestita assegnata dal sistema

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessType": "SystemAssignedManagedIdentity"
}

Accesso tramite l'identità gestita assegnata dall'utente

{
    "storageAccount": "{storage account name for the backup}",
    "containerName": "{backup container name}",
    "backupName": "{backup blob name}",
    "accessType": "UserAssignedManagedIdentity",
    "clientId": "{client ID of user-assigned identity}"
}

Impostare il valore dell'intestazione della richiesta Content-Type su application/json.

Il ripristino è un'operazione a lunga esecuzione che potrebbe richiedere 30 minuti o più per essere completata. Se la richiesta viene eseguita correttamente e il processo di ripristino è iniziato, si riceverà un codice di stato risposta 202 Accepted con un'intestazione Location. Effettuare richieste GET all'URL nell'intestazione Location per individuare lo stato dell'operazione. Mentre il ripristino è in corso, si continua a ricevere un codice di stato 202 Accepted. Il codice risposta 200 OK indicherà il completamento dell'operazione di ripristino.

Vincoli

• Il ripristino di un backup è garantito solo per 30 giorni dal momento della sua creazione.
• Mentre il backup è in corso, evitare modifiche alla gestione nel servizio, ad esempio l'aggiornamento o il downgrade del piano tariffario, la modifica del nome di dominio e altro ancora.
• Le modifiche apportate alla configurazione del servizio (ad esempio alle API, ai criteri e all'aspetto del portale per sviluppatori) durante l'esecuzione del processo di backup potrebbero essere escluse dal backup e potrebbero andare perse.
• Il backup non acquisisce i dati di log preaggregati usati nei report visualizzati nella finestra Analisi del portale di Azure.
• La condivisione di risorse tra le origini (CORS) non deve essere abilitata nel servizio BLOB nell'account di archiviazione.
• Il piano tariffario del servizio in cui si effettua il ripristino deve corrispondere al piano tariffario del servizio che è stato ripristinato.

Vincoli di rete di archiviazione

Se l'account di archiviazione è firewall abilitato, è consigliabile usare l'identità gestita assegnata dal sistema dell'istanza di Gestione API per l'accesso all'account. Assicurarsi che l'account di archiviazione conceda l'accesso ai servizi di Azure attendibili.

Cosa non viene sottopost a backup

• I dati di utilizzo usati per creare report analitici non sono inclusi nel backup. Usare l'API REST di Gestione API di Azure per recuperare periodicamente i report analitici e custodirli al sicuro.
• Certificati di TLS/SSL di dominio personalizzato.
• Certificati di CA personalizzati, che include i certificati intermedi o radice caricati dal cliente.
• Impostazioni di integrazione della rete virtuale.
• Configurazione dell'identità gestita.
• configurazione della diagnostica di Monitoraggio di Azure.
• Impostazioni di crittografia e protocolli.
• Contenuto del portale per sviluppatori.

La frequenza con cui si eseguono backup del servizio influisce sull'obiettivo del punto di ripristino. Per ridurla al minimo, si consiglia di implementare backup regolari e di eseguire backup su richiesta dopo aver apportato modifiche al servizio di Gestione API.

Passaggi successivi

Per il processo di backup/ripristino, vedere le risorse correlate seguenti:

• Automating API Management Backup and Restore with Logic Apps (Automazione del backup e del ripristino di Gestione API con App per la logica)
• Come spostare Gestione API di Azure tra aree
• Gestione API livello Premium supporta anche ridondanza della zona, che offre resilienza e disponibilità elevata a un'istanza del servizio in un'area di Azure specifica (località).