Envoyer des requêtes RPC avec Python

Les applications peuvent interagir avec l'API Universal Ledger à l'aide de gRPC et de Python. Cette approche implique la génération et l'utilisation de bibliothèques clientes Python compilées à partir des définitions de tampon de protocole du service.

Ce tutoriel explique aux développeurs qui souhaitent implémenter un client pour l'API Universal Ledger comment configurer un environnement de développement approprié, générer les bibliothèques nécessaires et effectuer un appel gRPC à l'aide de Python.

Avant de commencer

Pour suivre ce tutoriel, vous aurez besoin des éléments suivants :

  • Un Google Cloud projet avec l'API Universal Ledger activée.

  • Un rôle IAM tel que universalledger.googleapis.com/endpointViewer pour pouvoir au moins afficher les points de terminaison Universal Ledger.

  • Des identifiants d'authentification locaux pour votre compte utilisateur. Exécutez la commande suivante pour configurer ces identifiants :

    gcloud auth application-default login

Pour en savoir plus sur ces étapes, consultez le guide d'intégration à la version bêta privée.

Configurer votre environnement

Les instructions de ce tutoriel sont écrites pour un environnement exécutant Ubuntu 25.04, qui inclut Python 3.13 par défaut. Vous devrez peut-être modifier les commandes si vous utilisez un autre système d'exploitation.

Pour configurer votre environnement de développement, procédez comme suit. Ces étapes vous guident dans l'installation des outils de ligne de commande nécessaires. Cela inclut l'utilisation de pipx pour installer grpcio-tools, qui permet de créer les liaisons gRPC. Pour isoler les dépendances Python de ce projet, vous allez également créer et activer un environnement virtuel Python, puis y installer les bibliothèques Python requises à l'aide de pip.

  1. Installez les dépendances de base à l'aide des commandes suivantes :

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

  2. Utilisez pipx pour installer l'application d'outils gRPC et assurez-vous que son répertoire binaire est ajouté à votre PATH :

    pipx install grpcio-tools
pipx ensurepath

    Fermez et rouvrez votre terminal pour terminer l'activation de pipx.

  3. Créez un répertoire parent pour contenir les fichiers de ce tutoriel.

    mkdir gcul_tutorial
cd gcul_tutorial

    Sauf indication contraire, les commandes restantes doivent être exécutées à partir de ce nouveau répertoire.

  4. Créez un environnement virtuel Python et installez les bibliothèques restantes :

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

    Ces bibliothèques sont les suivantes :

    • google-auth: pour la gestion de l'authentification. Google Cloud
    • googleapis-common-protos: messages de tampon de protocole courants utilisés dans les API Google.
    • grpcio : bibliothèque gRPC pour Python.
    • requests : nécessaire à certaines dépendances pour envoyer des requêtes HTTP.

Générer les bibliothèques de tampon de protocole

Pour interagir avec l'API Universal Ledger à l'aide de gRPC, votre application Python a besoin de bibliothèques clientes compilées à partir des définitions de tampon de protocole (.proto) du service. Ces définitions spécifient les services, les méthodes et les types de messages de l'API.

Cette section explique comment télécharger ces fichiers .proto à partir du dépôt googleapis et utiliser les grpcio-tools installés pour générer le code source Python nécessaire.

  1. Clonez le dépôt GitHub googleapis où sont publiées les définitions de tampon de protocole pour les API Google.

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

  2. Créez les définitions de tampon de protocole et les liaisons gRPC pour 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

    Cela devrait créer plusieurs fichiers dans le répertoire 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

Appeler l'API Universal Ledger

Enfin, créez un script Python pour appeler l'API Universal Ledger à l'aide des bibliothèques générées. Enregistrez le code suivant sous le nom example_client/endpoints.py.

Dans le code, remplacez les valeurs d'espace réservé suivantes :

  • PROJECT_ID : ID de votre Google Cloud projet, par exemple my-project.
  • REGION : région où se trouve votre point de terminaison Universal Ledger, par exemple us-east5. Google Cloud 
"""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())

Pour exécuter le script, accédez au répertoire example_client. L'environnement virtuel doit toujours être actif depuis les étapes de configuration.

  1. Accédez au répertoire du script :

    cd example_client

    L'invite de l'interface système doit confirmer que l'environnement virtuel est actif (par exemple, il est précédé du préfixe (example_client)).

  2. Exécutez le script Python :

    python3 endpoints.py

Vous devriez voir une sortie semblable à celle-ci :

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

Étape suivante