Integrowanie usługi API Management z usługą Service Fabric na platformie Azure

Wdrażanie usługi Azure API Management za pomocą usługi Service Fabric jest zaawansowanym scenariuszem. Usługa API Management jest przydatna, gdy trzeba publikować interfejsy API z bogatym zestawem reguł routingu dla usług zaplecza usługi Service Fabric. Aplikacje w chmurze zazwyczaj potrzebują przedniej bramy, aby zapewnić pojedynczy punkt wejściowy dla użytkowników, urządzeń lub innych aplikacji. W usłudze Service Fabric brama może być dowolną bezstanową usługą przeznaczoną do ruchu przychodzącego, takiego jak aplikacja ASP.NET Core, usługa Event Hubs, usługa IoT Hub lub usługa Azure API Management.

W tym artykule pokazano, jak skonfigurować usługę Azure API Management za pomocą usługi Service Fabric w celu kierowania ruchu do usługi zaplecza w usłudze Service Fabric. Po zakończeniu wdrażania usługi API Management w sieci wirtualnej oraz skonfigurowaniu operacji interfejsu API do wysyłania ruchu do usług bezstanowych zaplecza, wszystkie czynności są gotowe. Aby dowiedzieć się więcej na temat scenariuszy usługi Azure API Management w usłudze Service Fabric, zobacz artykuł z omówieniem .

Uwaga

Zalecamy korzystanie z modułu Azure Az programu PowerShell do interakcji z platformą Azure. Aby rozpocząć, zobacz Instalowanie programu Azure PowerShell. Aby dowiedzieć się, jak przeprowadzić migrację do modułu Az PowerShell, zobacz Migracja programu Azure PowerShell z modułu AzureRM do modułu Az.

Dostępność

Ważne

Ta funkcja jest dostępna w warstwach Premium i Developer usługi API Management ze względu na wymaganą obsługę sieci wirtualnej.

Wymagania wstępne

Przed rozpoczęciem:

• Jeśli nie masz subskrypcji platformy Azure, utwórz bezpłatne konto
• Zainstaluj program Azure PowerShell lub interfejs wiersza polecenia platformy Azure.
• Utwórz bezpieczny klaster systemu Windows w sieciowej grupie zabezpieczeń.
• Jeśli wdrożysz klaster systemu Windows, skonfiguruj środowisko programistyczne systemu Windows. Zainstaluj Visual Studio 2019 i obciążenia robocze rozwój na platformie Azure, ASP.NET i tworzenie aplikacji internetowych oraz rozwój międzyplatformowy .NET Core. Następnie skonfiguruj środowisko programistyczne platformy .NET.

Topologia sieci

Teraz, gdy masz bezpieczny klaster systemu Windows na platformie Azure, wdróż usługę API Management w sieci wirtualnej w podsieci i sieciowej grupie zabezpieczeń wyznaczonej dla usługi API Management. W tym artykule szablon Menedżera Zasobów dla Zarządzania API jest wstępnie skonfigurowany do używania nazw sieci wirtualnej, podsieci i sieciowej grupy zabezpieczeń, które zostały określone w samouczku klastra Windows. W tym artykule wdrażana jest następująca topologia na platformie Azure, gdzie Zarządzanie API i Service Fabric znajdują się w podsieciach tej samej sieci wirtualnej.

Zaloguj się do platformy Azure i wybierz swoją subskrypcję

Zaloguj się do swojego konta Azure i wybierz subskrypcję przed wykonaniem poleceń Azure.

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

az login
az account set --subscription <guid>

Wdrażanie usługi zaplecza Service Fabric

Przed skonfigurowaniem usługi API Management w celu kierowania ruchu do usługi zaplecza usługi Service Fabric należy najpierw uruchomić usługę do akceptowania żądań.

Utwórz podstawową bezstanową usługę ASP.NET Core Reliable Service przy użyciu domyślnego szablonu projektu Web API. Spowoduje to utworzenie punktu końcowego HTTP dla usługi, który jest udostępniany za pośrednictwem usługi Azure API Management.

Uruchom program Visual Studio jako administrator i utwórz usługę ASP.NET Core:

1. W programie Visual Studio wybierz pozycję Plik —> nowy projekt.

2. Wybierz szablon aplikacji usługi Service Fabric w obszarze Chmura i nadaj mu nazwę "ApiApplication".

3. Wybierz szablon usługi bezstanowej ASP.NET Core i nadaj projektowi nazwę "WebApiService".

4. Wybierz szablon projektu Web API ASP.NET Core 2.1.

