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

Wdrażanie usługi Azure API Management z usługą Service Fabric odbywa się w ramach zaawansowanego scenariusza. Usługa API Management jest przydatna, gdy trzeba opublikować interfejsy API z obszernym zestawem reguł rozsyłania dla usług zaplecza Service Fabric. Aplikacje w chmurze zwykle potrzebują bramy frontonu, aby udostępniać pojedynczy punkt danych przychodzących dla użytkowników, urządzeń lub innych aplikacji. W usłudze Service Fabric bramą może być dowolna usługa bezstanowa przeznaczona dla ruchu przychodzącego, na przykład aplikacja ASP.NET Core albo usługa Event Hubs, IoT Hub lub 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. Wykonanie podanych instrukcji pozwoli wdrożyć usługę API Management w sieci wirtualnej i skonfigurować kierowanie ruchu do bezstanowych usług zaplecza za pomocą operacji interfejsu API. Aby dowiedzieć się więcej o scenariuszach użycia usługi Azure API Management z usługą Service Fabric, zobacz artykuł z omówieniem.

Uwaga

Do interakcji z platformą Azure zalecamy używanie modułu Azure Az w programie PowerShell. 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ń.
• W przypadku wdrażania klastra systemu Windows skonfiguruj środowisko deweloperskie w systemie Windows. Zainstaluj program Visual Studio 2019 i programowanie na platformie Azure, ASP.NET i tworzenie aplikacji internetowych oraz międzyplatformowe obciążenia programistyczne dla platformy .NET Core. Następnie skonfiguruj środowisko deweloperskie 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 usługi Resource Manager usługi API Management jest wstępnie skonfigurowany do używania nazw sieci wirtualnej, podsieci i sieciowej grupy zabezpieczeń, które zostały skonfigurowane w samouczku klastra systemu Windows W tym artykule wdrożono następującą topologię na platformie Azure, w której usługi API Management i Service Fabric znajdują się w podsieciach tej samej sieci wirtualnej:

Logowanie do platformy Azure i wybieranie subskrypcji

Przed wykonaniem poleceń platformy Azure zaloguj się na konto platformy Azure i wybierz subskrypcję.

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

az login
az account set --subscription <guid>

Wdrażanie usługi zaplecza Service Fabric

Do skonfigurowania usługi API Management pod kątem kierowania ruchu do usługi zaplecza Service Fabric potrzebna jest uruchomiona usługa, umożliwiająca akceptowanie żądań.

Utwórz podstawową bezstanową usługę ASP.NET Core Reliable Service przy użyciu domyślnego szablonu projektu internetowego interfejsu API. Spowoduje to utworzenie punktu końcowego HTTP dla usługi, który należy udostępnić 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. W obszarze Chmura wybierz szablon aplikacji Service Fabric i nadaj mu nazwę „ApiApplication”.

3. Wybierz szablon bezstanowej usługi ASP.NET Core i nazwij projekt „WebApiService”.

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

