Jak używać interfejsów API komunikacji usług Reliable Services

Usługa Azure Service Fabric jako platforma jest całkowicie niezależna od komunikacji między usługami. Wszystkie protokoły i stosy są dopuszczalne z protokołu UDP do protokołu HTTP. Deweloper usługi decyduje o tym, jak usługi powinny się komunikować. Platforma aplikacji Reliable Services udostępnia wbudowane stosy komunikacji, a także interfejsy API, których można użyć do tworzenia niestandardowych składników komunikacji.

Konfigurowanie komunikacji z usługą

Interfejs API usług Reliable Services używa prostego interfejsu do komunikacji z usługą. Aby otworzyć punkt końcowy usługi, po prostu zaimplementuj ten interfejs:

public interface ICommunicationListener
{
    Task<string> OpenAsync(CancellationToken cancellationToken);

    Task CloseAsync(CancellationToken cancellationToken);

    void Abort();
}

public interface CommunicationListener {
    CompletableFuture<String> openAsync(CancellationToken cancellationToken);

    CompletableFuture<?> closeAsync(CancellationToken cancellationToken);

    void abort();
}

Następnie możesz dodać implementację odbiornika komunikacji, zwracając ją w zastąpieniu metody klasy opartej na usłudze.

W przypadku usług bezstanowych:

public class MyStatelessService : StatelessService
{
    protected override IEnumerable<ServiceInstanceListener> CreateServiceInstanceListeners()
    {
        ...
    }
    ...
}

public class MyStatelessService extends StatelessService {

    @Override
    protected List<ServiceInstanceListener> createServiceInstanceListeners() {
        ...
    }
    ...
}

W przypadku usług stanowych:

    @Override
    protected List<ServiceReplicaListener> createServiceReplicaListeners() {
        ...
    }
    ...

public class MyStatefulService : StatefulService
{
    protected override IEnumerable<ServiceReplicaListener> CreateServiceReplicaListeners()
    {
        ...
    }
    ...
}

W obu przypadkach zwracasz kolekcję odbiorników. Korzystanie z wielu odbiorników umożliwia usłudze nasłuchiwanie w wielu punktach końcowych, potencjalnie przy użyciu różnych protokołów. Na przykład może istnieć odbiornik HTTP i oddzielny odbiornik protokołu WebSocket. Możesz przeprowadzić migrację z niezabezpieczonego do bezpiecznego komunikacji zdalnie, włączając najpierw oba scenariusze, używając zarówno niezabezpieczonego odbiornika, jak i bezpiecznego odbiornika. Każdy odbiornik otrzymuje nazwę, a wynikowa kolekcja nazw : pary adresów są reprezentowane jako obiekt JSON, gdy klient żąda adresów nasłuchiwania dla wystąpienia usługi lub partycji.

