API Management integrálása a Service Fabric szolgáltatással az Azure-ban

Az Azure API Management üzembe helyezése a Service Fabrickel speciális forgatókönyv. Az API Management akkor hasznos, ha a Service Fabric-háttérszolgáltatásokhoz tartozó útválasztási szabályok széles skálájával szeretne API-kat közzétenni. A felhőalapú alkalmazásokhoz általában előtér-átjáró szükséges, amely egyetlen belépési pontként szolgálhat a felhasználók, eszközök és egyéb alkalmazások számára. A Service Fabricben átjáró lehet bármely, bejövő forgalomra tervezett állapotmentes szolgáltatás, például egy ASP.NET Core-alkalmazás, az Event Hubs, az IoT Hub vagy az Azure API Management.

Ez a cikk bemutatja, hogyan állíthatja be az Azure API Management a Service Fabric szolgáltatással, hogy a forgalmat egy háttérszolgáltatáshoz irányíthassa a Service Fabricben. Az oktatóanyag végére rendelkezni fog egy virtuális hálózaton üzembe helyezett API Management szolgáltatással, valamint egy API-művelettel, amely a forgalom állapotmentes háttérszolgáltatásokhoz való irányítására lesz konfigurálva. A Service Fabrickel kapcsolatos Azure API Management-forgatókönyvekre vonatkozó további tudnivalókért tekintse meg az áttekintő cikket.

Rendelkezésre állás

Előfeltételek

Előkészületek:

• Ha nincs Azure-előfizetése, hozzon létre egy ingyenes fiókot
• Telepítse Azure PowerShell vagy az Azure CLI-t.
• Hozzon létre egy biztonságos Windows-fürtöt egy hálózati biztonsági csoportban.
• Ha Windows-fürtöt telepít, állítson be egy Windows fejlesztési környezetet. Telepítse a Visual Studio 2019-et és az Azure-fejlesztést, a ASP.NET és a webfejlesztést, valamint a .NET Core platformfüggetlen fejlesztési számítási feladatokat. Ezután hozzon létre egy .NET fejlesztési környezet.

Hálózati topológia

Most, hogy biztonságos Windows-fürtje van az Azure-ban, helyezzen üzembe API Management a virtuális hálózaton (VNET) a API Management kijelölt alhálózaton és NSG-n. Ebben a cikkben a API Management Resource Manager sablon előre konfigurálva van a Windows-fürt oktatóanyagában beállított virtuális hálózat, alhálózat és NSG nevének használatára Ez a cikk a következő topológiát helyezi üzembe az Azure-ban, amelyben a API Management és a Service Fabric azonos alhálózatokban találhatók Virtual Network:

Jelentkezzen be az Azure-ba, és válassza ki az előfizetését

Azure-parancsok végrehajtása előtt jelentkezzen be az Azure-fiókjába, és válassza ki az előfizetését.

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

az login
az account set --subscription <guid>

Service Fabric-háttérszolgáltatás telepítése

Mielőtt az API Management szolgáltatást a forgalom a Service Fabric-háttérszolgáltatáshoz való irányítására konfigurálná, előbb rendelkeznie kell a kérelmek fogadására képes, futó szolgáltatással.

Hozzon létre egy alapszintű állapot nélküli ASP.NET Core Reliable Service-t az alapértelmezett Webes API-projektsablon használatával. Ezzel létrehoz egy HTTP-végpontot a szolgáltatáshoz, amelyet az Azure API Management szolgáltatáson keresztül tehet közzé.

Indítsa el a Visual Studiót rendszergazdaként, és hozzon létre egy ASP.NET Core-szolgáltatást:

1. A Visual Studióban válassza a Fájl –> Új projekt lehetőséget.

2. Válassza ki a Service Fabric-alkalmazássablont a Cloud (Felhő) területen, és adja neki az "ApiApplication" nevet.

3. Válassza ki az ASP.NET Core állapotmentes szolgáltatássablont, és adja a "WebApiService" nevet a projektnek.

4. Válassza a Webes API ASP.NET Core 2.1 projektsablont.

5. A projekt létrehozása után nyissa meg a következőt a PackageRoot\ServiceManifest.xml fájlt, és távolítsa el a Port attribútumot a végponterőforrás-konfigurációból:

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

   A port eltávolítása lehetővé teszi a Service Fabric számára, hogy dinamikusan adjon meg egy portot az alkalmazás porttartományából, amelyet a Fürt Resource Manager sablon hálózati biztonsági csoportján keresztül nyit meg, így a forgalom a API Management-ból áramlik.