5. Po utworzeniu projektu otwórz plik PackageRoot\ServiceManifest.xml i usuń atrybut Port 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. W programie Visual Studio naciśnij klawisz F5, aby sprawdzić, czy internetowy interfejs API jest dostępny lokalnie.

   Otwórz narzędzie Service Fabric Explorer i przejdź do konkretnego wystąpienia usługi ASP.NET Core, aby wyświetlić podstawowy adres, na jakim nasłuchuje ta usługa. Dodaj ciąg /api/values do podstawowego adresu, a następnie otwórz ten adres w przeglądarce. Spowoduje to wywołanie metody Get klasy ValuesController w szablonie internetowego interfejsu API. Szablon zwróci domyślną odpowiedź — tablicę JSON, zawierającą dwa ciągi:

   ["value1", "value2"]`
   

   Jest to punkt końcowy, który należy udostępnić za pomocą usługi API Management na platformie Azure.

7. Teraz wdróż aplikację w klastrze na platformie Azure. W programie Visual Studio kliknij prawym przyciskiem myszy projekt aplikacji, a następnie wybierz polecenie Opublikuj. 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.

W klastrze powinna teraz być uruchomiona bezstanowa usługa ASP.NET Core o nazwie fabric:/ApiApplication/WebApiService.

Pobieranie szablonów usługi Resource Manager i zapoznawanie się z nimi

Pobierz i zapisz plik parametrów oraz następujące szablony usługi Resource Manager:

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

Szablon network-apim.json umożliwia wdrożenie nowej podsieci i sieciowej grupy zabezpieczeń w sieci wirtualnej, w której wdrożono klaster usługi Service Fabric.

W poniższych sekcjach opisano zasoby definiowane za pomocą szablonu apim.json. Poszczególne sekcje zawierają linki do dokumentacji szablonów, umożliwiające uzyskanie dodatkowych informacji. Konfigurowalne parametry, zdefiniowane w pliku apim.parameters.json, zostaną ustawione w dalszej części tego artykułu.

Microsoft.ApiManagement/service

Szablon Microsoft.ApiManagement/service opisuje wystąpienie usługi API Management i zawiera następujące informacje: nazwę, jednostkę SKU lub warstwę, lokalizację grupy zasobów oraz informacje o wydawcy i sieci wirtualnej.

Microsoft.ApiManagement/service/certificates

Szablon Microsoft.ApiManagement/service/certificates umożliwia konfigurowanie zabezpieczeń usługi API Management. W ramach odnajdywania usługi usługa API Management musi zostać uwierzytelniona w klastrze usługi Service Fabric 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 zabezpieczeń węzła-węzła klastra. Jeśli masz skonfigurowany osobny certyfikat klienta, możesz go używać do korzystania z klastra usługi Service Fabric. Podaj nazwę, hasło i dane (szyfrowany ciąg base64) dotyczące pliku klucza prywatnego (pfx) certyfikatu klastra, który został określony podczas tworzenia klastra usługi Service Fabric.

Microsoft.ApiManagement/service/backends

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

W przypadku usługi Service Fabric zapleczem jest klaster usługi Service Fabric, a nie określona usługa Service Fabric. Dzięki temu za pomocą jednej zasady można kierować ruch do więcej niż jednej usługi w klastrze. Pole url zawiera w pełni kwalifikowaną nazwę usługi w klastrze, do której są domyślnie kierowane wszystkie żądania, jeśli w zasadach zaplecza nie podano nazwy usługi. Jeśli nie potrzebujesz usługi rezerwowej, możesz użyć wymyślonej nazwy, takiej jak „fabric:/fake/service”. Pole resourceId określa punkt końcowy zarządzania klastrem. Pola clientCertificateThumbprint i serverCertificateThumbprints identyfikują certyfikaty używane do uwierzytelniania w klastrze.

Microsoft.ApiManagement/service/products

Szablon Microsoft.ApiManagement/service/products umożliwia utworzenie produktu. W usłudze Azure API Management produkt zawiera co najmniej jeden interfejs API oraz limit przydziału użycia i warunki użytkowania. Po opublikowaniu produktu deweloperzy mogą go zasubskrybować i zacząć korzystać z jego interfejsów API.

W polu displayName wpisz opisową nazwę produktu, a w polu description — opis. W tym artykule wymagana jest subskrypcja, ale zatwierdzenie subskrypcji przez administratora nie jest. Stan tego produktu ma wartość „opublikowany” i jest widoczny dla subskrybentów.

Microsoft.ApiManagement/service/apis

Szablon Microsoft.ApiManagement/service/apis umożliwia utworzenie interfejsu API. Interfejs API usługi API Management reprezentuje zestaw operacji, które mogą być wywoływane przez aplikacje klienckie. Po dodaniu operacji do produktu jest dodawany interfejs API, który można opublikować. Opublikowany interfejs API można zasubskrybować, a deweloperzy mogą go używać.

• Pole displayName może zawierać dowolną nazwę interfejsu API. W tym artykule użyj polecenia "Aplikacja usługi Service Fabric".
• Pole name zawiera unikatową i opisową nazwę interfejsu API, taką jak „service-fabric-app”. Jest ona wyświetlana w portalach dewelopera i wydawcy.
• Pole serviceUrl zawiera odwołanie do usługi HTTP implementującej interfejs API. Usługa API Management przekazuje żądania na ten adres. W przypadku zapleczy usługi Service Fabric ta wartość adresu URL nie jest używana. Można tu wpisać dowolną wartość. Na potrzeby tego artykułu, na przykład "http://servicefabric".
• Wartość pola path jest dołączana do podstawowego adresu URL usługi API Management. Podstawowy adres URL jest wspólny dla wszystkich interfejsów API hostowanych przez wystąpienie usługi API Management. W usłudze API Management interfejsy API są rozróżniane na podstawie sufiksów, dlatego sufiksy poszczególnych interfejsów API dla danego wydawcy muszą być unikatowe.
• Pole protocols określa, których protokołów można używać w celu uzyskania dostępu do interfejsu API. W tym artykule podaj listę http i https.
• Pole path jest sufiksem interfejsu API. W tym artykule użyj polecenia "myapp".

Microsoft.ApiManagement/service/apis/operations

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

Aby dodać operację interfejsu API frontonu, podaj następujące wartości:

• Pola displayName i description opisują operację. W tym artykule użyj wartości.
• Pole method określa polecenie HTTP. W tym artykule określ polecenie GET.
• Wartość pola urlTemplate jest dołączana do podstawowego adresu URL interfejsu API i określa pojedynczą operację HTTP. W tym artykule użyj /api/values polecenia , jeśli dodano usługę zaplecza platformy .NET lub getMessage jeśli dodano usługę zaplecza Java. Określona tutaj ścieżka URL jest domyślnie wysyłana do usługi Service Fabric zaplecza. W przypadku podania ścieżki URL używanej przez usługę, takiej jak „/api/values”, operacja działa bez dodatkowych modyfikacji. Można również podać ścieżkę URL, która różni się od ścieżki URL używanej przez usługę Service Fabric zaplecza. W takim przypadku należy później określić nadpisanie ścieżki w zasadach operacji.

Microsoft.ApiManagement/service/apis/policies

Szablon Microsoft.ApiManagement/service/apis/policies umożliwia utworzenie zasad zaplecza, które pozwalają zintegrować wszystkie elementy. Zasady te umożliwiają skonfigurowanie usługi Service Fabric zaplecza, do której są kierowane żądania. 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 możliwości sterowania routingiem żądań:

• Wybieranie wystąpienia usługi przez podanie nazwy wystąpienia usługi Service Fabric — zakodowanej (na przykład "fabric:/myapp/myservice") lub wygenerowanej na podstawie żądania HTTP (na przykład "fabric:/myapp/users/" + context.Request.MatchedParameters["name"]).
• Rozpoznawanie partycji przez wygenerowanie klucza partycji przy użyciu dowolnego schematu partycjonowania usługi Service Fabric.
• Wybieranie repliki dla usług stanowych.
• Warunki ponownego rozpoznawania, które umożliwiają określenie warunków ponownego rozpoznawania lokalizacji usługi i wysyłania żądania.

policyContent to zawartość XML zasad, ujęta w znaki Json zmieniające znaczenie. W tym artykule utwórz zasady zaplecza, aby kierować żądania bezpośrednio do wdrożonej wcześniej usługi bezstanowej .NET lub Java. Dodaj zasady set-backend-service w obszarze zasad ruchu przychodzącego. Wartość sf-service-instance-name zastąp ciągiem fabric:/ApiApplication/WebApiService, jeśli wcześniej wdrożono usługę zaplecza platformy .NET, lub ciągiem fabric:/EchoServerApplication/EchoServerService, jeśli wdrożono usługę platformy Java. Pole backend-id zawiera odwołanie do zasobu zaplecza, w tym przypadku zasobu Microsoft.ApiManagement/service/backends zdefiniowanego w szablonie apim.json. Pole backend-id może także odwoływać się do innego zasobu zaplecza, utworzonego za pomocą interfejsów API usługi API Management. W tym artykule ustaw identyfikator zaplecza 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>

Aby uzyskać pełny zestaw atrybutów zasad zaplecza usługi Service Fabric, zobaczAPI Management back-end documentation (Dokumentacja zaplecza usługi API Management).

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

Wypełnij następujące puste parametry szablonu apim.parameters.json dla danego wdrożenia.

Parametr	Wartość
apimInstanceName	sf-apim
apimPublisherEmail	myemail@contosos.com
apimSku	Deweloper
serviceFabricCertificateName	sfclustertutorialgroup320171031144217
certificatePassword	q6D7nN%6ck@6
serviceFabricCertificateThumbprint	C4C1E541AD512B8065280292A8BA6079C3F26F10
serviceFabricCertificate	<ciąg zakodowany w formacie Base-64>
url_path	/api/values
clusterHttpManagementEndpoint	https://mysfcluster.southcentralus.cloudapp.azure.com:19080
inbound_policy	<Ciąg XML>

Parametry certificatePassword i serviceFabricCertificateThumbprint muszą być zgodne z certyfikatem klastra użytym podczas konfigurowania klastra.

Parametr serviceFabricCertificate zawiera certyfikat w postaci ciągu zakodowanego w formacie Base-64, który można wygenerować za pomocą 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 parametrze inbound_policy wartość sf-service-instance-name zastąp ciągiem fabric:/ApiApplication/WebApiService, jeśli wcześniej wdrożono usługę zaplecza platformy .NET, lub ciągiem fabric:/EchoServerApplication/EchoServerService, jeśli wdrożono usługę platformy Java. Pole backend-id zawiera odwołanie do zasobu zaplecza, w tym przypadku zasobu Microsoft.ApiManagement/service/backends zdefiniowanego w szablonie apim.json. Pole backend-id może także odwoływać się do innego zasobu zaplecza, utworzonego za pomocą interfejsów API usługi API Management. W tym artykule ustaw identyfikator zaplecza 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>

Następujący skrypt umożliwia wdrożenie szablonu i plików 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 wysłać żądanie do usługi zaplecza Service Fabric za pośrednictwem usługi API Management bezpośrednio z witryny Azure Portal.

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

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

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

   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 poza samym zasobem klastra. Najprostszym sposobem na usunięcie klastra i wszystkich wykorzystywanych przez niego 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 uzyskać po zalogowaniu się do witryny Azure Portal. Usuń grupę zasobów i wszystkie zasoby klastra przy użyciu polecenia cmdlet Remove-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.