Sdílet prostřednictvím

Integrace služby API Management se Service Fabric v Azure

  • Článek

Nasazení služby Azure API Management s využitím Service Fabric je pokročilý scénář. Služba API Management je užitečná v případě, že potřebujete publikovat rozhraní API s bohatou sadou pravidel směrování pro vaše back-end služby Service Fabric. Cloudové aplikace obvykle potřebují front-end bránu, která poskytuje jediný bod příjmu příchozího přenosu od uživatelů, zařízení nebo dalších aplikací. V Service Fabric může být brána bezstavová služba navržená pro příjem provozu, například aplikace ASP.NET Core, služba Event Hubs, služba IoT Hub nebo služba Azure API Management.

V tomto článku se dozvíte, jak nastavit Azure API Management s Service Fabric tak, aby směrovat provoz do back-endové služby v Service Fabric. Po dokončení budete mít nasazenou službu API Management ve virtuální síti a nakonfigurovanou operaci rozhraní API pro odesílání provozu do back-end bezstavové služby. Další informace o scénářích služby Azure API Management s využitím Service Fabric najdete v článku Přehled.

Poznámka:

Při práci s Azure doporučujeme používat modul Azure Az PowerShellu. Pokud chcete začít, přečtěte si téma Instalace Azure PowerShellu. Informace o tom, jak migrovat na modul Az PowerShell, najdete v tématu Migrace Azure PowerShellu z AzureRM na Az.

Dostupnost

Důležité

Tato funkce je dostupná na úrovních Premium a Developer služby API Management kvůli požadované podpoře virtuální sítě.

Požadavky

Než začnete:

Topologie sítě

Teď, když máte zabezpečený cluster s Windows v Azure, nasaďte službu API Management do virtuální sítě v podsíti a skupině zabezpečení sítě určené pro službu API Management. V tomto článku je šablona Resource Manageru služby API Management předem nakonfigurovaná tak, aby používala názvy virtuální sítě, podsítě a skupiny zabezpečení sítě, které jste nastavili v kurzu clusteru s Windows. Tento článek nasadí následující topologii do Azure, ve které jsou služby API Management a Service Fabric v podsítích stejné virtuální sítě:

Popisek obrázku

Přihlášení k Azure a výběr předplatného

Před spouštěním příkazů Azure se přihlaste ke svému účtu Azure a vyberte své předplatné.

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

az login
az account set --subscription <guid>

Nasazení back-end služby Service Fabric

Než ve službě API Management nakonfigurujete směrování provozu do back-end služby Service Fabric, potřebujete nejprve spuštěnou službu, která bude požadavky přijímat.

Vytvořte základní bezstavovou službu ASP.NET Core Reliable Service pomocí výchozí šablony projektu webového rozhraní API. Tím se pro vaši službu vytvoří koncový bod HTTP, který zveřejníte prostřednictvím služby Azure API Management.

