Come usare Gestione API di Azure con le reti virtualiHow to use Azure API Management with virtual networks

Le reti virtuali di Azure (VNET) consentono di posizionare le risorse di Azure in una rete instradabile non Internet a cui si controlla l'accesso.Azure Virtual Networks (VNETs) allow you to place any of your Azure resources in a non-internet routeable network that you control access to. Queste reti possono quindi essere connesse alle reti locali usando diverse tecnologie VPN.These networks can then be connected to your on-premises networks using various VPN technologies. Per altre informazioni sulle reti virtuali di Azure, è possibile iniziare dalla Panoramica sulla rete virtuale di Azure.To learn more about Azure Virtual Networks start with the information here: Azure Virtual Network Overview.

Gestione API di Azure può essere distribuito all'interno della rete virtuale (VNET) in modo che possa accedere ai servizi di back-end all'interno della rete.Azure API Management can be deployed inside the virtual network (VNET), so it can access backend services within the network. Il portale per sviluppatori e il gateway dell'API possono essere configurati in modo che siano accessibili da Internet o solo all'interno della rete virtuale.The developer portal and API gateway, can be configured to be accessible either from the Internet or only within the virtual network.

Nota

Gestione API di Azure supporta le reti virtuali classiche e Azure Resource Manager.Azure API Management supports both classic and Azure Resource Manager VNets.

PrerequisitiPrerequisites

Per eseguire i passaggi descritti in questo articolo, è necessario disporre di:To perform the steps described in this article, you must have:

  • Una sottoscrizione di Azure attiva.An active Azure subscription.

    Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.If you don't have an Azure subscription, create a free account before you begin.

  • Un'istanza di Gestione API.An APIM instance. Per altre informazioni, vedere Create an Azure API Management instance (Creare un'istanza di Gestione API di Azure).For more information, see Create an Azure API Management instance.

  • La connettività di rete virtuale è disponibile solo nei livelli Premium e Developer.VNET connectivity is available in the Premium and Developer tiers only. Per passare a uno di questi livelli, seguire le istruzioni indicate nell'argomento relativo all'aggiornamento e alla scalabilità.Switch to one of these tiers by following the directions in the upgrade and scale topic.

Attivare la connessione VNET Enable VNET connection