W usłudze bezstanowej zastąpienie zwraca kolekcję elementów ServiceInstanceListeners. Element ServiceInstanceListener zawiera funkcję umożliwiającą utworzenie elementu ICommunicationListener(C#) / CommunicationListener(Java) i nada mu nazwę. W przypadku usług stanowych zastąpienie zwraca kolekcję elementów ServiceReplicaListeners. Różni się to nieco od swojego bezstanowego odpowiednika, ponieważ ServiceReplicaListener istnieje możliwość otwarcia ICommunicationListener obiektu w replikach pomocniczych. Nie tylko można używać wielu odbiorników komunikacji w usłudze, ale można również określić, które odbiorniki akceptują żądania w replikach pomocniczych i które nasłuchiwać tylko na replikach podstawowych.

Na przykład można mieć element ServiceRemotingListener, który pobiera wywołania RPC tylko w replikach podstawowych, a drugi niestandardowy odbiornik, który pobiera żądania odczytu w replikach pomocniczych za pośrednictwem protokołu HTTP:

protected override IEnumerable<ServiceReplicaListener> CreateServiceReplicaListeners()
{
    return new[]
    {
        new ServiceReplicaListener(context =>
            new MyCustomHttpListener(context),
            "HTTPReadonlyEndpoint",
            true),

        new ServiceReplicaListener(context =>
            this.CreateServiceRemotingListener(context),
            "rpcPrimaryEndpoint",
            false)
    };
}

Na koniec opisz punkty końcowe wymagane dla usługi w manifeście usługi w sekcji w punktach końcowych.

<Resources>
    <Endpoints>
      <Endpoint Name="WebServiceEndpoint" Protocol="http" Port="80" />
      <Endpoint Name="OtherServiceEndpoint" Protocol="tcp" Port="8505" />
    <Endpoints>
</Resources>

Odbiornik komunikacji może uzyskać dostęp do zasobów punktu końcowego przydzielonych do niego z poziomu CodePackageActivationContext obiektu w pliku ServiceContext. Odbiornik może następnie rozpocząć nasłuchiwanie żądań po jego otwarciu.

var codePackageActivationContext = serviceContext.CodePackageActivationContext;
var port = codePackageActivationContext.GetEndpoint("ServiceEndpoint").Port;

CodePackageActivationContext codePackageActivationContext = serviceContext.getCodePackageActivationContext();
int port = codePackageActivationContext.getEndpoint("ServiceEndpoint").getPort();

Rejestracja adresu usługi

Usługa systemowa o nazwie Nazewnictwo jest uruchamiana w klastrach usługi Service Fabric. Usługa nazewnictwa jest rejestratorem usług i ich adresami, na których nasłuchuje każde wystąpienie lub replika usługi. OpenAsync(C#) / openAsync(Java) Po zakończeniu ICommunicationListener(C#) / CommunicationListener(Java) metody zwracana wartość zostanie zarejestrowana w usłudze Naming Service. Ta zwracana wartość, która zostanie opublikowana w usłudze Naming Service, jest ciągiem, którego wartość może być w ogóle niczym. Ta wartość ciągu jest tym, co klienci widzą, gdy pytają o adres usługi z usługi nazewnictwa.

public Task<string> OpenAsync(CancellationToken cancellationToken)
{
    EndpointResourceDescription serviceEndpoint = serviceContext.CodePackageActivationContext.GetEndpoint("ServiceEndpoint");
    int port = serviceEndpoint.Port;

    this.listeningAddress = string.Format(
                CultureInfo.InvariantCulture,
                "http://+:{0}/",
                port);

    this.publishAddress = this.listeningAddress.Replace("+", FabricRuntime.GetNodeContext().IPAddressOrFQDN);

    this.webApp = WebApp.Start(this.listeningAddress, appBuilder => this.startup.Invoke(appBuilder));

    // the string returned here will be published in the Naming Service.
    return Task.FromResult(this.publishAddress);
}

public CompletableFuture<String> openAsync(CancellationToken cancellationToken)
{
    EndpointResourceDescription serviceEndpoint = serviceContext.getCodePackageActivationContext.getEndpoint("ServiceEndpoint");
    int port = serviceEndpoint.getPort();

    this.publishAddress = String.format("http://%s:%d/", FabricRuntime.getNodeContext().getIpAddressOrFQDN(), port);

    this.webApp = new WebApp(port);
    this.webApp.start();

    /* the string returned here will be published in the Naming Service.
     */
    return CompletableFuture.completedFuture(this.publishAddress);
}

Usługa Service Fabric udostępnia interfejsy API, które umożliwiają klientom i innym usługom monit o ten adres według nazwy usługi. Jest to ważne, ponieważ adres usługi nie jest statyczny. Usługi są przenoszone w klastrze na potrzeby równoważenia zasobów i dostępności. Jest to mechanizm, który umożliwia klientom rozpoznawanie adresu nasłuchiwania dla usługi.

Komunikacja z usługą

Interfejs API usług Reliable Services udostępnia następujące biblioteki do pisania klientów komunikujących się z usługami.

Rozpoznawanie punktu końcowego usługi

Pierwszym krokiem komunikacji z usługą jest rozwiązanie adresu punktu końcowego partycji lub wystąpienia usługi, z którą chcesz porozmawiać. Klasa ServicePartitionResolver(C#) / FabricServicePartitionResolver(Java) narzędzia jest podstawowym elementem pierwotnym, który pomaga klientom określić punkt końcowy usługi w czasie wykonywania. W terminologii usługi Service Fabric proces określania punktu końcowego usługi jest określany jako rozwiązanie punktu końcowego usługi.

Aby połączyć się z usługami w klastrze, można utworzyć usługę ServicePartitionResolver przy użyciu ustawień domyślnych. Jest to zalecane użycie w większości sytuacji:

ServicePartitionResolver resolver = ServicePartitionResolver.GetDefault();

FabricServicePartitionResolver resolver = FabricServicePartitionResolver.getDefault();

Aby połączyć się z usługami w innym klastrze, element ServicePartitionResolver można utworzyć za pomocą zestawu punktów końcowych bramy klastra. Należy pamiętać, że punkty końcowe bramy są po prostu różnymi punktami końcowymi do łączenia się z tym samym klastrem. Na przykład:

ServicePartitionResolver resolver = new  ServicePartitionResolver("mycluster.cloudapp.azure.com:19000", "mycluster.cloudapp.azure.com:19001");

FabricServicePartitionResolver resolver = new  FabricServicePartitionResolver("mycluster.cloudapp.azure.com:19000", "mycluster.cloudapp.azure.com:19001");

Alternatywnie ServicePartitionResolver można podać funkcję do utworzenia obiektu FabricClient do użycia wewnętrznie:

public delegate FabricClient CreateFabricClientDelegate();

public FabricServicePartitionResolver(CreateFabricClient createFabricClient) {
...
}

public interface CreateFabricClient {
    public FabricClient getFabricClient();
}

FabricClient to obiekt używany do komunikowania się z klastrem usługi Service Fabric na potrzeby różnych operacji zarządzania w klastrze. Jest to przydatne, gdy chcesz mieć większą kontrolę nad sposobem interakcji narzędzia rozpoznawania partycji usługi z klastrem. FabricClient program wykonuje buforowanie wewnętrznie i jest ogólnie kosztowne do utworzenia, dlatego ważne jest, aby jak najwięcej używać FabricClient wystąpień.

ServicePartitionResolver resolver = new  ServicePartitionResolver(() => CreateMyFabricClient());

FabricServicePartitionResolver resolver = new  FabricServicePartitionResolver(() -> new CreateFabricClientImpl());

Metoda rozpoznawania jest następnie używana do pobierania adresu usługi lub partycji usługi dla usług partycjonowanych.

ServicePartitionResolver resolver = ServicePartitionResolver.GetDefault();

ResolvedServicePartition partition =
    await resolver.ResolveAsync(new Uri("fabric:/MyApp/MyService"), new ServicePartitionKey(), cancellationToken);

FabricServicePartitionResolver resolver = FabricServicePartitionResolver.getDefault();

CompletableFuture<ResolvedServicePartition> partition =
    resolver.resolveAsync(new URI("fabric:/MyApp/MyService"), new ServicePartitionKey());

Adres usługi można łatwo rozpoznać przy użyciu elementu ServicePartitionResolver, ale wymagana jest większa praca w celu zapewnienia poprawnego użycia rozpoznanego adresu. Klient musi wykryć, czy próba połączenia nie powiodła się z powodu błędu przejściowego i może zostać ponowiona (np. przeniesiona usługa lub jest tymczasowo niedostępna) lub trwały błąd (np. usługa została usunięta lub żądany zasób już nie istnieje). Wystąpienia usługi lub repliki mogą poruszać się z węzła do węzła w dowolnym momencie z wielu powodów. Adres usługi rozwiązany za pośrednictwem elementu ServicePartitionResolver może być nieaktualny, gdy kod klienta próbuje nawiązać połączenie. W takim przypadku klient musi ponownie rozpoznać adres. Podanie poprzedniego ResolvedServicePartition oznacza, że narzędzie rozpoznawania musi spróbować ponownie, a nie po prostu pobrać adres buforowany.

Zazwyczaj kod klienta nie musi bezpośrednio pracować z usługą ServicePartitionResolver. Jest on tworzony i przekazywany do fabryk klienta komunikacji w interfejsie API usług Reliable Services. Fabryki używają programu rozpoznawania nazw wewnętrznie do generowania obiektu klienta, który może służyć do komunikowania się z usługami.

Klienci komunikacji i fabryki

Biblioteka fabryki komunikacji implementuje typowy wzorzec ponawiania prób obsługi błędów, który ułatwia ponawianie prób połączeń w celu rozpoznania punktów końcowych usługi. Biblioteka fabryki udostępnia mechanizm ponawiania podczas udostępniania procedur obsługi błędów.

ICommunicationClientFactory(C#) / CommunicationClientFactory(Java) definiuje interfejs podstawowy implementowany przez fabrykę klienta komunikacji, która generuje klientów, którzy mogą komunikować się z usługą Service Fabric. Implementacja elementu CommunicationClientFactory zależy od stosu komunikacji używanego przez usługę Service Fabric, w którym klient chce się komunikować. Interfejs API usług Reliable Services udostępnia element CommunicationClientFactoryBase<TCommunicationClient>. Zapewnia podstawową implementację interfejsu CommunicationClientFactory i wykonuje zadania wspólne dla wszystkich stosów komunikacji. (Te zadania obejmują użycie elementu ServicePartitionResolver w celu określenia punktu końcowego usługi). Klienci zazwyczaj implementują abstrakcyjną klasę CommunicationClientFactoryBase w celu obsługi logiki specyficznej dla stosu komunikacji.

Klient komunikacji po prostu odbiera adres i używa go do nawiązania połączenia z usługą. Klient może używać dowolnego żądanego protokołu.

public class MyCommunicationClient : ICommunicationClient
{
    public ResolvedServiceEndpoint Endpoint { get; set; }

    public string ListenerName { get; set; }

    public ResolvedServicePartition ResolvedServicePartition { get; set; }
}

public class MyCommunicationClient implements CommunicationClient {

    private ResolvedServicePartition resolvedServicePartition;
    private String listenerName;
    private ResolvedServiceEndpoint endPoint;

    /*
     * Getters and Setters
     */
}

Fabryka klienta jest odpowiedzialna przede wszystkim za tworzenie klientów komunikacyjnych. W przypadku klientów, którzy nie utrzymują trwałego połączenia, takiego jak klient HTTP, fabryka musi tylko utworzyć i zwrócić klienta. Inne protokoły, które utrzymują trwałe połączenie, takie jak niektóre protokoły binarne, powinny być również weryfikowane (ValidateClient(string endpoint, MyCommunicationClient client)) przez fabrykę, aby określić, czy połączenie musi zostać ponownie utworzone.

public class MyCommunicationClientFactory : CommunicationClientFactoryBase<MyCommunicationClient>
{
    protected override void AbortClient(MyCommunicationClient client)
    {
    }

    protected override Task<MyCommunicationClient> CreateClientAsync(string endpoint, CancellationToken cancellationToken)
    {
    }

    protected override bool ValidateClient(MyCommunicationClient clientChannel)
    {
    }

    protected override bool ValidateClient(string endpoint, MyCommunicationClient client)
    {
    }
}

public class MyCommunicationClientFactory extends CommunicationClientFactoryBase<MyCommunicationClient> {

    @Override
    protected boolean validateClient(MyCommunicationClient clientChannel) {
    }

    @Override
    protected boolean validateClient(String endpoint, MyCommunicationClient client) {
    }

    @Override
    protected CompletableFuture<MyCommunicationClient> createClientAsync(String endpoint) {
    }

    @Override
    protected void abortClient(MyCommunicationClient client) {
    }
}

Na koniec program obsługi wyjątków jest odpowiedzialny za określenie akcji, która ma być wykonywana w przypadku wystąpienia wyjątku. Wyjątki są klasyfikowane do ponawiania prób i nie można ich ponowić.

• Wyjątki niemożliwe do ponawiania po prostu są ponownie przywracane do elementu wywołującego.
• wyjątki z możliwością ponawiania prób są dalej podzielone na przejściowe i nie przejściowe.
  • Wyjątki przejściowe to te, które można po prostu ponowić bez ponownego rozpoznawania adresu punktu końcowego usługi. Będą one obejmować przejściowe problemy z siecią lub odpowiedzi na błędy usługi inne niż te, które wskazują, że adres punktu końcowego usługi nie istnieje.
  • Wyjątki nie przejściowe to wyjątki, które wymagają ponownego rozpoznania adresu punktu końcowego usługi. Obejmują one wyjątki wskazujące, że nie można uzyskać dostępu do punktu końcowego usługi, co wskazuje, że usługa została przeniesiona do innego węzła.

Podejmuje TryHandleException decyzję o danym wyjątku. Jeśli nie wie, jakie decyzje należy podjąć w sprawie wyjątku, powinien zwrócić wartość false. Jeśli wie, jaką decyzję należy podjąć, należy odpowiednio ustawić wynik i zwrócić wartość true.

class MyExceptionHandler : IExceptionHandler
{
    public bool TryHandleException(ExceptionInformation exceptionInformation, OperationRetrySettings retrySettings, out ExceptionHandlingResult result)
    {
        // if exceptionInformation.Exception is known and is transient (can be retried without re-resolving)
        result = new ExceptionHandlingRetryResult(exceptionInformation.Exception, true, retrySettings, retrySettings.DefaultMaxRetryCount);
        return true;


        // if exceptionInformation.Exception is known and is not transient (indicates a new service endpoint address must be resolved)
        result = new ExceptionHandlingRetryResult(exceptionInformation.Exception, false, retrySettings, retrySettings.DefaultMaxRetryCount);
        return true;

        // if exceptionInformation.Exception is unknown (let the next IExceptionHandler attempt to handle it)
        result = null;
        return false;
    }
}

public class MyExceptionHandler implements ExceptionHandler {

    @Override
    public ExceptionHandlingResult handleException(ExceptionInformation exceptionInformation, OperationRetrySettings retrySettings) {

        /* if exceptionInformation.getException() is known and is transient (can be retried without re-resolving)
         */
        result = new ExceptionHandlingRetryResult(exceptionInformation.getException(), true, retrySettings, retrySettings.getDefaultMaxRetryCount());
        return true;


        /* if exceptionInformation.getException() is known and is not transient (indicates a new service endpoint address must be resolved)
         */
        result = new ExceptionHandlingRetryResult(exceptionInformation.getException(), false, retrySettings, retrySettings.getDefaultMaxRetryCount());
        return true;

        /* if exceptionInformation.getException() is unknown (let the next ExceptionHandler attempt to handle it)
         */
        result = null;
        return false;

    }
}

Zebranie wszystkich elementów

Za pomocą elementu ICommunicationClient(C#) / CommunicationClient(Java), ICommunicationClientFactory(C#) / CommunicationClientFactory(Java)i IExceptionHandler(C#) / ExceptionHandler(Java) utworzonego wokół protokołu komunikacyjnego, ServicePartitionClient(C#) / FabricServicePartitionClient(Java) wszystkie opakowuje go razem i zapewnia pętlę rozpoznawania adresów partycji błędów i obsługi błędów wokół tych składników.

private MyCommunicationClientFactory myCommunicationClientFactory;
private Uri myServiceUri;

var myServicePartitionClient = new ServicePartitionClient<MyCommunicationClient>(
    this.myCommunicationClientFactory,
    this.myServiceUri,
    myPartitionKey);

var result = await myServicePartitionClient.InvokeWithRetryAsync(async (client) =>
   {
      // Communicate with the service using the client.
   },
   CancellationToken.None);

private MyCommunicationClientFactory myCommunicationClientFactory;
private URI myServiceUri;

FabricServicePartitionClient myServicePartitionClient = new FabricServicePartitionClient<MyCommunicationClient>(
    this.myCommunicationClientFactory,
    this.myServiceUri,
    myPartitionKey);

CompletableFuture<?> result = myServicePartitionClient.invokeWithRetryAsync(client -> {
      /* Communicate with the service using the client.
       */
   });

Następne kroki

• ASP.NET Core z usługami Reliable Services
• Zdalne wywołania procedur za pomocą komunikacji zdalnej usług Reliable Services
• Komunikacja WCF przy użyciu usług Reliable Services