Inviare richieste RPC con Python

Le applicazioni possono interagire con l'API Universal Ledger utilizzando gRPC e Python. Questo approccio prevede la generazione e l'utilizzo di librerie client Python compilate a partire dalle definizioni dei buffer di protocollo del servizio.

Questo tutorial mostra agli sviluppatori che vogliono implementare un client per l'API Universal Ledger come configurare un ambiente di sviluppo adatto, generare le librerie necessarie ed effettuare una chiamata gRPC utilizzando Python.

Prima di iniziare

Per completare questo tutorial, avrai bisogno di:

  • Un progetto Google Cloud con l'API Universal Ledger abilitata.

  • Un ruolo IAM come universalledger.googleapis.com/endpointViewer per poter almeno visualizzare gli endpoint di Universal Ledger.

  • Credenziali di autenticazione locale per il tuo account utente. Esegui il comando seguente per configurare queste credenziali:

    gcloud auth application-default login

Per saperne di più su questi passaggi, consulta la guida Onboarding della versione di anteprima privata.

Configura l'ambiente

Le istruzioni di questo tutorial sono scritte per un ambiente che esegue Ubuntu 25.04, che include Python 3.13 per impostazione predefinita. Potresti dover modificare i comandi se utilizzi un sistema operativo diverso.

Per configurare l'ambiente di sviluppo, completa i seguenti passaggi. Questi passaggi ti guidano nell'installazione degli strumenti a riga di comando necessari. Ciò include l'utilizzo di pipx per installare grpcio-tools, che viene utilizzato per creare i binding gRPC. Per isolare le dipendenze Python per questo progetto, creerai e attiverai anche un ambiente virtuale Python e installerai le librerie Python richieste utilizzando pip.

  1. Installa le dipendenze di base utilizzando i comandi:

    sudo apt update
sudo apt install git pipx python3.13-venv

  2. Utilizza pipx per installare l'applicazione degli strumenti gRPC e assicurati che la directory dei file binari venga aggiunta a PATH:

    pipx install grpcio-tools
pipx ensurepath

    Chiudi e riapri il terminale per completare l'attivazione di pipx.

  3. Crea una directory principale in cui inserire i file di questo tutorial.

    mkdir gcul_tutorial
cd gcul_tutorial

    Se non diversamente specificato, i comandi rimanenti devono essere eseguiti all'interno di questa nuova directory.

  4. Crea un ambiente virtuale Python e installa le librerie rimanenti:

    python3 -m venv example_client
cd example_client
source ./bin/activate
pip3 install google-auth googleapis-common-protos grpcio requests
cd ..

    Queste librerie sono:

    • google-auth: per la gestione dell' Google Cloud autenticazione.
    • googleapis-common-protos: messaggi buffer di protocollo comuni utilizzati in tutte le API di Google.
    • grpcio: la libreria gRPC per Python.
    • requests: necessario per alcune dipendenze per inviare richieste HTTP.

Genera le librerie Protocol Buffer

Per interagire con l'API Universal Ledger utilizzando gRPC, l'applicazione Python ha bisogno di librerie client compilate dalle definizioni di Protocol Buffer (.proto) del servizio. Queste definizioni specificano i servizi, i metodi e i tipi di messaggi dell'API.

Questa sezione mostra come scaricare questi file .proto dal repository googleapis e utilizzare grpcio-tools installato per generare il codice sorgente Python necessario.

  1. Clona il repository GitHub googleapis in cui vengono pubblicate le definizioni di Protocol Buffer per le API di Google.

    git clone https://github.com/googleapis/googleapis.git

  2. Crea le definizioni di Protocol Buffer e i binding gRPC per l'API Universal Ledger.

    python-grpc-tools-protoc --proto_path=googleapis/ \
    --python_out=example_client \
    --pyi_out=example_client \
    --grpc_python_out=example_client \
    google/cloud/universalledger/v1/universalledger.proto
python-grpc-tools-protoc --proto_path=googleapis/ \
    --python_out=example_client \
    --pyi_out=example_client \
    google/cloud/universalledger/v1/query.proto