6. Nyomja le az F5 gombot a Visual Studióban, hogy ellenőrizhesse a Web API helyi elérhetőségét.

   Nyissa meg Service Fabric Explorert, és indítson részletes elemzést az ASP.NET Core szolgáltatás egy adott példányán, hogy láthassa a szolgáltatás által figyelt alapszintű címet. Adja hozzá az alapszintű címhez az /api/values elemet, majd nyissa meg egy böngészőben, amellyel meghívja a Get metódust a ValuesControllerre vonatkozóan a Web API-sablonban. Ez a sablon által biztosított alapértelmezett választ adja vissza, amely egy két sztringet tartalmazó JSON-tömb:

   ["value1", "value2"]`
   

   Ez az a végpont, amely az API Managementen keresztül tehető közzé az Azure-ban.

7. Végül telepítse az alkalmazást a fürtön az Azure-ban. A Visual Studióban kattintson a jobb gombbal az alkalmazásprojektre, és válassza a Publish (Közzététel) lehetőséget. Adja meg a fürt végpontját (például mycluster.southcentralus.cloudapp.azure.com:19000) az alkalmazás Service Fabric-fürtön való üzembe helyezéséhez az Azure-ban.

Most már futnia kell egy fabric:/ApiApplication/WebApiService nevű ASP.NET Core állapotmentes szolgáltatásnak a Service Fabric-fürtön az Azure-ban.

A Resource Manager-sablonok letöltése és megismerése

Töltse le és mentse a következő Resource Manager-sablonokat és paraméterfájlt:

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

A network-apim.json sablon telepít egy új alhálózatot és hálózati biztonsági csoportot a virtuális hálózatra, ahová a Service Fabric-fürt telepítve van.

A következő szakaszok ismertetik az apim.json sablon által definiált erőforrásokat. További információért kövesse a sablon referenciadokumentációjára mutató hivatkozásokat az egyes szakaszokon belül. Az apim.parameters.json paraméterfájlban definiált konfigurálható paraméterek a cikk későbbi részében lesznek beállítva.

Microsoft.ApiManagement/service

A Microsoft.ApiManagement/service írja le az API Management szolgáltatáspéldányt, beleértve annak nevét, SKU-ját vagy szintjét, az erőforráscsoport helyét, a közzétevő adatait és a virtuális hálózatot.

Microsoft.ApiManagement/service/certificates

A Microsoft.ApiManagement/service/certificates az API Management szolgáltatás biztonsági beállításait konfigurálja. Az API Managementnek hitelesítést kell végeznie a Service Fabric-fürttel a szolgáltatásészlelés érdekében egy olyan ügyféltanúsítvány használatával, amely rendelkezik a fürthöz való hozzáféréssel. Ez a cikk ugyanazt a korábban megadott tanúsítványt használja a Windows-fürt létrehozásakor, amely alapértelmezés szerint a fürt eléréséhez használható.

Ez a cikk ugyanazt a tanúsítványt használja az ügyfél-hitelesítéshez és a fürt csomópontok közötti biztonságához. Használhat külön ügyféltanúsítványt, ha van ilyen konfigurálva a Service Fabric-fürthöz való hozzáféréshez. Adja meg a Service Fabric-fürt létrehozásakor megadott fürttanúsítvány a titkos kulcsfájljának (.pfx) nevét, jelszavát és adatait (base-64 kódolású sztring).

Microsoft.ApiManagement/service/backends

A Microsoft.ApiManagement/service/backends azt a háttérszolgáltatást ismerteti, amelybe a forgalmat továbbítják.

A Service Fabric-háttérrendszerek esetében a Service Fabric-fürt a háttérrendszer egy adott Service Fabric-szolgáltatás helyett. Ez lehetővé teszi, hogy egyetlen szabályzat egynél több szolgáltatáshoz irányíthasson a fürtben. Az url mező itt a fürt egy olyan szolgáltatásának teljes szolgáltatásneve, amelyhez alapértelmezés szerint az összes kérelem irányul, ha nincs megadva szolgáltatásnév egy háttérszabályzatban. Használhat hamis szolgáltatásnevet (például „fabric:/hamis/szolgáltatás”) ha nem tervezi tartalék szolgáltatás használatát. A resourceId határozza meg a fürt felügyeleti végpontját. A clientCertificateThumbprint és a serverCertificateThumbprints határozzák meg a fürttel való hitelesítéshez használt tanúsítványokat.

Microsoft.ApiManagement/service/products

A Microsoft.ApiManagement/service/products egy terméket hoz létre. Az Azure API Management szolgáltatásban a termék egy vagy több API-t, valamint a használati kvótát és a használati feltételeket tartalmazza. Egy termék közzététele után a fejlesztők előfizethetnek a termékre, és megkezdhetik a termék API-jainak használatát.

Adjon meg egy leíró megjelenített nevet (displayName) és leírást (description) a termékhez. Ebben a cikkben előfizetésre van szükség, de a rendszergazda nem hagyja jóvá az előfizetést. A termék állapota „közzé van téve”, és látható az előfizetők számára.

Microsoft.ApiManagement/service/apis

A Microsoft.ApiManagement/service/apis API-t hoz létre. Az API Management szolgáltatáson belül az API-k egy, az ügyfélalkalmazások által meghívható műveletkészletet jelölnek. A műveletek hozzáadása után az API hozzá lesz adva a termékhez, és közzé lehet tenni. Miután egy API közzé lett téve, elő lehet rá fizetni, és a fejlesztők használatba vehetik.

• A displayName (megjelenített név) bármilyen, az API-t jelölő név lehet. Ebben a cikkben használja a "Service Fabric-alkalmazás" kifejezést.
• A name (név) egyedi és leíró nevet biztosít az API-nak, például: „service-fabric-app”. A fejlesztői és közzétevői portálon jelenik meg.
• A serviceUrl (szolgáltatás URL-címe) az API-t alkalmazó HTTP-szolgáltatásra hivatkozik. Az API Management erre a címre továbbítja a kérelmeket. A Service Fabric-háttérrendszerek esetében ez az URL-érték nem használható. Itt bármilyen érték megadható. Ebben a cikkben például "http://servicefabric".
• A path (útvonal) értéke az API Management szolgáltatás kiindulási URL-címéhez lesz hozzáfűzve. A kiindulási URL-cím egy API Management-szolgáltatáspéldány által üzemeltetett mindegyik API esetében megegyezik. Az API Management az API-kat az utótag alapján különbözteti meg, ezért az utótagnak egy adott közzétevő minden API-ja esetében egyedinek kell lennie.
• A protocols (protokollok) határozza meg, mely protokollok révén lehet hozzáférni az API-hoz. Ebben a cikkben a http és a https listában találja a következőt: .
• A path (útvonal) az API utótagja. Ebben a cikkben használja a "myapp" kifejezést.

Microsoft.ApiManagement/service/apis/operations

Microsoft.ApiManagement/service/apis/operations Mielőtt az API Management egy API-ját használni lehetne, műveleteket kell hozzáadni az API-hoz. A külső ügyfelek egy művelet használatával kommunikálhatnak a Service Fabric-fürtben futó ASP.NET Core állapotmentes szolgáltatással.

Egy előtér-API művelet hozzáadásához töltse ki a következő értékeket:

• A displayName (megjelenített név) és a description (leírás) írják le a műveletet. Ebben a cikkben használja az "Értékek" kifejezést.
• A method (metódus) határozza meg a HTTP-műveletet. Ebben a cikkben adja meg a GET értéket.
• A urlTemplate (URL-sablon) értéke az API kiindulási URL-címéhez lesz hozzáfűzve, és egyetlen HTTP-műveletet határoz meg. Ebben a cikkben használja /api/values a .NET háttérszolgáltatást vagy getMessage a Java háttérszolgáltatást. Alapértelmezés szerint az itt megadott URL-útvonal a Service Fabric-háttérszolgáltatásnak küldött URL-címnek felel meg. Ha ugyanazt az URL-címet használja itt, amelyet a szolgáltatása is használ – például „/api/values” –, a művelet további módosítások nélkül is működni fog. Megadhat a Service Fabric-háttérszolgáltatás által használt URL-címtől eltérő URL-címet is, amely esetben a művelet szabályzatában később útvonal-újraírást is meg kell adnia.

Microsoft.ApiManagement/service/apis/policies

A Microsoft.ApiManagement/service/apis/policies egy háttérszabályzatot hoz létre, amely mindent összeköt egymással. Itt konfigurálhatja a Service Fabric-háttérszolgáltatást, amelyhez a rendszer a kérelmeket fogja irányítani. Ezt a házirendet bármely API-műveletre alkalmazhatja. További információkért lásd: Szabályzatok áttekintése.

A Service Fabric háttérrendszerének konfigurációja a következő vezérlőket biztosítja a kérelmek útválasztásához:

• Szolgáltatáspéldány kiválasztása szoftveresen kötött (például "fabric:/myapp/myservice") vagy a HTTP-kérelem alapján létrehozott (például "fabric:/myapp/users/" + context.Request.MatchedParameters["name"]) Service Fabric szolgáltatáspéldány-név megadásával.
• Partíciófeloldás bármely Service Fabric particionálási séma használatával történő partíciókulcs-létrehozással.
• Replika kiválasztása állapotalapú szolgáltatásokhoz.
• Feloldási újrapróbálkozási feltételek, amelyek lehetővé teszik a szolgáltatáshelyek ismételt feloldása és a kérelmek újraküldése feltételeinek megszabását.

A policyContent a szabályzat Json-feloldójelekkel ellátott XML-tartalma. Ebben a cikkben hozzon létre egy háttérszabályzatot, amely közvetlenül a korábban üzembe helyezett .NET- vagy Java-állapot nélküli szolgáltatáshoz irányítja a kéréseket. Adjon hozzá egy set-backend-service szabályzatot a bejövő szabályzatok alatt. Az sf-service-instance-name értékét cserélje a fabric:/ApiApplication/WebApiService értékre, ha korábban a .NET-háttérszolgáltatást helyezte üzembe, vagy a fabric:/EchoServerApplication/EchoServerService értékre, ha a Java-szolgáltatást helyezte üzembe. A backend-id egy háttérerőforrásra hivatkozik, ebben az esetben a Microsoft.ApiManagement/service/backends erőforrásra, amely az apim.json sablonban van definiálva. A backend-id más, API Management API-k használatával létrehozott háttérerőforrásra is hivatkozhat. Ebben a cikkben állítsa a háttér-azonosítót a service_fabric_backend_name paraméter értékére.

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

A Service Fabric-háttérszabályzat attribútumainak teljes listája az API Management-háttérrendszer dokumentációban található.

Paraméterek beállítása és az API Management telepítése

Töltse ki az apim.parameters.json fájl következő üres paramétereit az üzembe helyezéshez.

A certificatePassword és a serviceFabricCertificateThumbprint értékeinek meg kell felelnie a fürt létrehozásakor használt fürttanúsítványnak.

A serviceFabricCertificate a tanúsítvány base-64 kódolású sztring formájában, amely a következő szkript használatával hozható létre:

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

Az inbound_policy esetében cserélje le az sf-service-instance-name értékét a fabric:/ApiApplication/WebApiService értékre, ha korábban a .NET-háttérszolgáltatást helyezte üzembe, vagy a fabric:/EchoServerApplication/EchoServerService értékre, ha a Java-szolgáltatást. A backend-id egy háttérerőforrásra hivatkozik, ebben az esetben a Microsoft.ApiManagement/service/backends erőforrásra, amely az apim.json sablonban van definiálva. A backend-id más, API Management API-k használatával létrehozott háttérerőforrásra is hivatkozhat. Ebben a cikkben állítsa a háttér-azonosítót a service_fabric_backend_name paraméter értékére.

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

A Resource Manager-sablon és az API Management paraméterfájljai telepítéséhez használja a következő szkriptet:

$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

Tesztelje

Most megpróbálhat küldeni egy kérelmet a Service Fabricben lévő háttérszolgáltatásnak az API Management szolgáltatáson keresztül, közvetlenül az Azure Portalról.

1. Az API Management szolgáltatásban válassza az API lehetőséget.

2. A korábbi lépések során létrehozott Service Fabric-alkalmazás API-ban válassza ki a Test (Teszt) fület, majd a Values műveletet.

3. Kattintson a Send (Küldés) gombra a tesztelési kérelem elküldéséhez a háttérszolgáltatásnak. Az alábbihoz hasonló HTTP-válasznak kell megjelennie:

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

Az erőforrások eltávolítása

A fürtben a fürt erőforrásán felül egyéb Azure-erőforrások is megtalálhatók. A fürt és az összes általa használt erőforrás törlésének legegyszerűbb módja az erőforráscsoport törlése.

Jelentkezzen be az Azure-ba, és válassza ki azt az előfizetés-azonosítót, amellyel el szeretné távolítani a fürtöt. Az Azure Portalra bejelentkezve keresheti meg az előfizetés azonosítóját. Törölje az erőforráscsoportot és az összes fürterőforrást a Remove-AzResourceGroup parancsmaggal.

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

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

Következő lépések

További információ a API Management használatáról.

A Azure Portal is használhatja a Service Fabric-háttéralkalmazások létrehozására és kezelésére API Management.