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úfer 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 de gRPC con Python.
Antes de comenzar
Para completar este instructivo, necesitarás lo siguiente:
Un proyecto de Google Cloud 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 introducción.
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. Estos
pasos te guiarán para instalar las herramientas de línea de comandos necesarias. Esto incluye
usar 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.
Instala las dependencias base con los siguientes comandos:
sudo apt updatesudo apt install git pipx python3.13-venvUsa
pipxpara instalar la aplicación de herramientas de gRPC y asegúrate de que su directorio binario se agregue a tuPATH:pipx install grpcio-toolspipx ensurepathCierra y vuelve a abrir la terminal para completar la activación de
pipx.Crea un directorio superior para almacenar los archivos de este instructivo.
mkdir gcul_tutorialcd gcul_tutorialA menos que se especifique lo contrario, los comandos restantes deben ejecutarse desde este directorio nuevo.
Crea un entorno virtual de Python y, luego, instala las bibliotecas restantes:
python3 -m venv example_clientcd example_clientsource ./bin/activatepip3 install google-auth googleapis-common-protos grpcio requestscd ..Estas bibliotecas son las siguientes:
google-auth: para controlar la autenticación de Google Cloud .googleapis-common-protos: Son mensajes comunes de búfer de protocolo que se usan en las APIs de Google.grpcio: Es la biblioteca de gRPC para Python.requests: Algunas de las dependencias lo necesitan para enviar solicitudes HTTP.
Genera las bibliotecas de búferes 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
búfer de protocolo
(.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.
Clona el repositorio de GitHub googleapis, en el que se publican las definiciones de búfer de protocolo para las APIs de Google.
git clone https://github.com/googleapis/googleapis.gitCompila 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.protopython-grpc-tools-protoc --proto_path=googleapis/ \ --python_out=example_client \ --pyi_out=example_client \ google/cloud/universalledger/v1/query.protopython-grpc-tools-protoc --proto_path=googleapis/ \ --python_out=example_client \ --pyi_out=example_client \ google/cloud/universalledger/v1/accounts.protopython-grpc-tools-protoc --proto_path=googleapis/ \ --python_out=example_client \ --pyi_out=example_client \ google/cloud/universalledger/v1/common.protopython-grpc-tools-protoc --proto_path=googleapis/ \ --python_out=example_client \ --pyi_out=example_client \ google/cloud/universalledger/v1/transactions.protopython-grpc-tools-protoc --proto_path=googleapis/ \ --python_out=example_client \ --pyi_out=example_client \ google/cloud/universalledger/v1/types.protopython-grpc-tools-protoc --proto_path=googleapis/ \ --python_out=example_client \ --pyi_out=example_client \ google/cloud/universalledger/v1/status_event.protoEsto 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 del proyecto de Google Cloud , por ejemplo,my-project.REGION: Es la región de 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
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())
Para ejecutar la secuencia de comandos, navega al directorio example_client.
El entorno virtual debería seguir activo desde los pasos de configuración.
Cambia al directorio de la secuencia de comandos:
cd example_clientEl mensaje de la shell debería confirmar que el entorno virtual está activo (por ejemplo, tiene el prefijo
(example_client)).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?
- Consulta todos los métodos de la API de Universal Ledger.
- Obtén información sobre la compatibilidad de gRPC en otros lenguajes.
- Explora las definiciones de búfer de protocolo de la API de Universal Ledger.