API Management integreren met Service Fabric in Azure

Het implementeren van Azure API Management met Service Fabric is een geavanceerd scenario. API Management is handig wanneer u API's wilt publiceren met een uitgebreide set routeringsregels voor uw back-endService Fabric-services. Cloudtoepassingen hebben meestal een gateway in de front-end nodig om een centraal ingangspunt te bieden voor gebruikers, apparaten of andere toepassingen. In Service Fabric kan een gateway elke staatloze service zijn die is ontworpen voor inkomend verkeer, zoals een ASP.NET Core-toepassing, Event Hubs, IoT Hub of Azure API Management.

In dit artikel leest u hoe u Azure API Management instelt met Service Fabric om verkeer te routeren naar een back-endservice in Service Fabric. Wanneer u klaar bent, hebt u API Management geïmplementeerd in een VNET, een API-bewerking geconfigureerd om verkeer naar stateless back-endservices te verzenden. Zie het overzichtsartikel voor meer informatie over Azure API Management-scenario's met Service Fabric.

Beschikbaarheid

Vereiste voorwaarden

Voordat u begint:

• Als u nog geen Azure-abonnement hebt, maakt u een gratis account
• Installeer Azure PowerShell of Azure CLI.
• Maak een beveiligd Windows-cluster in een netwerkbeveiligingsgroep.
• Als u een Windows-cluster implementeert, stelt u een Windows-ontwikkelomgeving in. Installeer Visual Studio 2019 en de Azure-ontwikkeling, ASP.NET en webontwikkeling en .NET Core platformoverschrijdende ontwikkelworkloads . Stel vervolgens een .NET-ontwikkelomgeving in.

Netwerktopologie

Nu u een beveiligd Windows-cluster in Azure hebt, implementeert u API Management in het virtuele netwerk (VNET) in het subnet en de NSG die is aangewezen voor API Management. Voor dit artikel is de API Management Resource Manager-sjabloon vooraf geconfigureerd voor het gebruik van de namen van het VNET, subnet en NSG dat u hebt ingesteld in de Windows-clusterzelfstudie . In dit artikel wordt de volgende topologie geïmplementeerd in Azure waarin API Management en Service Fabric zich in subnetten van hetzelfde virtuele netwerk bevinden:

Meld u aan bij Azure en selecteer uw abonnement

Meld u aan bij uw Azure-account selecteer uw abonnement voordat u Azure-opdrachten uitvoert.

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

az login
az account set --subscription <guid>

Een Service Fabric-back-endservice implementeren

Voordat u API Management configureert om verkeer naar een Service Fabric-back-endservice te routeren, hebt u eerst een actieve service nodig om aanvragen te accepteren.

Maak een eenvoudige staatloze ASP.NET Core Reliable Service met behulp van de standaardsjabloon voor web-API-projecten. Hiermee maakt u een HTTP-eindpunt voor uw service, die u beschikbaar maakt via Azure API Management.

Start Visual Studio als beheerder en maak een ASP.NET Core-service:

1. Selecteer Bestand -> Nieuw project in Visual Studio.

2. Selecteer de Service Fabric-toepassingssjabloon onder Cloud en geef deze de naam ApiApplication.

3. Selecteer de stateless ASP.NET Core-servicesjabloon en geef het project de naam WebApiService.

4. Selecteer de web-API ASP.NET Core 2.1-projectsjabloon.

5. Zodra het project is gemaakt, opent PackageRoot\ServiceManifest.xml en verwijdert u het Port kenmerk uit de configuratie van de eindpuntresource:

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

   Als u de poort verwijdert, kan Service Fabric dynamisch een poort opgeven vanuit het poortbereik van de toepassing, geopend via de netwerkbeveiligingsgroep in de clusterbronbeheersjabloon, zodat verkeer ernaartoe kan stromen vanuit API Management.

