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 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 locali per il tuo account utente. Esegui il comando seguente per configurare queste credenziali:

    gcloud auth application-default login

Per scoprire di più su questi passaggi, consulta la guida Inizia.

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. Se utilizzi un sistema operativo diverso, potresti dover modificare i comandi.

Per configurare l'ambiente di sviluppo, completa i seguenti passaggi. Questi passaggi ti guideranno 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, quindi 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 relativa directory binaria venga aggiunta alla tua 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'autenticazione Google Cloud .
    • googleapis-common-protos: messaggi buffer di protocollo comuni utilizzati nelle API di Google.
    • grpcio: la libreria gRPC per Python.
    • requests: richiesto da alcune dipendenze per inviare richieste HTTP.

Genera le librerie di buffer di protocollo

Per interagire con l'API Universal Ledger utilizzando gRPC, la tua applicazione Python deve avere librerie client compilate dalle definizioni del buffer di protocollo (.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 sono pubblicate le definizioni dei buffer di protocollo per le API di Google.

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

  2. Crea le definizioni dei buffer di protocollo e le associazioni 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

    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

PROJECT = "PROJECT_ID"
REGION = "REGION"
API_ENDPOINT = f"universalledger.{REGION}.rep.googleapis.com"
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 degli 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