Enviar solicitações de RPC com Python

Os aplicativos podem interagir com a API Universal Ledger usando gRPC e Python. Essa abordagem envolve gerar e usar bibliotecas de cliente do Python compiladas com base nas definições de buffer de protocolo do serviço.

Neste tutorial, mostramos 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 projeto do Google Cloud 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 Primeiros passos.

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 o ambiente de desenvolvimento, siga as etapas abaixo. Estas etapas orientam você na instalação das ferramentas de linha de comando necessárias. Isso inclui usar pipx para instalar grpcio-tools, que é usado para criar as vinculações do 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 do Python necessárias usando pip.

  1. Instale as dependências de base 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 garantir que o diretório binário dele seja adicionado ao 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 armazenar 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 autenticação do Google Cloud .
    • googleapis-common-protos: mensagens comuns de buffer de protocolo usadas nas APIs do Google.
    • grpcio: a biblioteca gRPC para Python.
    • requests: necessário para que algumas das dependências enviem solicitações HTTP.

Gerar as bibliotecas de buffer de protocolo

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

Nesta seção, mostramos como fazer o download desses arquivos .proto do repositório googleapis e usar o grpcio-tools instalado 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 as 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: o ID do projeto do Google Cloud , por exemplo, my-project.
  • REGION: a região do Google Cloud em que o 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

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 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 deve confirmar que o ambiente virtual está ativo (por exemplo, ele tem o prefixo (example_client)).

  2. Execute o script Python:

    python3 endpoints.py

Você verá uma saída como:

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