Chiamate di streaming nelle librerie client di Cloud per Java

Le chiamate in streaming consentono pattern di interazione più complessi rispetto alla semplice richiesta/risposta, consentendo l'invio o la ricezione di più messaggi tramite una singola connessione.

Le librerie client di Cloud per Java supportano tre tipi di chiamate di streaming:

  • Streaming lato server:il server ti invia un flusso di risposte.
  • Streaming client:invii un flusso di richieste al server.
  • Streaming bidirezionale: puoi inviare un flusso di richieste al server e il server può inviarti un flusso di risposte.

Le implementazioni di streaming sono modellate in base alle implementazioni gRPC-Java per lo streaming server, client e bidirezionale.

Supporto dello streaming su tutti i trasporti

Lo streaming è completamente supportato quando utilizzi gRPC, ma solo parzialmente per HttpJson. Per informazioni sul supporto dello streaming, consulta la tabella seguente.

Tipo di streaming gRPC HttpJson
Server Streaming Supportato Supportato
Streaming client Supportato Non supportata
Streaming bidirezionale Supportato Non supportata

Le chiamate unarie (non in streaming) sono supportate sia per gRPC che per HttpJson.

Determinare il tipo di streaming

Per determinare il tipo di streaming della chiamata, controlla il tipo Callable restituito:

  • ServerStreamingCallable: streaming dal server.
  • ClientStreamingCallable: streaming client.
  • BidiStreamingCallable: streaming bidirezionale.

Ad esempio, utilizzando Java-Aiplatform e Java-Speech:

// Server Streaming
ServerStreamingCallable<ReadTensorboardBlobDataRequest, ReadTensorboardBlobDataResponse> callable = aiplatformClient.readTensorboardBlobDataCallable();

// Bidirectional Streaming
BidiStreamingCallable<StreamingRecognizeRequest, StreamingRecognizeResponse> callable = speechClient.streamingRecognizeCallable();

Effettuare chiamate in streaming

L'effettuazione di una chiamata di streaming varia a seconda che tu stia utilizzando lo streaming lato server o lo streaming bidirezionale.

Streaming lato server

Lo streaming lato server non richiede un'implementazione aggiuntiva. La classe ServerStream consente di iterare il flusso di risposte. Utilizzando Java-Maps-Routing come esempio, di seguito viene mostrato come chiamare l'API Server Streaming:

try (RoutesClient routesClient = RoutesClient.create()) {
  ServerStreamingCallable<ComputeRouteMatrixRequest, RouteMatrixElement> computeRouteMatrix =
    routesClient.computeRouteMatrixCallable();  
  ServerStream<RouteMatrixElement> stream = computeRouteMatrix.call(
    ComputeRouteMatrixRequest.newBuilder().build());
  for (RouteMatrixElement element : stream) {
    // Do something with response
  }
}

In questo esempio, il client invia un singolo ComputeRouteMatrixRequest e riceve un flusso di risposte.

Streaming bidirezionale

Lo streaming bidirezionale richiede un'implementazione aggiuntiva per effettuare la chiamata. Utilizzando Java-Speech come esempio, i seguenti passaggi forniscono un'implementazione di esempio per effettuare una chiamata di streaming bidirezionale.

Innanzitutto, implementa l'interfaccia ResponseObserver utilizzando il seguente codice come linea guida:

class BidiResponseObserver<T> implements ResponseObserver<T> {
  private final List<T> responses = new ArrayList<>();
  private final SettableApiFuture<List<T>> future = SettableApiFuture.create();

  @Override
  public void onStart(StreamController controller) {
    // no-op
  }

  @Override
  public void onResponse(T response) {
    responses.add(response);
  }

  @Override
  public void onError(Throwable t) {
    future.setException(t);
  }

  @Override
  public void onComplete() {
    future.set(responses);
  }

  public SettableApiFuture<List<T>> getFuture() {
    return future;
  }
}

A tale scopo, procedi nel seguente modo:

  1. Crea un'istanza dell'osservatore: java BidiResponseObserver<StreamingRecognizeResponse> responseObserver = new BidiResponseObserver<>();
  2. Passa l'observer al callable: java ClientStream<EchoRequest> clientStream = speechClient.streamingRecognizeCallable().splitCall(responseObserver);
  3. Invia le richieste al server e chiudi lo stream al termine: java clientStream.send(StreamingRecognizeRequest.newBuilder().build()); clientStream.send(StreamingRecognizeRequest.newBuilder().build()); // ... other requests ... clientStream.send(StreamingRecognizeRequest.newBuilder().build()); clientStream.closeSend();

  4. Itera le risposte: ```java List responses = responseObserver.getFuture().get();

    for (StreamingRecognizeResponse response : responses) { // Do something with response } ```

Errori di streaming non supportati

Per le librerie client che supportano sia i trasporti gRPC che HTTP/JSON, è possibile configurare accidentalmente la libreria client per richiamare una chiamata di streaming non supportata. Ad esempio, la seguente configurazione mostra il client HttpJson di Java-Speech che effettua una chiamata di streaming bidirezionale:

// SpeechClient is configured to use HttpJson
try (SpeechClient speechClient = SpeechClient.create(SpeechSettings.newHttpJsonBuilder().build())) {
  // Bidi Callable is not supported in HttpJson
  BidiStreamingCallable<StreamingRecognizeRequest, StreamingRecognizeResponse> callable = speechClient.streamingRecognizeCallable();
  ...
}

Ciò non comporta un errore di compilazione, ma viene visualizzato come errore di runtime: 

Not implemented: streamingRecognizeCallable(). REST transport is not implemented for this method yet.
Important: The client library MUST be configured with gRPC to use client or bidirectional streaming.