Enviar solicitações de RPC com Python

Os aplicativos podem interagir com a API Universal Ledger usando gRPC e Python. Essa abordagem envolve a geração e o uso de bibliotecas de cliente Python compiladas a partir das definições de buffer de protocolo do serviço.

Este tutorial mostra aos desenvolvedores que querem implementar um cliente para a API Universal Ledger como configurar um ambiente de desenvolvimento adequado, gerar as bibliotecas necessárias e fazer uma chamada gRPC usando Python.

Antes de começar

Para concluir este tutorial, você vai precisar de:

  • Um Google Cloud projeto com a API Universal Ledger ativada.

  • Um papel do IAM, como universalledger.googleapis.com/endpointViewer, para que você possa pelo menos visualizar os endpoints do Universal Ledger.

  • Credenciais de autenticação local para sua conta de usuário. Execute o comando a seguir para configurar essas credenciais:

    gcloud auth application-default login

Para saber mais sobre essas etapas, consulte o guia de integração do pré-lançamento particular.

Configurar o ambiente

As instruções neste tutorial foram escritas para um ambiente que executa o Ubuntu 25.04, que inclui o Python 3.13 por padrão. Talvez seja necessário modificar os comandos se você estiver usando um sistema operacional diferente.

Para configurar seu ambiente de desenvolvimento, conclua as etapas a seguir. Essas etapas orientam você na instalação das ferramentas de linha de comando necessárias. Isso inclui o uso de pipx para instalar grpcio-tools, que é usado para criar as vinculações gRPC. Para isolar as dependências do Python para este projeto, você também vai criar e ativar um ambiente virtual do Python e, em seguida, instalar as bibliotecas necessárias do Python usando pip.

  1. Instale as dependências básicas usando os comandos:

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

  2. Use pipx para instalar o aplicativo de ferramentas gRPC e verifique se o diretório binário dele foi adicionado ao seu PATH:

    pipx install grpcio-tools
pipx ensurepath

    Feche e reabra o terminal para concluir a ativação do pipx.

  3. Crie um diretório pai para conter os arquivos deste tutorial.

    mkdir gcul_tutorial
cd gcul_tutorial

    A menos que especificado de outra forma, os comandos restantes precisam ser executados nesse novo diretório.

  4. Crie um ambiente virtual do Python e instale as bibliotecas restantes:

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

    Essas bibliotecas são:

    • google-auth: para processar a Google Cloud autenticação.
    • googleapis-common-protos: mensagens comuns de buffer de protocolo usadas nas APIs do Google.
    • grpcio: a biblioteca gRPC para Python.
    • requests: necessária para algumas das dependências para enviar solicitações HTTP.

Gerar as bibliotecas de buffer de protocolo

Para interagir com a API Universal Ledger usando gRPC, o aplicativo Python precisa de bibliotecas de cliente compiladas a partir das definições de buffer de protocolo (.proto) do serviço. Essas definições especificam os serviços, métodos e tipos de mensagens da API.

Esta seção mostra como fazer o download desses arquivos .proto do repositório googleapis e usar as grpcio-tools instaladas para gerar o código-fonte Python necessário.

  1. Clone o repositório do GitHub googleapis em que as definições de buffer de protocolo para APIs do Google são publicadas.

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

  2. Crie as definições de buffer de protocolo e as vinculações gRPC para a 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

    Isso vai criar vários arquivos no diretório 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

Chamar a API Universal Ledger

Por fim, crie um script Python para chamar a API Universal Ledger usando as bibliotecas geradas. Salve o código a seguir como example_client/endpoints.py.

No código, substitua os seguintes valores de marcador:

  • PROJECT_ID: seu Google Cloud ID do projeto, por exemplo, my-project.
  • REGION: aregião em que o Google Cloud endpoint do Universal Ledger está localizado, por exemplo, 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 executar o script, navegue até o diretório example_client. O ambiente virtual ainda precisa estar ativo nas etapas de configuração.

  1. Altere para o diretório do script:

    cd example_client

    O prompt do shell precisa confirmar que o ambiente virtual está ativo (por exemplo, ele é prefixado com (example_client)).

  2. Execute o script Python:

    python3 endpoints.py

Você vai receber uma saída como esta:

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

A seguir