5. Po utworzeniu projektu otwórz PackageRoot\ServiceManifest.xml i usuń Port atrybut z konfiguracji zasobu punktu końcowego:

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

   Usunięcie portu umożliwia usłudze Service Fabric dynamiczne określanie portu z zakresu portów aplikacji otwieranych za pośrednictwem sieciowej grupy zabezpieczeń w szablonie usługi Resource Manager klastra, co umożliwia przepływ ruchu do niego z usługi API Management.

6. Naciśnij F5 w programie Visual Studio, aby sprawdzić, czy internetowy interfejs API jest dostępny lokalnie.

   Otwórz narzędzie Service Fabric Explorer i przejdź do określonego wystąpienia usługi ASP.NET Core, aby sprawdzić adres podstawowy, na który nasłuchuje usługa. Dodaj /api/values do podstawowego adresu i otwórz go w przeglądarce, co wywołuje metodę Get w kontrolerze ValuesController w szablonie interfejsu API sieci Web. Zwraca on domyślną odpowiedź dostarczaną przez szablon, tablicę JSON zawierającą dwa ciągi:

   ["value1", "value2"]`
   

   Jest to punkt końcowy udostępniany za pośrednictwem usługi API Management na platformie Azure.

7. Na koniec wdróż aplikację w klastrze na platformie Azure. W programie Visual Studio kliknij prawym przyciskiem myszy projekt Aplikacja i wybierz polecenie Publikuj. Podaj punkt końcowy klastra (na przykład mycluster.southcentralus.cloudapp.azure.com:19000), aby wdrożyć aplikację w klastrze usługi Service Fabric na platformie Azure.

Usługa bezstanowa ASP.NET Core o nazwie fabric:/ApiApplication/WebApiService powinna być teraz uruchomiona w klastrze usługi Service Fabric na platformie Azure.

Pobieranie i zrozumienie szablonów usługi Resource Manager

Pobierz i zapisz następujący plik szablonów i parametrów usługi Resource Manager:

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

Szablon network-apim.json wdraża nową podsieć i sieciową grupę zabezpieczeń w sieci wirtualnej, w której wdrożono klaster usługi Service Fabric.

W poniższych sekcjach opisano zasoby definiowane przez szablon apim.json . Aby uzyskać więcej informacji, skorzystaj z linków do dokumentacji referencyjnej szablonu w każdej sekcji. Konfigurowalne parametry zdefiniowane w pliku parametrów apim.parameters.json są ustawiane w dalszej części tego artykułu.

Microsoft.ApiManagement/service

Microsoft.ApiManagement/service opisuje wystąpienie usługi API Management: nazwę, jednostkę SKU lub warstwę, lokalizację grupy zasobów, informacje o wydawcy i sieć wirtualną.

Microsoft.ApiManagement/service/certificates

Microsoft.ApiManagement/service/certificates konfiguruje zabezpieczenia usługi API Management. Usługa API Management musi uwierzytelniać się w klastrze usługi Service Fabric na potrzeby odnajdywania usług przy użyciu certyfikatu klienta, który ma dostęp do klastra. W tym artykule użyto tego samego certyfikatu określonego wcześniej podczas tworzenia klastra systemu Windows, który domyślnie może służyć do uzyskiwania dostępu do klastra.

W tym artykule użyto tego samego certyfikatu do uwierzytelniania klienta i zabezpieczania komunikacji między węzłami klastra. Jeśli skonfigurowano dostęp do klastra usługi Service Fabric, możesz użyć oddzielnego certyfikatu klienta. Podaj nazwę, hasło i dane (ciąg zakodowany w formacie base-64) pliku klucza prywatnego (pfx) certyfikatu klastra określonego podczas tworzenia klastra usługi Service Fabric.

Microsoft.ApiManagement/service/backends

Microsoft.ApiManagement/service/backends opisuje usługę zaplecza, do którego jest przekazywany ruch.

W przypadku zapleczy usługi Service Fabric klaster jest zapleczem zamiast konkretnej usługi. Dzięki temu pojedyncze zasady mogą kierować do więcej niż jednej usługi w klastrze. Pole adresu URL w tym miejscu jest w pełni kwalifikowaną nazwą usługi w klastrze, do którego wszystkie żądania są domyślnie kierowane, jeśli żadna nazwa usługi nie jest określona w zasadach zaplecza. Możesz użyć fałszywej nazwy usługi, takiej jak "fabric:/fake/service", jeśli nie zamierzasz mieć usługi rezerwowej. resourceId określa punkt końcowy zarządzania klastrem. clientCertificateThumbprint i serverCertificateThumbprints identyfikują certyfikaty używane do uwierzytelniania w klastrze.

Microsoft.ApiManagement/usługa/produkty

Microsoft.ApiManagement/service/products tworzy produkt. W usłudze Azure API Management produkt zawiera co najmniej jeden interfejs API, a także limit przydziału użycia i warunki użytkowania. Po opublikowaniu produktu deweloperzy mogą subskrybować produkt i zacząć korzystać z interfejsów API produktu.

Wprowadź opisową nazwę wyświetlaną i opis produktu. Aby uzyskać dostęp do tego artykułu, wymagana jest subskrypcja, ale zatwierdzenie subskrypcji przez administratora nie jest konieczne. Ten stan produktu jest "opublikowany" i jest widoczny dla subskrybentów.

Microsoft.ApiManagement/service/apis

Microsoft.ApiManagement/service/apis tworzy interfejs API. Interfejs API w usłudze API Management reprezentuje zestaw operacji, które mogą być wywoływane przez aplikacje klienckie. Po dodaniu operacji interfejs API zostanie następnie dodany do produktu i można go opublikować. Po opublikowaniu interfejsu API, można się do niego rejestrować i używać go do wykorzystania przez deweloperów.

• displayName może być dowolną nazwą interfejsu API. W tym artykule użyj "Service Fabric App".
• nazwa zawiera unikatową i opisową nazwę interfejsu API, taką jak "service-fabric-app". Jest on wyświetlany w portalach deweloperów i wydawców.
• serviceUrl odwołuje się do usługi HTTP implementowania interfejsu API. Usługa API Management przekazuje żądania do tego adresu. W przypadku zapleczy usługi Service Fabric ta wartość adresu URL nie jest używana. W tym miejscu możesz umieścić dowolną wartość. Na potrzeby tego artykułu, na przykład "http://servicefabric".
• ścieżka jest dołączana do podstawowego adresu URL usługi API Management. Podstawowy adres URL jest typowy dla wszystkich interfejsów API hostowanych przez wystąpienie usługi API Management. Usługa API Management rozróżnia interfejsy API według ich sufiksu, dlatego sufiks musi być unikatowy dla każdego interfejsu API dla danego wydawcy.
• protokoły określają, które protokoły mogą służyć do uzyskiwania dostępu do interfejsu API. W tym artykule podaj listę http i https.
• path jest sufiksem interfejsu API. W tym artykule użyj polecenia "myapp".

Microsoft.ApiManagement/service/apis/operations

Microsoft.ApiManagement/service/apis/operations Aby móc korzystać z interfejsu API w usłudze API Management, należy dodać do niego operacje. Klienci zewnętrzni używają operacji do komunikowania się z usługą bezstanową ASP.NET Core uruchomioną w klastrze usługi Service Fabric.

Aby dodać operację API frontend, wypełnij odpowiednie pola:

• displayName i opis opisują operację. W tym artykule użyj wartości.
• metoda określa czasownik HTTP. W tym artykule określ polecenie GET.
• element urlTemplate jest dołączany do podstawowego adresu URL interfejsu API i identyfikuje jedną operację HTTP. W tym artykule użyj /api/values jeśli dodano usługę zaplecza .NET lub getMessage jeśli dodano usługę zaplecza Java. Domyślnie ścieżka adresu URL określona tutaj jest ścieżką adresu URL wysłaną do usługi Service Fabric zaplecza. Jeśli w tym miejscu używasz tej samej ścieżki adresu URL, takiej jak "/api/values", operacja działa bez dalszej modyfikacji. W tym miejscu można również określić ścieżkę adresu URL, która różni się od ścieżki adresu URL używanej przez usługę Service Fabric zaplecza. W takim przypadku należy również później określić ścieżkę ponownego zapisywania w zasadach operacji.

Microsoft.ApiManagement/service/apis/policies

Microsoft.ApiManagement/service/apis/policies tworzy zasady zaplecza, które łączą wszystkie elementy ze sobą. W tym miejscu należy skonfigurować zaplecze dla usługi Service Fabric, do którego są kierowane żądania. Te zasady można zastosować do dowolnej operacji interfejsu API. Aby uzyskać więcej informacji, zobacz Omówienie zasad.

Konfiguracja zaplecza dla usługi Service Fabric udostępnia następujące kontrolki routingu żądań:

• Wybór wystąpienia usługi poprzez określenie nazwy wystąpienia usługi Service Fabric, zakodowanej na stałe (na przykład "fabric:/myapp/myservice") lub wygenerowanej na podstawie żądania HTTP (na przykład "fabric:/myapp/users/" + context.Request.MatchedParameters["name"]).
• Rozwiązywanie partycji przez wygenerowanie klucza partycji przy użyciu dowolnego schematu partycjonowania platformy Service Fabric.
• Wybór repliki dla usług stanowych.
• Warunki ponawiania próby rozwiązania, które umożliwiają określenie warunków ponownego rozpoznawania lokalizacji usługi i ponownego wysyłanie żądania.

policyContent jest zawartością XML w formacie Json w formacie ucieczki zasad. W tym artykule utwórz politykę zaplecza, aby przekierowywać żądania bezpośrednio do wdrożonej wcześniej usługi bezstanowej .NET lub Java. set-backend-service Dodaj zasady w obszarze zasady ruchu przychodzącego. Zastąp wartość sf-service-instance-name wartością fabric:/ApiApplication/WebApiService , jeśli wcześniej wdrożono usługę zaplecza platformy .NET lub fabric:/EchoServerApplication/EchoServerService wdrożono usługę Java. Identyfikator zaplecza odwołuje się do zasobu zaplecza, w tym przypadku Microsoft.ApiManagement/service/backends zasobu zdefiniowanego w szablonie apim.json. Identyfikator zaplecza może również odwoływać się do innego zasobu zaplecza utworzonego przy użyciu interfejsów API usługi API Management. W tym artykule ustaw backend-id na wartość 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>

Pełny zestaw atrybutów zasad zaplecza usługi Service Fabric można znaleźć w dokumentacji zaplecza usługi API Management

Ustawianie parametrów i wdrażanie usługi API Management

Wypełnij poniższe puste parametry w apim.parameters.json dla swojego wdrożenia.

Parametr	Wartość
apimInstanceName	sf-apim
apimPublisherEmail	myemail@contosos.com
apimSku	Programista
serviceFabricCertificateName	sfclustertutorialgroup320171031144217
hasło certyfikatu	q6D7nN%6ck@6
odciskPalcaCertyfikatuUsługiFabric	C4C1E541AD512B8065280292A8BA6079C3F26F10
certyfikat usługi Service Fabric	<Ciąg zakodowany w formacie base-64>
ścieżka URL	/api/values
punkt końcowy zarządzania klastrem HTTP	https://mysfcluster.southcentralus.cloudapp.azure.com:19080
polityka przychodząca	<Ciąg XML>

certificatePassword i serviceFabricCertificateThumbprint muszą być zgodne z certyfikatem klastra używanym do skonfigurowania klastra.

serviceFabricCertificate to certyfikat jako ciąg zakodowany w formacie base-64, który można wygenerować przy użyciu następującego skryptu:

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

W inbound_policy zastąp wartość sf-service-instance-name wartością fabric:/ApiApplication/WebApiService , jeśli wcześniej wdrożono usługę zaplecza platformy .NET lub fabric:/EchoServerApplication/EchoServerService jeśli wdrożono usługę Java. backend-id odwołuje się do zasobu backendu, w tym przypadku do Microsoft.ApiManagement/service/backends zasobu zdefiniowanego w szablonie apim.json. Identyfikator backendu może również odwoływać się do innego zasobu backendu utworzonego przy użyciu interfejsów API systemu API Management. W tym artykule przypisz identyfikator zaplecza do wartości 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>

Użyj następującego skryptu, aby wdrożyć pliki szablonu i parametrów usługi Resource Manager dla usługi 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

Testowanie

Teraz możesz spróbować wysłać żądanie do usługi zaplecza w usłudze Service Fabric za pośrednictwem usługi API Management bezpośrednio z witryny Azure Portal.

1. W usłudze API Management wybierz pozycję API.

2. W interfejsie API aplikacji usługi Service Fabric utworzonym w poprzednich krokach wybierz kartę Test , a następnie operację Wartości .

3. Kliknij przycisk Wyślij , aby wysłać żądanie testowe do usługi zaplecza. Powinna zostać wyświetlona odpowiedź HTTP podobna do:

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

Czyszczenie zasobów

Klaster składa się z innych zasobów platformy Azure oprócz samego zasobu klastra. Najprostszym sposobem usunięcia klastra i wszystkich używanych zasobów jest usunięcie grupy zasobów.

Zaloguj się do platformy Azure i wybierz identyfikator subskrypcji, za pomocą którego chcesz usunąć klaster. Identyfikator subskrypcji można znaleźć, logując się do witryny Azure Portal. Usuń grupę zasobów i wszystkie zasoby klastra przy użyciu polecenia cmdletRemove-AzResourceGroup.

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

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

Następne kroki

Dowiedz się więcej o korzystaniu z usługi API Management.

Możesz również użyć witryny Azure Portal do tworzenia zapleczy usługi Service Fabric i zarządzania nimi na potrzeby usługi API Management.