Trasmissione di metadati personalizzati
Scopra come inviare e ricevere coppie chiave-valore personalizzate come metadati nelle richieste e nelle risposte gRPC.
Trasmissione di metadati personalizzati è una lezione gRPC & High Performance APIs gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento gRPC & High Performance APIs, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso gRPC & High Performance APIs include 4 lezioni in totale.
Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.
What is gRPC Metadata?
In gRPC, metadata refers to key-value pairs that are attached to an RPC call, similar to HTTP headers.
Unlike the main message payload, metadata carries information about the call itself, rather than the application data being transmitted.
- It's for auxiliary data.
- It travels with requests and responses.
- It's separate from your protobuf messages.
Why Use Metadata?
Metadata is incredibly useful for carrying information that doesn't belong in your service's primary request or response messages.
Common use cases include:
- Authentication Tokens: Sending JWTs or API keys.
- Tracing IDs: Propagating unique request IDs for distributed tracing.
- Custom Headers: Any other contextual information needed by your services.
Metadata Structure & Types
Metadata consists of a list of key-value pairs.
- Keys: Are case-insensitive ASCII strings.
- Values: Can be either ASCII strings or binary data.
For binary values, the key must end with -bin (e.g., auth-token-bin). gRPC handles the encoding for these.
Client: Sending Request Metadata
Clients attach metadata to outgoing requests using the gRPC Metadata class. This object is then added to the gRPC call stub.
You create Metadata.Key objects to define your header keys and their marshallers (how they are converted to/from strings or bytes).
Client: Sending Metadata Example
This Java client snippet shows how to create a Metadata object and attach it to your stub before making an RPC call. Ensure your `hello.proto` is compiled.
package com.coddykit.grpc;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import io.grpc.Metadata;
import io.grpc.stub.MetadataUtils;
import io.grpc.StatusRuntimeException;
import java.util.concurrent.TimeUnit;
public class GrpcClient {
private final ManagedChannel channel;
private final GreeterGrpc.GreeterBlockingStub blockingStub;
public GrpcClient(String host, int port) {
this.channel = ManagedChannelBuilder.forAddress(host, port)
.usePlaintext()
.build();
blockingStub = GreeterGrpc.newBlockingStub(channel);
}
public void shutdown() throws InterruptedException {
channel.shutdown().awaitTermination(5, TimeUnit.SECONDS);
}
public void sayHello(String name, String customValue) {
System.out.println("Sending custom-key: " + customValue);
HelloRequest request = HelloRequest.newBuilder().setName(name).build();
// 1. Create Metadata object
Metadata headers = new Metadata();
// 2. Define a Metadata.Key for your header
Metadata.Key<String> customKey = Metadata.Key.of(
"custom-key", Metadata.ASCII_STRING_MARSHALLER);
// 3. Put the key-value pair into Metadata
headers.put(customKey, customValue);
// 4. Attach metadata to the stub
GreeterGrpc.GreeterBlockingStub stubWithMetadata =
MetadataUtils.attachHeaders(blockingStub, headers);
try {
HelloReply response = stubWithMetadata.SayHello(request);
System.out.println("Greeting: " + response.getMessage());
} catch (StatusRuntimeException e) {
System.err.println("RPC failed: " + e.getStatus());
}
}
public static void main(String[] args) throws Exception {
GrpcClient client = new GrpcClient("localhost", 50051);
try {
client.sayHello("CoddyKit User", "my-session-id-123");
} finally {
client.shutdown();
}
}
}Server: Receiving Request Metadata
On the server side, incoming metadata is typically accessed using a ServerInterceptor.
An interceptor sits between the gRPC runtime and your service implementation, allowing you to inspect and modify calls.
- It receives a
Metadataobject. - You can extract values using
Metadata.Key. - Often, metadata is then added to the
Contextfor easy access within service methods.
Server: Receiving Metadata Example
This Java server example shows a ServerInterceptor extracting a custom header and making it available to the service via Context. Ensure your `hello.proto` is compiled.
package com.coddykit.grpc;
import io.grpc.Context;
import io.grpc.Metadata;
import io.grpc.Server;
import io.grpc.ServerBuilder;
import io.grpc.ServerCall;
import io.grpc.ServerCallHandler;
import io.grpc.ServerInterceptor;
import io.grpc.stub.StreamObserver;
import java.io.IOException;
public class GrpcServer {
private Server server;
// Context.Key to store the custom value for the service method
private static final Context.Key<String> CUSTOM_VALUE_CTX_KEY = Context.key("custom-value");
private void start() throws IOException {
int port = 50051;
server = ServerBuilder.forPort(port)
.addService(new GreeterService())
.intercept(new CustomHeaderInterceptor()) // Add our interceptor
.build()
.start();
System.out.println("Server started, listening on " + port);
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
System.err.println("*** shutting down server");
try { GrpcServer.this.stop(); }
catch (InterruptedException e) { e.printStackTrace(System.err); }
System.err.println("*** server shut down");
}));
}
private void stop() throws InterruptedException {
if (server != null) { server.shutdown().awaitTermination(); }
}
private void blockUntilShutdown() throws InterruptedException {
if (server != null) { server.awaitTermination(); }
}
public static void main(String[] args) throws Exception {
final GrpcServer server = new GrpcServer();
server.start();
server.blockUntilShutdown();
}
static class GreeterService extends GreeterGrpc.GreeterImplBase {
@Override
public void SayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
// Retrieve custom value from Context
String customValue = CUSTOM_VALUE_CTX_KEY.get();
System.out.println("Service received custom-key: " + customValue);
HelloReply reply = HelloReply.newBuilder()
.setMessage("Hello " + request.getName() +
"! Custom value: " + customValue)
.build();
responseObserver.onNext(reply);
responseObserver.onCompleted();
}
}
static class CustomHeaderInterceptor implements ServerInterceptor {
// Define the Metadata.Key for our custom header
private static final Metadata.Key<String> CUSTOM_KEY =
Metadata.Key.of("custom-key", Metadata.ASCII_STRING_MARSHALLER);
@Override
public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
ServerCall<ReqT, RespT> call,
Metadata headers,
ServerCallHandler<ReqT, RespT> next) {
// Get the custom value from incoming headers
String customValue = headers.get(CUSTOM_KEY);
System.out.println("Interceptor received custom-key: " + customValue);
// Store the custom value in the Context for the service to access
Context context = Context.current().withValue(CUSTOM_VALUE_CTX_KEY, customValue);
// Proceed with the call within the new context
return Context.current().call(() -> next.startCall(call, headers));
}
}
}Server: Sending Response Metadata
Servers can also send metadata back to clients, either as response headers or response trailers.
- Response Headers: Sent before any response messages. Use
ServerCall.sendHeaders(Metadata). - Response Trailers: Sent at the end of the RPC, after all response messages. Often used for status or final context.
Both are handled within the ServerCall object, which is available in interceptors or advanced service implementations.
Client: Receiving Response Metadata
Clients can access the response metadata (headers and trailers) through the ClientCall.Listener interface, typically used with asynchronous (non-blocking) stubs.
The listener provides callbacks like onHeaders(Metadata) and onTrailers(Metadata) where you can inspect the incoming metadata.
Metadata Use Cases
Which of the following is NOT a typical use case for gRPC metadata?
Recap: Metadata in gRPC
You've learned how gRPC metadata acts like HTTP headers, carrying essential non-application data alongside your RPC calls.
- Clients send metadata with requests.
- Servers receive and process request metadata (often via interceptors).
- Servers can send response metadata (headers/trailers) back to clients.
- Metadata is crucial for cross-cutting concerns like authentication and tracing.
Mastering metadata allows for more robust and observable gRPC services!
Impara gRPC & High Performance APIs con un tutor IA — gratis
Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.
- Corsi
- 12
- Lezioni
- 48
Domande Frequenti
La lezione «Trasmissione di metadati personalizzati» è gratuita?
Sì — il testo completo di «Trasmissione di metadati personalizzati» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso gRPC & High Performance APIs, passa a CoddyKit PRO. Il corso gRPC & High Performance APIs include 4 lezioni in totale.
Cosa imparerò in «Trasmissione di metadati personalizzati»?
Scopra come inviare e ricevere coppie chiave-valore personalizzate come metadati nelle richieste e nelle risposte gRPC. Eserciti gRPC & High Performance APIs con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare gRPC & High Performance APIs?
Non è richiesta alcuna esperienza precedente. gRPC & High Performance APIs su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.
Quanto tempo richiede la lezione «Trasmissione di metadati personalizzati»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione gRPC & High Performance APIs?
Sì. Ogni lezione gRPC & High Performance APIs include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Codici di stato e gestione degli errori
- Trasmissione di metadati personalizzati
- Contesto e scadenze
- Modelli avanzati degli errori con google.rpc.Status