python-grpc-tools-protoc --proto_path=googleapis/ \
    --python_out=example_client \
    --pyi_out=example_client \
    google/cloud/universalledger/v1/accounts.proto
python-grpc-tools-protoc --proto_path=googleapis/ \
    --python_out=example_client \
    --pyi_out=example_client \
    google/cloud/universalledger/v1/common.proto
python-grpc-tools-protoc --proto_path=googleapis/ \
    --python_out=example_client \
    --pyi_out=example_client \
    google/cloud/universalledger/v1/transactions.proto
python-grpc-tools-protoc --proto_path=googleapis/ \
    --python_out=example_client \
    --pyi_out=example_client \
    google/cloud/universalledger/v1/types.proto
python-grpc-tools-protoc --proto_path=googleapis/ \
    --python_out=example_client \
    --pyi_out=example_client \
    google/cloud/universalledger/v1/status_event.proto

    In questo modo dovrebbero essere creati diversi file nella directory example_client/google/cloud/universalledger/v1.

    accounts_pb2.py
accounts_pb2.pyi
common_pb2.py
common_pb2.pyi
query_pb2.py
query_pb2.pyi
status_event_pb2.py
status_event_pb2.pyi
transactions_pb2.py
transactions_pb2.pyi
types_pb2.py
types_pb2.pyi
universalledger_pb2.py
universalledger_pb2.pyi
universalledger_pb2_grpc.py

Chiama l'API Universal Ledger

Infine, crea uno script Python per chiamare l'API Universal Ledger utilizzando le librerie generate. Salva il seguente codice come example_client/endpoints.py.

Nel codice, sostituisci i seguenti valori segnaposto:

  • PROJECT_ID: il tuo ID progetto Google Cloud , ad esempio my-project.
  • REGION: la regione Google Cloud in cui si trova l'endpoint Universal Ledger, ad esempio us-east5.
"""Example calling the Universal Ledger API."""

import sys

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
from google.cloud.universalledger.v1 import universalledger_pb2
from google.cloud.universalledger.v1 import universalledger_pb2_grpc
import grpc

API_ENDPOINT = "universalledger.googleapis.com"
PROJECT = "PROJECT_ID"
REGION = "REGION"
SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]


def main() -> str | None:
  # Get the application default credentials.
  credentials, _ = google.auth.default(scopes=SCOPES)

  # Get an HTTP request function to refresh credentials.
  refresh_request = google.auth.transport.requests.Request()

  # Create a secure channel to the API endpoint.
  with google.auth.transport.grpc.secure_authorized_channel(
      credentials, refresh_request, API_ENDPOINT
  ) as channel:
    # Create the client stub using the generated code.
    stub = universalledger_pb2_grpc.UniversalLedgerStub(channel)

    # Parent location for GCUL network endpoints.
    parent = f"projects/{PROJECT}/locations/{REGION}"

    # Build the request message.
    request = universalledger_pb2.ListEndpointsRequest(parent=parent)

    # Make the gRPC call.
    try:
      metadata = [("x-goog-request-params", f"parent={parent}")]
      response = stub.ListEndpoints(request, metadata=metadata)
    except grpc.RpcError as exc:
      return f"{exc.code().name}: {exc.details()}"

    if not response.endpoints:
      return f"No endpoints found under: {parent}"

    print("Found the following endpoints:")
    for endpoint in response.endpoints:
      print("-", endpoint.name)


if __name__ == "__main__":
  sys.exit(main())

Per eseguire lo script, vai alla directory example_client. L'ambiente virtuale dovrebbe essere ancora attivo dai passaggi di configurazione.

  1. Passa alla directory dello script:

    cd example_client

    Il prompt della shell dovrebbe confermare che l'ambiente virtuale è attivo (ad esempio, è preceduto da (example_client)).

  2. Esegui lo script Python:

    python3 endpoints.py

Dovresti visualizzare un output simile al seguente:

Found the following endpoints:
- projects/my-project/locations/us-east5/endpoint/gcul-pilot-testing
- projects/my-project/locations/us-east5/endpoint/gcul-user-testing

Passaggi successivi