6. Druk op F5 in Visual Studio om te controleren of de web-API lokaal beschikbaar is.

   Open Service Fabric Explorer en zoom in op een specifiek exemplaar van de ASP.NET Core-service om het basisadres te zien waarop de service luistert. Voeg /api/values dit toe aan het basisadres en open het in een browser, waarmee de get-methode wordt aangeroepen op de ValuesController in de web-API-sjabloon. Het retourneert het standaardantwoord dat wordt geleverd door de sjabloon, een JSON-matrix die twee tekenreeksen bevat:

   ["value1", "value2"]`
   

   Dit is het eindpunt dat u beschikbaar maakt via API Management in Azure.

7. Implementeer ten slotte de toepassing in uw cluster in Azure. Klik in Visual Studio met de rechtermuisknop op het toepassingsproject en selecteer Publiceren. Geef uw clustereindpunt (bijvoorbeeld mycluster.southcentralus.cloudapp.azure.com:19000) op om de toepassing te implementeren in uw Service Fabric-cluster in Azure.

Een ASP.NET Core stateless service met de naam fabric:/ApiApplication/WebApiService moet nu worden uitgevoerd in uw Service Fabric-cluster in Azure.

De Resource Manager-sjablonen downloaden en begrijpen

Download en sla de volgende Resource Manager-sjablonen en -parameters op:

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

Met de network-apim.json-sjabloon wordt een nieuw subnet en een nieuwe netwerkbeveiligingsgroep geïmplementeerd in het virtuele netwerk waarin het Service Fabric-cluster wordt geïmplementeerd.

In de volgende secties worden de resources beschreven die worden gedefinieerd door de apim.json-sjabloon . Volg de koppelingen naar de naslagdocumentatie voor sjablonen in elke sectie voor meer informatie. De configureerbare parameters die zijn gedefinieerd in het bestandapim.parameters.json parameters, worden verderop in dit artikel ingesteld.

Microsoft.ApiManagement/service

Microsoft.ApiManagement/service beschrijft het API Management-service-exemplaar: naam, SKU of laag, locatie van resourcegroep, informatie over uitgevers en virtueel netwerk.

Microsoft.ApiManagement/service/certificates

Microsoft.ApiManagement/service/certificates configureert API Management-beveiliging. API Management moet worden geverifieerd met uw Service Fabric-cluster voor servicedetectie met behulp van een clientcertificaat dat toegang heeft tot uw cluster. In dit artikel wordt hetzelfde certificaat gebruikt dat eerder is opgegeven bij het maken van het Windows-cluster, dat standaard kan worden gebruikt voor toegang tot uw cluster.

In dit artikel wordt hetzelfde certificaat gebruikt voor clientverificatie en beveiliging van clusterknooppunten naar knooppunt. U kunt een afzonderlijk clientcertificaat gebruiken als u er een hebt geconfigureerd voor toegang tot uw Service Fabric-cluster. Geef de naam, het wachtwoord en de gegevens (base-64 gecodeerde tekenreeks) op van het persoonlijke-sleutelbestand (.pfx) van het clustercertificaat dat u hebt opgegeven bij het maken van uw Service Fabric-cluster.

Microsoft.ApiManagement/service/backends

Microsoft.ApiManagement/service/backends beschrijft de back-endservice waarnaar verkeer wordt doorgestuurd.

Voor Service Fabric-back-ends is het Service Fabric-cluster de back-end in plaats van een specifieke Service Fabric-service. Hierdoor kan één beleid naar meer dan één service in het cluster worden gerouteerd. Het URL-veld hier is een volledig gekwalificeerde servicenaam van een service in uw cluster waarnaar alle aanvragen standaard worden doorgestuurd als er geen servicenaam is opgegeven in een back-endbeleid. U kunt een valse servicenaam gebruiken, zoals 'fabric:/fake/service' als u niet van plan bent om een terugvalservice te hebben. resourceId geeft het eindpunt voor clusterbeheer op. clientCertificateThumbprint en serverCertificateThumbprints identificeren certificaten die worden gebruikt voor verificatie met het cluster.

Microsoft.ApiManagement/service/products

Microsoft.ApiManagement/service/products maakt een product. In Azure API Management bevat een product een of meer API's, evenals een gebruiksquotum en de gebruiksvoorwaarden. Zodra een product is gepubliceerd, kunnen ontwikkelaars zich abonneren op het product en de API's van het product gaan gebruiken.

Voer een beschrijvende displayName en beschrijving in voor het product. Voor dit artikel is een abonnement vereist, maar de goedkeuring van het abonnement door een beheerder is dat niet. Deze productstatus is 'gepubliceerd' en is zichtbaar voor abonnees.

Microsoft.ApiManagement/service/apis

Met Microsoft.ApiManagement/service/apis wordt een API gemaakt. Een API in API Management vertegenwoordigt een set bewerkingen die kunnen worden aangeroepen door clienttoepassingen. Zodra de bewerkingen zijn toegevoegd, wordt de API toegevoegd aan een product en kan deze worden gepubliceerd. Zodra een API is gepubliceerd, kan deze worden geabonneerd op en gebruikt door ontwikkelaars.

• displayName kan elke naam voor uw API zijn. Voor dit artikel gebruikt u Service Fabric App.
• de naam biedt een unieke en beschrijvende naam voor de API, zoals 'service-fabric-app'. Deze wordt weergegeven in de portals voor ontwikkelaars en uitgevers.
• serviceUrl verwijst naar de HTTP-service die de API implementeert. API Management stuurt aanvragen door naar dit adres. Voor Service Fabric-back-ends wordt deze URL-waarde niet gebruikt. U kunt hier elke waarde plaatsen. Voor dit artikel bijvoorbeeld 'http://servicefabric"'.
• het pad wordt bijgevoegd aan de basis-URL voor de API management-service. De basis-URL is gebruikelijk voor alle API's die worden gehost door een API Management-service-exemplaar. API Management onderscheidt API's door hun achtervoegsel en daarom moet het achtervoegsel uniek zijn voor elke API voor een bepaalde uitgever.
• protocollen bepalen welke protocollen kunnen worden gebruikt voor toegang tot de API. Voor dit artikel vermeldt u http en https.
• path is een achtervoegsel bij de API. Gebruik voor dit artikel 'myapp'.

Microsoft.ApiManagement/service/apis/operations

Microsoft.ApiManagement/service/apis/operations Voordat een API in API Management kan worden gebruikt, moeten bewerkingen worden toegevoegd aan de API. Externe clients gebruiken een bewerking om te communiceren met de stateless ASP.NET Core-service die wordt uitgevoerd in het Service Fabric-cluster.

Als u een front-end-API-bewerking wilt toevoegen, vult u de waarden in:

• displayName en beschrijving beschrijven de bewerking. Gebruik 'Waarden' voor dit artikel.
• de methode geeft het HTTP-werkwoord op. Geef voor dit artikel GET op.
• urlTemplate wordt toegevoegd aan de basis-URL van de API en identificeert één HTTP-bewerking. Gebruik /api/values voor dit artikel of u de .NET-back-endservice hebt toegevoegd of getMessage als u de Java-back-endservice hebt toegevoegd. Het standaard-URL-pad dat hier is opgegeven, is het URL-pad dat wordt verzonden naar de Service Fabric-back-endservice. Als u hier hetzelfde URL-pad gebruikt dat door uw service wordt gebruikt, zoals '/api/values', werkt de bewerking zonder verdere aanpassing. U kunt hier ook een URL-pad opgeven dat verschilt van het URL-pad dat wordt gebruikt door de Service Fabric-service voor de back-end. In dat geval moet u later ook een pad opnieuw schrijven in uw bewerkingsbeleid.

Microsoft.ApiManagement/service/apis/policies

Microsoft.ApiManagement/service/apis/policies maakt een back-endbeleid dat alles met elkaar verbindt. Hier configureert u de Service Fabric-back-endservice waarnaar aanvragen worden doorgestuurd. U kunt dit beleid toepassen op elke API-bewerking. Zie Het overzicht van beleidsregels voor meer informatie.

De back-endconfiguratie voor Service Fabric biedt de volgende besturingselementen voor aanvraagroutering:

• Selectie van service-exemplaren door de naam van een Service Fabric-service-exemplaar op te geven, vastgelegd (bijvoorbeeld "fabric:/myapp/myservice") of gegenereerd op basis van de HTTP-aanvraag (bijvoorbeeld "fabric:/myapp/users/" + context.Request.MatchedParameters["name"]).
• Partitieomzetting door een partitiesleutel te genereren met behulp van een Service Fabric-partitioneringsschema.
• Replicaselectie voor statusbewuste diensten.
• Oplossingsvoorwaarden waarmee u de voorwaarden voor het opnieuw oplossen van een servicelocatie kunt opgeven en een aanvraag opnieuw kunt verzenden.

policyContent is de xml-inhoud van het Json-escape-bestand van het beleid. Voor dit artikel maakt u een back-endbeleid om verzoeken rechtstreeks naar de stateless service van .NET of Java te routeren die eerder is geïmplementeerd. Voeg een set-backend-service beleid toe onder inkomend beleid. Vervang de waarde sf-service-instance-name door fabric:/ApiApplication/WebApiService als u eerder de .NET-back-endservice hebt geïmplementeerd of fabric:/EchoServerApplication/EchoServerService als u de Java-service hebt geïmplementeerd. back-end-id verwijst naar een back-endresource, in dit geval de Microsoft.ApiManagement/service/backends resource die is gedefinieerd in de apim.json-sjabloon . back-end-id kan ook verwijzen naar een andere back-endresource die is gemaakt met behulp van de API Management-API's. Voor dit artikel stelt u de back-end-id in op de waarde van de parameter 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>

Raadpleeg de back-enddocumentatie van API Management voor een volledige set back-endbeleidskenmerken van Service Fabric

Parameters instellen en API Management implementeren

Vul de volgende lege parameters in de apim.parameters.json in voor uw implementatie.

certificatePassword en serviceFabricCertificateThumbprint moeten overeenkomen met het clustercertificaat dat wordt gebruikt om het cluster in te stellen.

serviceFabricCertificate is het certificaat als een met base 64 gecodeerde tekenreeks, die kan worden gegenereerd met behulp van het volgende script:

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

Vervang in inbound_policy de naamwaarde sf-service-instance-name door fabric:/ApiApplication/WebApiService als u eerder de .NET-back-endservice hebt geïmplementeerd of fabric:/EchoServerApplication/EchoServerService als u de Java-service hebt geïmplementeerd. back-end-id verwijst naar een back-endresource, in dit geval de Microsoft.ApiManagement/service/backends resource die is gedefinieerd in de apim.json-sjabloon . back-end-id kan ook verwijzen naar een andere back-endresource die is gemaakt met behulp van de API Management-API's. Voor dit artikel stelt u de back-end-id in op de waarde van de parameter 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>

Gebruik het volgende script om de Resource Manager-sjabloon en parameterbestanden voor API Management te implementeren:

$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

Test het

U kunt nu proberen een aanvraag naar uw back-endservice in Service Fabric te verzenden via API Management rechtstreeks vanuit Azure Portal.

1. Selecteer API in de API Management-service.

2. Selecteer in de Service Fabric App-API die u in de vorige stappen hebt gemaakt het tabblad Testen en vervolgens de bewerking Waarden .

3. Klik op de knop Verzenden om een testaanvraag naar de back-endservice te verzenden. U ziet nu een HTTP-antwoord dat lijkt op:

   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"]
   

Hulpmiddelen opruimen

Een cluster bestaat uit andere Azure-resources naast de clusterresource zelf. De eenvoudigste manier om het cluster te verwijderen en alle resources die het verbruikt, is door de resourcegroep te verwijderen.

Meld u aan bij Azure en selecteer de abonnements-id waarmee u het cluster wilt verwijderen. U kunt uw abonnements-id vinden door u aan te melden bij Azure Portal. Verwijder de resourcegroep en alle clusterresources met behulp van de cmdletRemove-AzResourceGroup.

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

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

Volgende stappen

Meer informatie over het gebruik van API Management.

U kunt ook Azure Portal gebruiken om Service Fabric-back-ends voor API Management te maken en te beheren.