Spusťte sadu Visual Studio jako správce a vytvořte službu ASP.NET Core:

  1. V sadě Visual Studio vyberte Soubor –> Nový projekt.

  2. Vyberte šablonu aplikace Service Fabric v části Cloud a pojmenujte aplikaci ApiApplication.

  3. Vyberte šablonu bezstavové služby ASP.NET Core a pojmenujte projekt WebApiService.

  4. Vyberte šablonu projektu webového rozhraní API ASP.NET Core 2.1.

  5. Po vytvoření projektu otevřete soubor PackageRoot\ServiceManifest.xml a z konfigurace prostředku koncového bodu odeberte atribut Port:

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

    Odebráním portu umožníte službě Service Fabric dynamicky určit port z rozsahu portů aplikace, který se otevře prostřednictvím skupiny zabezpečení sítě v šabloně Správce prostředků clusteru, což umožní tok provozu do něj ze služby API Management.

  6. Stisknutím klávesy F5 v sadě Visual Studio ověřte, že je webové rozhraní API místně dostupné.

    Otevřete Service Fabric Explorer, projděte hierarchií ke konkrétní instanci služby ASP.NET Core a zobrazte základní adresu, na které služba naslouchá. Přidejte k základní adrese /api/values a otevřete ji v prohlížeči. Tím se v šabloně webového rozhraní API vyvolá metoda Get v kontroleru ValuesController. Metoda vrátí výchozí odpověď poskytovanou šablonou, což je pole JSON obsahující dva řetězce:

    ["value1", "value2"]`

    Toto je koncový bod, který zveřejníte prostřednictvím služby API Management v Azure.

  7. Nakonec aplikaci nasaďte do svého clusteru v Azure. V sadě Visual Studio klikněte pravým tlačítkem na projekt aplikace a vyberte Publikovat. Zadejte koncový bod svého clusteru (například mycluster.southcentralus.cloudapp.azure.com:19000), aby se aplikace nasadila do vašeho clusteru Service Fabric v Azure.

Ve vašem clusteru Service Fabric v Azure by teď měla být spuštěná bezstavová služba ASP.NET Core s názvem fabric:/ApiApplication/WebApiService.

Stažení a pochopení šablon Resource Manageru

Stáhněte a uložte následující šablony Resource Manageru a soubor parametrů:

Šablona network-apim.json do virtuální sítě, ve které je nasazený cluster Service Fabric, nasadí novou podsíť a skupinu zabezpečení sítě.

Následující části popisují prostředky definované šablonou apim.json. Další informace najdete na odkazech na referenční dokumentaci k šabloně v každé části. Konfigurovatelné parametry definované v souboru parametrů apim.parameters.json se nastaví v pozdější části tohoto článku.

Microsoft.ApiManagement/service

Microsoft.ApiManagement/service popisuje instanci služby API Management: název, skladovou položku nebo úroveň, umístění skupiny prostředků, informace o vydavateli a virtuální síť.

Microsoft.ApiManagement/service/certificates

Microsoft.ApiManagement/service/certificates konfiguruje zabezpečení služby API Management. Aby byla služba API Management zjistitelná, musí se ve vašem clusteru Service Fabric ověřit pomocí klientského certifikátu s přístupem k vašemu clusteru. Tento článek používá stejný certifikát zadaný dříve při vytváření clusteru s Windows, který se ve výchozím nastavení dá použít pro přístup ke clusteru.

Tento článek používá stejný certifikát pro ověřování klientů a zabezpečení mezi uzly clusteru. Pro přístup k vašemu clusteru Service Fabric můžete použít i samostatný klientský certifikát, pokud máte nějaký nakonfigurovaný. Zadejte název, heslo a data (řetězec s kódováním Base 64) souboru privátního klíče (.pfx) certifikátu clusteru, který jste zadali při vytváření clusteru Service Fabric.

Microsoft.ApiManagement/service/backends

Microsoft.ApiManagement/service/backends popisuje back-end službu, do které se směruje provoz.

V případě back-endů Service Fabric je místo konkrétní služby Service Fabric back-endem cluster Service Fabric. Díky tomu může jediná zásada směrovat do více než jedné služby v clusteru. Zde uvedené pole url je plně kvalifikovaný název služby ve vašem clusteru, do které se ve výchozím nastavení směrují všechny požadavky, pokud v zásadě back-endu není zadaný žádný název služby. Pokud nemáte v úmyslu mít náhradní službu, můžete použít fiktivní název služby, například fabric:/fiktivni/sluzba. resourceId určuje koncový bod správy clusteru. clientCertificateThumbprint a serverCertificateThumbprints identifikují certifikáty sloužící k ověření v clusteru.

Microsoft.ApiManagement/service/products

Microsoft.ApiManagement/service/products vytvoří produkt. Ve službě Azure API Management obsahuje produkt jedno nebo více rozhraní API a také kvótu využití a podmínky použití. Jakmile je projekt publikovaný, vývojáři se můžou přihlásit k jeho odběru a začít používat jeho rozhraní API.

Zadejte popisný zobrazovaný název (displayName) a popis (description) produktu. V tomto článku se vyžaduje předplatné, ale schválení předplatného správcem není. Stav tohoto produktu je „publikováno“ a produkt je viditelný pro předplatitele.

Microsoft.ApiManagement/service/apis

Microsoft.ApiManagement/service/apis vytvoří rozhraní API. Rozhraní API ve službě API Management představuje sadu operací, které můžou vyvolat klientské aplikace. Po přidání operací se rozhraní API přidá do produktu a může se publikovat. Jakmile je rozhraní API publikované, vývojáři se můžou přihlásit k jeho odběru a začít ho používat.

  • displayName (zobrazovaný název) může být jakýkoli název vašeho rozhraní API. Pro účely tohoto článku použijte "Service Fabric App".
  • name (název) představuje jedinečný a popisný název rozhraní API, například service-fabric-app. Tento název se zobrazí na portálech pro vývojáře a vydavatele.
  • serviceUrl (adresa URL služby) odkazuje na službu HTTP implementující toto rozhraní API. Služba API Management na tuto adresu směruje požadavky. Pro back-endy Service Fabric se tato hodnota adresy URL nepoužívá. Sem můžete zadat jakoukoli hodnotu. Pro tento článek, například "http://servicefabric".
  • path (cesta) se připojí k základní adrese URL služby API Management. Základní adresa URL je společná pro všechna rozhraní API hostovaná jednou instancí služby API Management. Služba API Management rozlišuje rozhraní API podle jejich přípony, proto musí být přípona jedinečná pro každé rozhraní API daného vydavatele.
  • protocols (protokoly) určuje, které protokoly je možné použít k přístupu k rozhraní API. Pro účely tohoto článku uveďte http a https.
  • path (cesta) je přípona rozhraní API. Pro účely tohoto článku použijte myapp.

Microsoft.ApiManagement/service/apis/operations

Microsoft.ApiManagement/service/apis/operations Než bude možné použít rozhraní API ve službě API Management, musí se do tohoto rozhraní API přidat operace. Externí klienti pomocí operací komunikují s bezstavovou službou ASP.NET Core spuštěnou v clusteru Service Fabric.

Pokud chcete přidat front-end operaci rozhraní API, vyplňte následující hodnoty:

  • displayName (zobrazovaný název) a description (popis) popisujíc operaci. Pro účely tohoto článku použijte hodnoty.
  • method (metoda) určuje příkaz HTTP. Pro účely tohoto článku zadejte get.
  • urlTemplate (šablona adresy URL) se připojí k základní adrese URL rozhraní API a identifikuje jednu operaci HTTP. Pro účely tohoto článku použijte /api/values , pokud jste přidali back-endovou službu .NET nebo getMessage jste přidali back-endovou službu Java. Zde zadaná cesta URL je ve výchozím nastavení cestou URL, která se odesílá do back-end služby Service Fabric. Pokud tady použijete stejnou cestu URL, jakou používá vaše služba, například /api/values, bude operace fungovat bez dalších úprav. Můžete tady zadat také jinou cestu URL, než kterou používá vaše back-end služba Service Fabric. V takovém případě je potřeba později také určit přepsání cesty v zásadách operace.

Microsoft.ApiManagement/service/apis/policies

Microsoft.ApiManagement/service/apis/policies vytvoří zásadu back-endu, která vše spojí dohromady. Tady konfigurujete back-end službu Service Fabric, do které se požadavky směrují. Tuto zásadu můžete použít pro jakoukoli operaci rozhraní API. Další informace najdete v tématu Přehled zásad.

Konfigurace back-endu pro Service Fabric poskytuje následující ovládací prvky směrování požadavků:

  • Výběr instance služby zadáním názvu instance služby Service Fabric, a to buď pevně zakódovaného (například "fabric:/myapp/myservice"), nebo vygenerovaného z požadavku HTTP (například "fabric:/myapp/users/" + context.Request.MatchedParameters["name"]).
  • Překlad oddílů vygenerováním klíče oddílu pomocí jakéhokoli schématu vytváření oddílů Service Fabric.
  • Výběr replik pro stavové služby.
  • Podmínky opakování překladu, které umožňují zadat podmínky pro opakování překladu umístění služby a odeslání požadavku.

policyContent (obsah zásady) je obsah XML zásady uvozený ve formátu JSON. Pro účely tohoto článku vytvořte zásadu back-endu pro směrování požadavků přímo do bezstavové služby .NET nebo Javy nasazené dříve. Mezi příchozí zásady přidejte zásadu set-backend-service. Nahraďte hodnotu sf-service-instance-name za fabric:/ApiApplication/WebApiService, pokud jste předtím nasadili back-end službu v .NET, nebo za fabric:/EchoServerApplication/EchoServerService, pokud jste nasadili službu v Javě. backend-id odkazuje na prostředek back-endu, v tomto případě na prostředek Microsoft.ApiManagement/service/backends definovaný v šabloně apim.json. backend-id může odkazovat i na jiný prostředek back-endu vytvořený pomocí rozhraní API služby API Management. V tomto článku nastavte back-end id na hodnotu parametru 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>

Úplnou sadu atributů zásad back-endu Service Fabric najdete v dokumentaci k back-endu služby API Management.

Nastavení parametrů a nasazení služby API Management

Vyplňte následující prázdné parametry v souboru apim.parameters.json pro vaše nasazení.

Parametr Hodnota
apimInstanceName sf-apim
apimPublisherEmail myemail@contosos.com
apimSku Vývojář
serviceFabricCertificateName sfclustertutorialgroup320171031144217
certificatePassword q6D7nN%6ck@6
serviceFabricCertificateThumbprint C4C1E541AD512B8065280292A8BA6079C3F26F10
serviceFabricCertificate <řetězec s kódováním Base 64>
url_path /api/values
clusterHttpManagementEndpoint https://mysfcluster.southcentralus.cloudapp.azure.com:19080
inbound_policy <Řetězec XML>

certificatePassword a serviceFabricCertificateThumbprint musí odpovídat certifikátu clusteru použitému k nastavení clusteru.

serviceFabricCertificate je certifikát v podobě řetězce s kódováním Base 64, který můžete vygenerovat pomocí následujícího skriptu:

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

V části inbound_policy nahraďte hodnotu sf-service-instance-name za fabric:/ApiApplication/WebApiService, pokud jste předtím nasadili back-end službu v .NET, nebo za fabric:/EchoServerApplication/EchoServerService, pokud jste nasadili službu v Javě. backend-id odkazuje na prostředek back-endu, v tomto případě na prostředek Microsoft.ApiManagement/service/backends definovaný v šabloně apim.json. backend-id může odkazovat i na jiný prostředek back-endu vytvořený pomocí rozhraní API služby API Management. V tomto článku nastavte back-end id na hodnotu parametru 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>

Pomocí následujícího skriptu nasaďte šablonu Resource Manageru a soubory parametrů pro službu API Management:

$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

Testování

Přímo na webu Azure Portal teď můžete do své back-end služby v Service Fabric zkusit odeslat požadavek přes službu API Management.

  1. Ve službě API Management vyberte Rozhraní API.

  2. V rozhraní API Service Fabric App, které jste vytvořili v předchozích krocích, vyberte kartu Test a pak operaci Values.

  3. Kliknutím na tlačítko Odeslat odešlete do back-end služby testovací požadavek. Měla by se zobrazit podobná odpověď HTTP jako tato:

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

Vyčištění prostředků

Cluster se kromě vlastního prostředku clusteru skládá z dalších prostředků Azure. Nejjednodušší způsob, jak odstranit cluster a všechny prostředky, které využívá, je odstranit příslušnou skupinu prostředků.

Přihlaste se k Azure a vyberte ID předplatného, pomocí kterého chcete cluster odebrat. Své ID předplatného můžete zjistit po přihlášení k webu Azure Portal. Pomocí rutiny Remove-AzResourceGroup odstraňte skupinu prostředků a všechny prostředky clusteru.

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

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

Další kroky

Přečtěte si další informace o používání služby API Management.

Pomocí webu Azure Portal můžete také vytvářet a spravovat back-endy Service Fabric pro službu API Management.