Integrare la Gestione delle API con Service Fabric in Azure

La distribuzione di Gestione API di Azure con Service Fabric è uno scenario avanzato. Gestione API è utile quando è necessario pubblicare API con un set completo di regole di routing per i servizi di Service Fabric back-end. Le applicazioni cloud richiedono in genere un gateway front-end per fornire un singolo punto di ingresso per utenti, dispositivi o altre applicazioni. In Service Fabric un gateway può essere qualsiasi servizio senza stato progettato per l'ingresso del traffico, ad esempio un'applicazione ASP.NET Core, hub eventi, hub IoT o Gestione API di Azure.

Questo articolo illustra come configurare Gestione API di Azure con Service Fabric per instradare il traffico a un servizio back-end in Service Fabric. Al termine, la Gestione API sarà stata distribuita alla rete virtuale e sarà stata configurata un'operazione API per l'invio del traffico ai servizi senza stato di back-end. Per altre informazioni sugli scenari di Gestione API di Azure con Service Fabric, vedere l'articolo panoramica .

Annotazioni

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

Availability

Importante

Questa funzionalità è disponibile nei livelli Premium e Developer di Gestione API a causa del supporto necessario per la rete virtuale.

Prerequisiti

Prima di iniziare:

• Se non si ha una sottoscrizione di Azure, creare un account gratuito
• Installare Azure PowerShell o l'interfaccia della riga di comando di Azure.
• Creare un cluster Windows sicuro in un gruppo di sicurezza di rete.
• Se si distribuisce un cluster Windows, configurare un ambiente di sviluppo Windows. Installare Visual Studio 2019 e i carichi di lavoro sviluppo multipiattaforma di Azure, sviluppo di ASP.NET e Web e .NET Core. Configurare quindi un ambiente di sviluppo .NET.

Topologia di rete

Ora che si dispone di un cluster di Windows protetto in Azure, distribuire Gestione API nella rete virtuale nella subnet e il gruppo di sicurezza di rete designato per Gestione API. Per questo articolo, il modello di Resource Manager Gestione API è preconfigurato con i nomi della rete virtuale, della subnet e del gruppo di sicurezza di rete configurati nell'esercitazione relativa al cluster di Windows. Questo articolo distribuisce la topologia seguente in Azure, in cui Gestione API e Service Fabric si trovano in subnet della stessa rete virtuale:

Accedere ad Azure e selezionare la sottoscrizione

Accedi al tuo account Azure e seleziona il tuo abbonamento prima di eseguire i comandi di Azure.

Connect-AzAccount
Get-AzSubscription
Set-AzContext -SubscriptionId <guid>

az login
az account set --subscription <guid>

Distribuire un servizio back-end di Service Fabric

Prima di configurare Gestione API per instradare il traffico a un servizio back-end di Service Fabric, è necessario un servizio in esecuzione per accettare le richieste.

Creare un ASP.NET Core Reliable Service senza stato di base usando il modello di progetto API Web predefinito. Verrà creato un endpoint HTTP per il servizio, esposto tramite Gestione API di Azure.

Avviare Visual Studio come amministratore e creare un servizio ASP.NET Core:

1. In Visual Studio selezionare File -> Nuovo progetto.

2. Selezionare il modello applicazione di Service Fabric in Cloud e denominarlo "ApiApplication".

3. Selezionare il modello di servizio senza stato ASP.NET Core e assegnare al progetto il nome "WebApiService".

4. Selezionare il modello di progetto API Web ASP.NET Core 2.1.

5. Dopo aver creato il progetto, aprire PackageRoot\ServiceManifest.xml e rimuovere l'attributo dalla configurazione della risorsa dell'endpoint Port :

   <Resources>
     <Endpoints>
       <Endpoint Protocol="http" Name="ServiceEndpoint" Type="Input" />
     </Endpoints>
   </Resources>
   

   La rimozione della porta consente a Service Fabric di specificare dinamicamente una porta dall'intervallo delle porte dell'applicazione, intervallo che viene aperto tramite il gruppo di sicurezza di rete configurato nel modello del Cluster Resource Manager, permettendo al traffico di fluire verso di essa dalla Gestione delle API.

