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

SI APPLICA A: Developer | Basic | Standard | Premium

La pubblicazione e la gestione delle API tramite Gestione API di Azure permette di sfruttare le 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 spiega come automatizzare le operazioni di backup e ripristino dell'istanza di Gestione API utilizzando un account di archiviazione esterno. I passaggi illustrati di seguito usano i cmdlet Backup-AzApiManagement e Restore-AzApiManagement di Azure PowerShell o il servizio Gestione API - Backup e Servizio Gestione API - Ripristinare le API REST.

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 utilizzare lo stesso nome host personalizzato e lo stesso certificato TLS per i servizi attivi e di standby, in modo che, al termine dell'operazione di ripristino, il traffico possa essere reindirizzato all'istanza di standby da una semplice modifica di CNAME DNS.

Nota

È consigliabile utilizzare 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.

Importante

Il completamento delle modifiche apportate all'infrastruttura del servizio Gestione API, ad esempio la configurazione di domini personalizzati, l'aggiunta di certificati CA, la scalabilità, la configurazione della rete virtuale, le modifiche della zona di disponibilità e le aggiunte all'area, possono richiedere 15 minuti o più, a seconda del livello di servizio e delle dimensioni della distribuzione. Prevedere tempi più lunghi per un'istanza con un numero maggiore di unità di scala o configurazione in più aree. Modifiche progressive al servizio di gestione delle API vengono eseguite con attenzione per preservare la capacità e la disponibilità.

Durante l'aggiornamento del servizio, non è possibile apportare altre modifiche all'infrastruttura del servizio. Tuttavia, è possibile configurare API, prodotti, criteri e impostazioni utente. Il servizio non riscontra tempi di inattività del gateway e Gestione API continuerà a gestire le richieste API senza interruzioni (ad eccezione del livello Sviluppatore).

Prerequisiti

• Istanza del servizio Gestione API in un livello di servizio supportato. Se non ne hai una, consulta Creare un'istanza del servizio Gestione API.

  Nota

  Attualmente, il backup e il ripristino non sono supportati nelle istanze di Gestione API con i gateway dell'area di lavoro associati.

• Un account di archiviazione di Azure. Se non ne hai uno, vedi Crea 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 utilizzare 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 utilizzate 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 versioni successive.

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 utilizzato 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 in identityresourcegroup del gruppo di risorse.

$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

Accedi con Azure CLI.

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.

RIPOSO

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: nome del servizio di Gestione API di cui sta eseguendo il backup specificato al momento della creazione
• api-version: 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 in identityresourcegroup del gruppo di risorse.

$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

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

RIPOSO

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: nome del servizio di Gestione API in cui si sta effettuando il ripristino specificato al momento della creazione
• api-version: 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 esecuzione prolungata che può richiedere alcuni minuti. 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 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, API, criteri e aspetto del portale per sviluppatori) mentre l'operazione di backup è in corso potrebbe essere esclusa dal backup e andrà persa.
• 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 della rete di archiviazione

Se l'account di archiviazione ha il 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 incluso nel backup

• I dati di utilizzo usati per la creazione di report di analisi non sono inclusi nel backup. Usare l'API REST di Gestione API di Azure per recuperare periodicamente i report di analisi per garantire la sicurezza.
• Certificati TLS/SSL di dominio personalizzati .
• Certificati ca personalizzati, che includono certificati intermedi o radice caricati dal cliente.
• Impostazioni di integrazione della rete virtuale.
• Configurazione dell'identità gestita .
• Configurazione della diagnostica di Azure Monitor.
• Protocolli e impostazioni di crittografia .
• Contenuto del portale per sviluppatori .

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

Contenuti correlati

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

• Automazione del backup e del ripristino della gestione delle API con Logic Apps
• Come spostare Gestione API di Azure tra aree
• Il livello Premium di Gestione API supporta anche la ridondanza della zona, che offre resilienza e disponibilità elevata a un'istanza del servizio in un'area di Azure specifica (località).