Abilitare la connettività di rete virtuale usando il portale di AzureEnable VNET connectivity using the Azure portal

  1. Nel portale di Azure passare all'istanza di Gestione API.Navigate to your APIM instance in the Azure portal.
  2. Selezionare Rete virtuale.Select Virtual Network.
  3. Configurare l'istanza di Gestione API da distribuire all'interno di una rete virtuale.Configure the API Management instance to be deployed inside a Virtual network.

    Menu della rete virtuale di Gestione API

  4. Selezionare il tipo di accesso da usare:Select the desired access type:

    • Esterno: il gateway di Gestione API e il portale per gli sviluppatori sono accessibili dalla rete internet pubblica tramite un servizio di bilanciamento del carico esterno.External: the API Management gateway and developer portal are accessible from the public internet via an external load balancer. Il gateway può accedere alle risorse all'interno della rete virtuale.The gateway can access resources within the virtual network.

      Peering pubblico

    • Interno: il gateway di Gestione API e il portale per gli sviluppatori sono accessibili soltanto dalla rete virtuale tramite un servizio di bilanciamento del carico interno.Internal: the API Management gateway and developer portal are accessible only from within the virtual network via an internal load balancer. Il gateway può accedere alle risorse all'interno della rete virtuale.The gateway can access resources within the virtual network.

      Peering privato`

      Verrà ora visualizzato un elenco di tutte le aree in cui viene eseguito il provisioning del servizio Gestione API.You will now see a list of all regions where your API Management service is provisioned. Selezionare una VNET e una subnet per ogni area.Select a VNET and subnet for every region. L'elenco viene popolato con le reti virtuali classiche e Resource Manager disponibili nelle sottoscrizioni di Azure, impostate nell'area che si sta configurando.The list is populated with both classic and Resource Manager virtual networks available in your Azure subscriptions that are setup in the region you are configuring.

      Nota

      Endpoint di servizio nel diagramma precedente include Gateway/Proxy, Portale di pubblicazione, Portale per sviluppatori, GIT e l'endpoint di gestione diretta.Service Endpoint in the above diagram includes Gateway/Proxy, Publisher Portal, Developer Portal, GIT, and the Direct Management Endpoint. Endpoint di gestione nel diagramma precedente è l'endpoint ospitato nel servizio per la gestione della configurazione tramite il portale di Azure e Powershell.Management Endpoint in the above diagram is the endpoint hosted on the service to manage configuration via Azure portal and Powershell. Inoltre si noti che, sebbene il diagramma mostra gli indirizzi IP per i vari endpoint, il servizio Gestione API risponde solo ai relativi nomi host configurati.Also, note, that, even though, the diagram shows IP Addresses for its various endpoints, API Management service only responds on its configured Hostnames.

      Importante

      Quando si distribuisce un'istanza di gestione API di Azure a una rete virtuale Resource Manager, il servizio deve essere in una subnet dedicata che non contiene altre risorse, a eccezione di istanze di gestione API di Azure.When deploying an Azure API Management instance to a Resource Manager VNET, the service must be in a dedicated subnet that contains no other resources except for Azure API Management instances. Se si tenta di distribuire un'istanza di gestione API di Azure a una subnet della rete virtuale Resource Manager contenente altre risorse, la distribuzione avrà esito negativo.If an attempt is made to deploy an Azure API Management instance to a Resource Manager VNET subnet that contains other resources, the deployment will fail.

      Selezionare una VPN

  5. Fare clic su Salva nella parte superiore della schermata.Click Save at the top of the screen.

Nota

L'indirizzo VIP dell'istanza di Gestione API può cambiare ogni volta che la rete virtuale viene abilitata o disabilitata.The VIP address of the API Management instance will change each time VNET is enabled or disabled.
L'indirizzo VIP viene modificato quando Gestione API passa da Esterna a Interna o viceversaThe VIP address will also change when API Management is moved from External to Internal or vice-versa

Importante

Se si rimuove Gestione API da una rete virtuale o si modifica quella in cui è distribuito, la rete virtuale utilizzata in precedenza può rimanere bloccata fino a 4 ore.If you remove API Management from a VNET or change the one it is deployed in, the previously used VNET can remain locked for up to 4 hours. Durante questo periodo non sarà possibile eliminare la rete virtuale o distribuirvi una nuova risorsa.During this period it will not be possible to delete the VNET or deploy a new resource to it.

Abilitare la connessione della rete virtuale usando i cmdlet di PowerShell Enable VNET connection using PowerShell cmdlets

È inoltre possibile abilitare la connettività della rete virtuale utilizzando i cmdlet di PowerShellYou can also enable VNET connectivity using the PowerShell cmdlets

  • Creare un servizio Gestione API all'interno di una rete virtuale: usare il cmdlet New-AzureRmApiManagement per creare un servizio Gestione API di Azure all'interno di una rete virtuale.Create an API Management service inside a VNET: Use the cmdlet New-AzureRmApiManagement to create an Azure API Management service inside a VNET.

  • Distribuire un servizio Gestione API esistente all'interno di una rete virtuale: usare il cmdlet Update-AzureRmApiManagementDeployment per spostare un servizio Gestione API di Azure esistente all'interno di una rete virtuale.Deploy an existing API Management service inside a VNET: Use the cmdlet Update-AzureRmApiManagementDeployment to move an existing Azure API Management service inside a Virtual Network.

Connettersi a un servizio Web ospitato all'interno di una rete virtuale Connect to a web service hosted within a virtual Network

Dopo che il servizio Gestione API è stato connesso alla VNET, l'accesso ai servizi di back-end all'interno della rete virtuale non è diverso dall'accesso ai servizi pubblici.After your API Management service is connected to the VNET, accessing backend services within it is no different than accessing public services. È sufficiente digitare l'indirizzo locale o il nome host (se è stato configurato un server DNS per la VNET) del servizio Web nel campo URL del servizio Web quando si crea una nuova API o se ne modifica una esistente.Just type in the local IP address or the host name (if a DNS server is configured for the VNET) of your web service into the Web service URL field when creating a new API or editing an existing one.

Aggiungere un'API dalla VPN

Problemi comuni di configurazione di rete Common Network Configuration Issues

Di seguito è riportato un elenco di problemi di configurazione comuni che possono verificarsi durante la distribuzione del servizio Gestione API in una rete virtuale.Following is a list of common misconfiguration issues that can occur while deploying API Management service into a Virtual Network.

  • Installazione di server DNS personalizzata: il servizio Gestione API dipende da vari servizi di Azure.Custom DNS server setup: The API Management service depends on several Azure services. Quando Gestione API è ospitata in una rete virtuale con un server DNS personalizzato, deve risolvere i nomi host dei servizi di Azure.When API Management is hosted in a VNET with a custom DNS server, it needs to resolve the hostnames of those Azure services. Vedere queste informazioni aggiuntive sulla configurazione del DNS personalizzato.Please follow this guidance on custom DNS setup. Vedere la tabella delle porte e altri requisiti di rete per riferimento.See the ports table below and other network requirements for reference.

Importante

Se si usa un server DNS personalizzato per la rete virtuale, è consigliabile impostarlo prima di distribuirvi un servizio Gestione API.It is recommended that, if you are using a Custom DNS Server(s) for the VNET, you set that up before deploying an API Management service into it. In caso contrario è necessario aggiornare il servizio Gestione API ogni volta che si modifica il server DNS eseguendo l'operazione di applicazione della configurazione di reteOtherwise you need to update the API Management service each time you change the DNS Servers(s) by running the Apply Network Configuration Operation

  • Porte necessarie per il servizio Gestione API: il traffico in ingresso e in uscita nella subnet in cui viene distribuita la gestione delle API può essere controllato usando il gruppo di sicurezza di rete.Ports required for API Management: Inbound and Outbound traffic into the Subnet in which API Management is deployed can be controlled using Network Security Group. Se una qualsiasi di queste porte non è disponibile, Gestione API potrebbe non funzionare correttamente e potrebbe diventare inaccessibile.If any of these ports are unavailable, API Management may not operate properly and may become inaccessible. Il blocco di una o più di tali porte è un problema di configurazione comune nell'uso di Gestione API in una rete virtuale.Having one or more of these ports blocked is another common misconfiguration issue when using API Management with a VNET.

Quando un'istanza del servizio Gestione API è ospitata in una rete virtuale, vengono usate le porte indicate nella tabella seguente.When an API Management service instance is hosted in a VNET, the ports in the following table are used.

Porte di origine/destinazioneSource / Destination Port(s) DirezioneDirection Protocollo di trasportoTransport protocol Origine/DestinazioneSource / Destination Scopo ()Purpose () Tipo di rete virtualeVirtual Network type
* / 80, 443* / 80, 443 In ingressoInbound TCPTCP INTERNET / VIRTUAL_NETWORKINTERNET / VIRTUAL_NETWORK Comunicazione tra client e Gestione APIClient communication to API Management EsternoExternal
/3443 / 3443 In ingressoInbound TCPTCP INTERNET / VIRTUAL_NETWORKINTERNET / VIRTUAL_NETWORK Endpoint di gestione per il portale di Azure e PowerShellManagement endpoint for Azure portal and Powershell InternoInternal
* / 80, 443* / 80, 443 In uscitaOutbound TCPTCP VIRTUAL_NETWORK / INTERNETVIRTUAL_NETWORK / INTERNET Accesso agli endpoint di Archiviazione di AzureAccess to Azure Storage endpoints Esterno e internoExternal & Internal
* / 1433* / 1433 In uscitaOutbound TCPTCP VIRTUAL_NETWORK / INTERNETVIRTUAL_NETWORK / INTERNET Accesso agli endpoint SQL di AzureAccess to Azure SQL endpoints Esterno e internoExternal & Internal
* / 11000 - 11999* / 11000 - 11999 In uscitaOutbound TCPTCP VIRTUAL_NETWORK / INTERNETVIRTUAL_NETWORK / INTERNET Accesso a SQL Azure versione 12Access to Azure SQL V12 Esterno e internoExternal & Internal
* / 14000 - 14999* / 14000 - 14999 In uscitaOutbound TCPTCP VIRTUAL_NETWORK / INTERNETVIRTUAL_NETWORK / INTERNET Accesso a SQL Azure versione 12Access to Azure SQL V12 Esterno e internoExternal & Internal
* / 5671* / 5671 In uscitaOutbound AMQPAMQP VIRTUAL_NETWORK / INTERNETVIRTUAL_NETWORK / INTERNET Dipendenza per il criterio Registra a Hub eventiDependency for Log to Event Hub policy and monitoring agent Esterno e internoExternal & Internal
* / 445* / 445 In uscitaOutbound TCPTCP VIRTUAL_NETWORK / INTERNETVIRTUAL_NETWORK / INTERNET Dipendenza dalla condivisione file di Azure per GITDependency on Azure File Share for GIT Esterno e internoExternal & Internal
* / 25028* / 25028 In uscitaOutbound TCPTCP VIRTUAL_NETWORK / INTERNETVIRTUAL_NETWORK / INTERNET Connettersi al server di inoltro SMTP per l'invio di messaggi di posta elettronicaConnect to SMTP Relay for sending Emails Esterno e internoExternal & Internal
* / 6381 - 6383* / 6381 - 6383 In ingresso e in uscitaInbound & Outbound TCPTCP VIRTUAL_NETWORK / VIRTUAL_NETWORKVIRTUAL_NETWORK / VIRTUAL_NETWORK Istanze di accesso Cache Redis tra RoleInstancesAccess Redis Cache Instances between RoleInstances Esterno e internoExternal & Internal
* / / * In ingressoInbound TCPTCP VIRTUAL_NETWORK/AZURE_LOADBALANCERAZURE_LOAD_BALANCER / VIRTUAL_NETWORK Bilanciamento del carico di infrastruttura di AzureAzure Infrastructure Load Balancer Esterno e internoExternal & Internal

Importante

  • Le porte per cui Scopo è grassetto sono necessarie per la corretta distribuzione del servizio Gestione API.The Ports for which the Purpose is bold are required for API Management service to be deployed successfully. Se si bloccano le altre porte, si verifica una riduzione delle prestazioni nella capacità di usare e monitorare il servizio in esecuzione.Blocking the other ports however will cause degradation in the ability to use and monitor the running service.
  • Funzionalità SSL: per abilitare la creazione e la convalida della catena di certificati SSL, il servizio Gestione API richiede la connettività di rete in uscita a ocsp.msocsp.com, mscrl.microsoft.com e crl.microsoft.com. Questa dipendenza non è necessaria se un certificato caricato in Gestione API contiene l'intera catena per la radice dell'autorità di certificazione.SSL functionality: To enable SSL certificate chain building and validation the API Management service needs Outbound network connectivity to ocsp.msocsp.com, mscrl.microsoft.com and crl.microsoft.com. This dependency is not required, if any certificate you upload to API Management contain the full chain to the CA root.

  • Accesso a DNS: l'accesso in uscita sulla porta 53 è necessario per la comunicazione con i server DNS.DNS Access: Outbound access on port 53 is required for communication with DNS servers. Se è presente un server DNS personalizzato all'altra estremità di un gateway VPN, il server DNS deve essere raggiungibile dalla subnet che ospita Gestione API.If a custom DNS server exists on the other end of a VPN gateway, the DNS server must be reachable from the subnet hosting API Management.

  • Le metriche e il monitoraggio dell'integrità: la connettività di rete in uscita agli endpoint di Monitoraggio di Azure, che si risolve nei domini seguenti: global.metrics.nsatc.net, shoebox2.metrics.nsatc.net, prod3.metrics.nsatc.net.Metrics and Health Monitoring: Outbound network connectivity to Azure Monitoring endpoints, which resolve under the following domains: global.metrics.nsatc.net, shoebox2.metrics.nsatc.net, prod3.metrics.nsatc.net.

  • Installazione di Express Route: secondo una diffusa configurazione, i clienti definiscono la propria route predefinita (0.0.0.0/0) verso la quale viene forzato il traffico Internet in uscita invece di far passare il flusso localmente.Express Route Setup: A common customer configuration is to define their own default route (0.0.0.0/0) which forces outbound Internet traffic to instead flow on-premises. Questo flusso di traffico interrompe sempre la connettività con Gestione API di Azure perché il traffico in uscita è bloccato in locale o convertito tramite NAT in un set non riconoscibile di indirizzi che non usano più i diversi endpoint di Azure.This traffic flow invariably breaks connectivity with Azure API Management because the outbound traffic is either blocked on-premises, or NAT'd to an unrecognizable set of addresses that no longer work with various Azure endpoints. La soluzione consiste nel definire una o più route definite dall'utente (UDR, User Defined Routes) o nella subnet contenente il servizio Gestione API di Azure.The solution is to define one (or more) user-defined routes (UDRs) on the subnet that contains the Azure API Management. Una route UDR definisce le route specifiche della subnet che verranno accettate invece della route predefinita.A UDR defines subnet-specific routes that will be honored instead of the default route. Se possibile, è consigliabile utilizzare la seguente configurazione:If possible, it is recommended to use the following configuration:

    • La configurazione di ExpressRoute annuncia 0.0.0.0/0 e per impostazione predefinita esegue il tunneling forzato di tutto il traffico in uscita in un ambiente locale.The ExpressRoute configuration advertises 0.0.0.0/0 and by default force tunnels all outbound traffic on-premises.
    • L'UDR applicata alla subnet contenente il servizio Gestione API di Azure definisce 0.0.0.0/0 con un tipo di hop successivo di Internet.The UDR applied to the subnet containing the Azure API Management defines 0.0.0.0/0 with a next hop type of Internet. L'effetto combinato di questi passaggi è che il livello di subnet UDR avrà la precedenza sul tunneling forzato di ExpressRoute, garantendo l'accesso a Internet in uscita dal servizio Gestione API di Azure.The combined effect of these steps is that the subnet level UDR takes precedence over the ExpressRoute forced tunneling, thus ensuring outbound Internet access from the Azure API Management.

Avviso

Gestione API di Azure non è supportato con le configurazioni di ExpressRoute che annunciano erroneamente route dal percorso di peering pubblico al percorso di peering privato.Azure API Management is not supported with ExpressRoute configurations that incorrectly cross-advertise routes from the public peering path to the private peering path. Le configurazioni di ExpressRoute che dispongono di peering pubblico configurato, riceveranno gli annunci di route da Microsoft per un elevato numero di intervalli di indirizzi IP di Microsoft Azure.ExpressRoute configurations that have public peering configured, will receive route advertisements from Microsoft for a large set of Microsoft Azure IP address ranges. Se questi intervalli di indirizzi vengono annunciati in modo non corretto nel percorso di peering privato, il risultato finale è che tutti i pacchetti di rete in uscita dalla subnet dell'istanza di Gestione API di Azure verranno erroneamente sottoposti a tunneling forzato verso l'infrastruttura di rete locale del cliente.If these address ranges are incorrectly cross-advertised on the private peering path, the end result is that all outbound network packets from the Azure API Management instance's subnet are incorrectly force-tunneled to a customer's on-premises network infrastructure. Questo flusso di rete interromperà il servizio Gestione API di Azure.This network flow breaks Azure API Management. La soluzione a questo problema consiste nell'interrompere l'annuncio di più route dal percorso di peering pubblico al percorso di peering privato.The solution to this problem is to stop cross-advertising routes from the public peering path to the private peering path.

Risoluzione dei problemi Troubleshooting

  • Installazione iniziale: quando la distribuzione iniziale del servizio Gestione API in una subnet non ha esito positivo, è consigliabile distribuire prima una macchina virtuale nella stessa subnet.Initial Setup: When the initial deployment of API Management service into a subnet does not succeed, it is advised to first deploy a virtual machine into the same subnet. Accedere successivamente al desktop remoto nella macchina virtuale e convalidare l'esistenza di connettività a una delle risorse indicate di seguito nella sottoscrizione di Azure in uso:Next remote desktop into the virtual machine and validate that there is connectivity to one of each resource below in your azure subscription

    • BLOB di Archiviazione di AzureAzure Storage blob
    • Database SQL di AzureAzure SQL Database

    Importante

    Dopo aver convalidato la connettività, assicurarsi di rimuovere tutte le risorse distribuite nella subnet, prima di distribuire Gestione API nella subnet.After you have validated the connectivity, make sure to remove all the resources deployed in the subnet, before deploying API Management into the subnet.

  • Aggiornamento incrementale: quando si apportano modifiche alla rete, fare riferimento all'API NetworkStatus per verificare che il servizio Gestione API non abbia perso l'accesso ad alcuna delle risorse critiche da cui dipende.Incremental Updates: When making changes to your network, refer to NetworkStatus API, to verify that the API Management service has not lost access to any of the critical resources which it depends upon. Lo stato della connettività dovrebbe essere aggiornato ogni 15 minuti.The connectivity status should be updated every 15 minutes.

  • Collegamenti di navigazione delle risorse: quando si esegue la distribuzione in una subnet di macchina virtuale in stile Resource Manager, Gestione API riserva la subnet, creando un collegamento di navigazione delle risorse.Resource Navigation Links: When deploying into Resource Manager style vnet subnet, API Management reserves the subnet, by creating a resource navigation Link. Se la subnet contiene già una risorsa da un provider diverso, la distribuzione ha esito negativo.If the subnet already contains a resource from a different provider, deployment will fail. Quando, analogamente, si sposta un servizio Gestione API in una subnet diversa o lo si elimina, viene rimosso il collegamento di navigazione delle risorse.Similarly, when you move an API Management service to a different subnet or delete it, we will remove that resource navigation link.

Routing Routing

  • Un indirizzo IP pubblico con bilanciamento del carico (VIP) viene riservato per consentire l'accesso a tutti gli endpoint di servizio.A load balanced public IP address (VIP) will be reserved to provide access to all service endpoints.
  • Un indirizzo IP di un intervallo IP di subnet (DIP) viene usato per accedere alle risorse all'interno della rete rituale e un indirizzo IP pubblico (VIP) viene usato per accedere alle risorse esterne alla rete virtuale.An IP address from a subnet IP range (DIP) will be used to access resources within the vnet and a public IP address (VIP) will be used to access resources outside the vnet.
  • L'indirizzo IP pubblico con bilanciamento del carico è disponibile nel pannello Panoramica/Informazioni di base del portale di Azure.Load balanced public IP address can be found on the Overview/Essentials blade in the Azure portal.

Limitazioni Limitations

  • Una subnet contenente le istanze di Gestione API non può contenere altri tipi di risorse di Azure.A subnet containing API Management instances cannot contain any other Azure resource types.
  • La subnet e il servizio di Gestione API devono essere nella stessa sottoscrizione.The subnet and the API Management service must be in the same subscription.
  • Una subnet contenente le istanze di gestione API non può essere spostata da una sottoscrizione all'altra.A subnet containing API Management instances cannot be moved across subscriptions.
  • Per le distribuzioni di Gestione API su più aree in modalità rete virtuale interna configurata, gli utenti sono responsabili della gestione del bilanciamento del carico poiché sono titolari del routing.For multi-region API Management deployments configured in Internal virtual network mode, users are responsible for managing the load balancing across multiple regions, as they own the routing.

Contenuti correlati Related content