6. Premere F5 in Visual Studio per verificare che l'API Web sia disponibile in locale.

   Aprire Service Fabric Explorer ed eseguire il drill-down in un'istanza specifica del servizio ASP.NET Core per visualizzare l'indirizzo di base su cui il servizio è in ascolto. Aggiungere /api/values all'indirizzo di base e aprirlo in un browser, che richiama il metodo Get nel modello api Web ValuesController. Restituisce la risposta predefinita fornita dal modello, una matrice JSON che contiene due stringhe:

   ["value1", "value2"]`
   

   Questo è l'endpoint che esponi tramite Gestione delle API in Azure.

7. Distribuire infine l'applicazione nel cluster in Azure. In Visual Studio fare clic con il pulsante destro del mouse sul progetto Applicazione e scegliere Pubblica. Specificare l'endpoint del cluster ,ad esempio , mycluster.southcentralus.cloudapp.azure.com:19000per distribuire l'applicazione nel cluster di Service Fabric in Azure.

Un servizio senza stato core ASP.NET denominato fabric:/ApiApplication/WebApiService dovrebbe ora essere in esecuzione nel cluster di Service Fabric in Azure.

Scaricare e comprendere i modelli di Resource Manager

Scaricare e salvare il file di parametri e modelli di Resource Manager seguenti:

• network-apim.json
• network-apim.parameters.json
• apim.json
• apim.parameters.json

Il modello dinetwork-apim.json distribuisce una nuova subnet e un nuovo gruppo di sicurezza di rete nella rete virtuale in cui viene distribuito il cluster di Service Fabric.

Le sezioni seguenti descrivono le risorse definite dal modello diapim.json . Per altre informazioni, seguire i collegamenti alla documentazione di riferimento del modello all'interno di ogni sezione. I parametri configurabili definiti nel file dei parametri diapim.parameters.json vengono impostati più avanti in questo articolo.

Microsoft.ApiManagement/service

Microsoft.ApiManagement/service descrive l'istanza del servizio Gestione API: nome, SKU o livello, percorso del gruppo di risorse, informazioni sull'editore e rete virtuale.

Microsoft.ApiManagement/service/certificates

Microsoft.ApiManagement/service/certificates configura la sicurezza di Gestione API. L'API Management deve autenticarsi con il cluster di Service Fabric per la scoperta dei servizi utilizzando un certificato client che ha accesso al cluster. Questo articolo usa lo stesso certificato specificato in precedenza durante la creazione del cluster Windows, che per impostazione predefinita può essere usato per accedere al cluster.

Questo articolo usa lo stesso certificato per l'autenticazione client e la sicurezza da nodo a nodo del cluster. È possibile usare un certificato client separato se ne è stato configurato uno per accedere al cluster di Service Fabric. Specificare il nome, la password e i dati (stringa con codifica base 64) del file di chiave privata (pfx) del certificato del cluster specificato durante la creazione del cluster di Service Fabric.

Microsoft.ApiManagement/service/backends

Microsoft.ApiManagement/service/backends descrive il servizio back-end a cui viene inoltrato il traffico.

Per i back-end di Service Fabric, il cluster di Service Fabric è il back-end anziché un servizio specifico di Service Fabric. Ciò consente a una singola politica di instradare più di un servizio nel cluster. Il campo URL qui è un nome di servizio completo di un servizio nel cluster a cui tutte le richieste vengono instradate per impostazione predefinita se non viene specificato alcun nome di servizio in un criterio back-end. È possibile usare un nome di servizio falso, ad esempio "fabric:/fake/service" se non si intende avere un servizio di fallback. resourceId specifica l'endpoint di gestione del cluster. clientCertificateThumbprint e serverCertificateThumbprints identificano i certificati usati per l'autenticazione con il cluster.

Microsoft.ApiManagement/service/products

Microsoft.ApiManagement/service/products crea un prodotto. In Gestione API di Azure, un prodotto contiene una o più API, nonché una quota di utilizzo e le condizioni per l'utilizzo. Una volta pubblicato un prodotto, gli sviluppatori possono sottoscrivere il prodotto e iniziare a usare le API del prodotto.

Immettere un displayName descrittivo e una descrizione per il prodotto. Per questo articolo, è necessaria una sottoscrizione, ma l'approvazione della sottoscrizione da parte di un amministratore non è necessaria. Questo stato del prodotto è "pubblicato" ed è visibile ai sottoscrittori.

Microsoft.ApiManagement/service/apis

Microsoft.ApiManagement/service/apis crea un'API. Un'API in Gestione API rappresenta un set di operazioni che possono essere richiamate dalle applicazioni client. Dopo aver aggiunto le operazioni, l'API viene aggiunta a un prodotto e può essere pubblicata. Una volta pubblicata un'API, può essere sottoscritta e usata dagli sviluppatori.

• displayName può essere qualsiasi nome per l'API. Per questo articolo, usare "App di Service Fabric".
• name fornisce un nome univoco e descrittivo per l'API, ad esempio "service-fabric-app". Viene visualizzato nei portali per sviluppatori e editori.
• serviceUrl fa riferimento al servizio HTTP che implementa l'API. La gestione dell'API inoltra le richieste a questo indirizzo. Per i back-end di Service Fabric, questo valore URL non viene usato. È possibile inserire qualsiasi valore qui. Per questo articolo, ad esempio "http://servicefabric".
• path viene aggiunto all'URL di base per il servizio Gestione API. L'URL di base è comune per tutte le API ospitate da un'istanza del servizio Gestione API. Gestione API distingue le API in base al suffisso e pertanto il suffisso deve essere univoco per ogni API per un determinato editore.
• i protocolli determinano quali protocolli possono essere usati per accedere all'API. Per questo articolo, elencare http e https.
• path è un suffisso per l'API. Per questo articolo, usare "myapp".

Microsoft.ApiManagement/service/apis/operations

Microsoft.ApiManagement/service/apis/operations Prima di poter usare un'API in Gestione API, è necessario aggiungere operazioni all'API. I client esterni usano un'operazione per comunicare con il servizio senza stato core ASP.NET in esecuzione nel cluster di Service Fabric.

Per aggiungere un'operazione API front-end, compilare i valori:

• displayName e descrizione descrivono l'operazione. Per questo articolo, usare "Valori".
• method specifica il verbo HTTP. Per questo articolo specificare GET.
• URLTemplate viene aggiunto all'URL di base dell'API e identifica una singola operazione HTTP. Per questo articolo, usare /api/values se è stato aggiunto il servizio back-end .NET o getMessage se è stato aggiunto il servizio back-end Java. Per impostazione predefinita, il percorso URL specificato qui è il percorso URL inviato al servizio Service Fabric back-end. Se si usa lo stesso percorso URL usato dal servizio, ad esempio "/api/values", l'operazione funziona senza ulteriori modifiche. È anche possibile specificare un percorso URL diverso dal percorso URL usato dal servizio Service Fabric back-end, nel qual caso è anche necessario specificare una riscrittura del percorso nei criteri dell'operazione in un secondo momento.

Microsoft.ApiManagement/service/apis/policies

Microsoft.ApiManagement/service/apis/policies crea un criterio back-end che collega tutti gli elementi insieme. In questo caso si configura il servizio Service Fabric back-end a cui vengono instradate le richieste. È possibile applicare questo criterio a qualsiasi operazione API. Per altre informazioni, vedere Panoramica dei criteri.

La configurazione back-end per Service Fabric fornisce i controlli di routing delle richieste seguenti:

• Selezione dell'istanza di servizio specificando un nome di istanza di servizio di Service Fabric, codificato in modo fisso (ad esempio, "fabric:/myapp/myservice") o generato dalla richiesta HTTP (ad esempio, "fabric:/myapp/users/" + context.Request.MatchedParameters["name"]).
• Risoluzione delle partizioni generando una chiave di partizione usando qualsiasi schema di partizionamento di Service Fabric.
• Selezione della replica per i servizi con stato.
• Condizioni per i nuovi tentativi di risoluzione della posizione di un servizio e il nuovo invio di una richiesta.

policyContent è il contenuto XML con escape JSON della policy. Per questo articolo, creare un criterio di back-end per instradare le richieste direttamente al servizio .NET o Java senza stato distribuito in precedenza. Aggiungere un criterio set-backend-service tra i criteri in ingresso. Sostituire il valore sf-service-instance-name con fabric:/ApiApplication/WebApiService se in precedenza è stato distribuito il servizio back-end .NET o fabric:/EchoServerApplication/EchoServerService se è stato distribuito il servizio Java. backend-id fa riferimento a una risorsa back-end, in questo caso la Microsoft.ApiManagement/service/backends risorsa definita nel modello diapim.json . backend-id può anche fare riferimento a un'altra risorsa back-end creata usando le API di Gestione API. Per questo articolo impostare backend-id sul valore del parametro service_fabric_backend_name .

<policies>
  <inbound>
    <base/>
    <set-backend-service
        backend-id="servicefabric"
        sf-service-instance-name="service-name"
        sf-resolve-condition="@(context.LastError?.Reason == "BackendConnectionFailure")" />
  </inbound>
  <backend>
    <base/>
  </backend>
  <outbound>
    <base/>
  </outbound>
</policies>

Per un set completo di attributi dei criteri back-end di Service Fabric, vedere la documentazione back-end di Gestione API

Impostare i parametri e distribuire la Gestione dell'API

Compilare i seguenti parametri vuoti nel file apim.parameters.json per la tua distribuzione.

Parametro	Value
apimInstanceName	sf-apim
apimPublisherEmail	myemail@contosos.com
apimSku	Developer
serviceFabricCertificateName	sfclustertutorialgroup320171031144217
certificatePassword	q6D7nN%6ck@6
serviceFabricCertificateThumbprint	C4C1E541AD512B8065280292A8BA6079C3F26F10
serviceFabricCertificate	<stringa con codifica Base 64>
url_path	/api/values
clusterHttpManagementEndpoint	https://mysfcluster.southcentralus.cloudapp.azure.com:19080
inbound_policy	<Stringa XML>

certificatePassword e serviceFabricCertificateThumbprint devono corrispondere al certificato del cluster usato per configurare il cluster.

serviceFabricCertificate è il certificato come stringa con codifica base 64, che può essere generata usando lo script seguente:

$bytes = [System.IO.File]::ReadAllBytes("C:\mycertificates\sfclustertutorialgroup220171109113527.pfx");
$b64 = [System.Convert]::ToBase64String($bytes);
[System.Io.File]::WriteAllText("C:\mycertificates\sfclustertutorialgroup220171109113527.txt", $b64);

In inbound_policy sostituire il valore sf-service-instance-name con fabric:/ApiApplication/WebApiService se in precedenza è stato distribuito il servizio back-end .NET o fabric:/EchoServerApplication/EchoServerService se è stato distribuito il servizio Java. backend-id fa riferimento a una risorsa back-end, in questo caso la Microsoft.ApiManagement/service/backends risorsa definita nel modello diapim.json . backend-id può anche fare riferimento a un'altra risorsa back-end creata usando le API di Gestione API. Per questo articolo impostare backend-id sul valore del parametro service_fabric_backend_name .

<policies>
  <inbound>
    <base/>
    <set-backend-service
        backend-id="servicefabric"
        sf-service-instance-name="service-name"
        sf-resolve-condition="@(context.LastError?.Reason == "BackendConnectionFailure")" />
  </inbound>
  <backend>
    <base/>
  </backend>
  <outbound>
    <base/>
  </outbound>
</policies>

Usare lo script seguente per distribuire il modello di Resource Manager e i file di parametri per Gestione API:

$groupname = "sfclustertutorialgroup"
$clusterloc="southcentralus"
$templatepath="C:\clustertemplates"

New-AzResourceGroupDeployment -ResourceGroupName $groupname -TemplateFile "$templatepath\network-apim.json" -TemplateParameterFile "$templatepath\network-apim.parameters.json" -Verbose

New-AzResourceGroupDeployment -ResourceGroupName $groupname -TemplateFile "$templatepath\apim.json" -TemplateParameterFile "$templatepath\apim.parameters.json" -Verbose

ResourceGroupName="sfclustertutorialgroup"
az deployment group create --name ApiMgmtNetworkDeployment --resource-group $ResourceGroupName --template-file network-apim.json --parameters @network-apim.parameters.json

az deployment group create --name ApiMgmtDeployment --resource-group $ResourceGroupName --template-file apim.json --parameters @apim.parameters.json

Testarlo

È ora possibile provare a inviare una richiesta al servizio back-end in Service Fabric tramite Gestione API direttamente dal portale di Azure.

1. Nel servizio Gestione API selezionare API.

2. Nell'API dell'app di Service Fabric creata nei passaggi precedenti selezionare la scheda Test e quindi l'operazione Valori .

3. Fare clic sul pulsante Invia per inviare una richiesta di test al servizio back-end. Verrà visualizzata una risposta HTTP simile alla seguente:

   HTTP/1.1 200 OK
   
   Transfer-Encoding: chunked
   
   Content-Type: application/json; charset=utf-8
   
   Vary: Origin
   
   Ocp-Apim-Trace-Location: https://apimgmtstodhwklpry2xgkdj.blob.core.windows.net/apiinspectorcontainer/PWSQOq_FCDjGcaI1rdMn8w2-2?sv=2015-07-08&sr=b&sig=MhQhzk%2FEKzE5odlLXRjyVsgzltWGF8OkNzAKaf0B1P0%3D&se=2018-01-28T01%3A04%3A44Z&sp=r&traceId=9f8f1892121e445ea1ae4d2bc8449ce4
   
   Date: Sat, 27 Jan 2018 01:04:44 GMT
   
   
   ["value1", "value2"]
   

Pulire le risorse

Un cluster è costituito da altre risorse di Azure oltre alla risorsa cluster stessa. Il modo più semplice per eliminare il cluster e tutte le risorse utilizzate consiste nell'eliminare il gruppo di risorse.

Accedere ad Azure e selezionare l'ID sottoscrizione con cui si vuole rimuovere il cluster. È possibile trovare l'ID sottoscrizione accedendo al portale di Azure. Eliminare il gruppo di risorse e tutte le risorse del cluster usando il cmdletRemove-AzResourceGroup.

$ResourceGroupName = "sfclustertutorialgroup"
Remove-AzResourceGroup -Name $ResourceGroupName -Force

ResourceGroupName="sfclustertutorialgroup"
az group delete --name $ResourceGroupName

Passaggi successivi

Altre informazioni sull'uso di Gestione API.

È anche possibile usare il portale di Azure per creare e gestire back-end di Service Fabric per Gestione API.