Envía solicitudes de RPC con Python

Las aplicaciones pueden interactuar con la API de Universal Ledger a través de gRPC y Python. Este enfoque implica generar y usar bibliotecas cliente de Python compiladas a partir de las definiciones de búferes de protocolo del servicio.

En este instructivo, se muestra a los desarrolladores que desean implementar un cliente para la API de Universal Ledger cómo configurar un entorno de desarrollo adecuado, generar las bibliotecas necesarias y realizar una llamada a gRPC con Python.

Antes de comenzar

Para completar este instructivo, necesitarás lo siguiente:

  • Un Google Cloud proyecto con la API de Universal Ledger habilitada

  • Un rol de IAM, como universalledger.googleapis.com/endpointViewer, para que al menos puedas ver los extremos de Universal Ledger

  • Credenciales de autenticación locales para tu cuenta de usuario. Ejecuta el siguiente comando para configurar estas credenciales:

    gcloud auth application-default login

Para obtener más información sobre estos pasos, consulta la guía de incorporación a la versión preliminar privada.

Configura tu entorno

Las instrucciones de este instructivo están escritas para un entorno que ejecuta Ubuntu 25.04, que incluye Python 3.13 de forma predeterminada. Es posible que debas modificar los comandos si usas un sistema operativo diferente.

Para configurar tu entorno de desarrollo, completa los siguientes pasos. En estos pasos, se explica cómo instalar las herramientas de línea de comandos necesarias. Esto incluye el uso de pipx para instalar grpcio-tools, que se usa para compilar las vinculaciones de gRPC. Para aislar las dependencias de Python de este proyecto, también crearás y activarás un entorno virtual de Python y, luego, instalarás las bibliotecas de Python necesarias en él con pip.

  1. Instala las dependencias básicas con los siguientes comandos:

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

  2. Usa pipx para instalar la aplicación de herramientas de gRPC y asegúrate de que su directorio binario se agregue a tu PATH:

    pipx install grpcio-tools
pipx ensurepath

    Cierra y vuelve a abrir la terminal para completar la activación de pipx.

  3. Crea un directorio principal para contener los archivos de este instructivo.

    mkdir gcul_tutorial
cd gcul_tutorial

    A menos que se especifique lo contrario, los comandos restantes deben ejecutarse desde este nuevo directorio.

  4. Crea un entorno virtual de Python y, luego, instala las bibliotecas restantes:

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

    Estas bibliotecas son las siguientes:

    • google-auth: Para controlar la autenticación de Google Cloud
    • googleapis-common-protos: Son mensajes de búfer de protocolo comunes que se usan en todas las APIs de Google.
    • grpcio: Es la biblioteca de gRPC para Python.
    • requests: Es necesaria para que algunas de las dependencias envíen solicitudes HTTP.

Genera las bibliotecas de búfer de protocolo

Para interactuar con la API de Universal Ledger con gRPC, tu aplicación de Python necesita bibliotecas cliente compiladas a partir de las definiciones de Protocol Buffer (.proto) del servicio. Estas definiciones especifican los servicios, los métodos y los tipos de mensajes de la API.

En esta sección, se muestra cómo descargar estos archivos .proto del repositorio de googleapis y usar el grpcio-tools instalado para generar el código fuente de Python necesario.

  1. Clona el repositorio de GitHub googleapis, en el que se publican las definiciones de búferes de protocolo para las APIs de Google.

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

  2. Compila las definiciones de búfer de protocolo y las vinculaciones de gRPC para la API de 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

    Esto debería crear varios archivos en el directorio 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

Llama a la API de Universal Ledger

Por último, crea una secuencia de comandos de Python para llamar a la API de Universal Ledger con las bibliotecas generadas. Guarda el siguiente código como example_client/endpoints.py.

En el código, reemplaza los siguientes valores de marcador de posición:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud , por ejemplo,my-project.
  • REGION: La región Google Cloud en la que se encuentra tu extremo de Universal Ledger, por ejemplo, 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())

Para ejecutar la secuencia de comandos, navega al directorio example_client. El entorno virtual debería seguir activo desde los pasos de configuración.

  1. Cambia al directorio de la secuencia de comandos:

    cd example_client

    La solicitud de shell debería confirmar que el entorno virtual está activo (por ejemplo, tiene el prefijo (example_client)).

  2. Ejecuta la secuencia de comandos de Python:

    python3 endpoints.py

Deberías ver un resultado como el siguiente:

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

¿Qué sigue?