Mengirim permintaan RPC dengan Python

Aplikasi dapat berinteraksi dengan Universal Ledger API menggunakan gRPC dan Python. Pendekatan ini melibatkan pembuatan dan penggunaan library klien Python yang dikompilasi dari definisi protocol buffer layanan.

Tutorial ini menunjukkan kepada developer yang ingin menerapkan klien untuk Universal Ledger API cara menyiapkan lingkungan pengembangan yang sesuai, membuat library yang diperlukan, dan melakukan panggilan gRPC menggunakan Python.

Sebelum memulai

Untuk menyelesaikan tutorial ini, Anda memerlukan:

  • Project Google Cloud dengan Universal Ledger API diaktifkan.

  • Peran IAM seperti universalledger.googleapis.com/endpointViewer sehingga Anda setidaknya dapat melihat endpoint Universal Ledger.

  • Kredensial autentikasi lokal untuk akun pengguna Anda. Jalankan perintah berikut untuk mengonfigurasi kredensial ini:

    gcloud auth application-default login

Untuk mempelajari langkah-langkah ini lebih lanjut, lihat panduan Orientasi pratinjau pribadi.

Menyiapkan lingkungan Anda

Petunjuk dalam tutorial ini ditulis untuk lingkungan yang menjalankan Ubuntu 25.04, yang menyertakan Python 3.13 secara default. Anda mungkin perlu mengubah perintah jika menggunakan sistem operasi yang berbeda.

Untuk menyiapkan lingkungan pengembangan, selesaikan langkah-langkah berikut. Langkah-langkah ini akan memandu Anda menginstal alat command line yang diperlukan. Hal ini mencakup penggunaan pipx untuk menginstal grpcio-tools, yang digunakan untuk membuat binding gRPC. Untuk mengisolasi dependensi Python untuk project ini, Anda juga akan membuat dan mengaktifkan lingkungan virtual Python, lalu menginstal library Python yang diperlukan ke dalamnya menggunakan pip.

  1. Instal dependensi dasar menggunakan perintah:

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

  2. Gunakan pipx untuk menginstal aplikasi alat gRPC dan pastikan direktori binernya ditambahkan ke PATH Anda:

    pipx install grpcio-tools
pipx ensurepath

    Tutup dan buka kembali terminal Anda untuk menyelesaikan aktivasi pipx.

  3. Buat direktori induk untuk menyimpan file tutorial ini.

    mkdir gcul_tutorial
cd gcul_tutorial

    Kecuali ditentukan lain, perintah yang tersisa harus dijalankan dari dalam direktori baru ini.

  4. Buat lingkungan virtual Python dan instal library yang tersisa:

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

    Library tersebut adalah:

    • google-auth: untuk menangani autentikasi Google Cloud .
    • googleapis-common-protos: pesan buffer protokol umum yang digunakan di seluruh Google API.
    • grpcio: library gRPC untuk Python.
    • requests: diperlukan oleh beberapa dependensi untuk mengirim permintaan HTTP.

Buat library Protocol Buffer

Untuk berinteraksi dengan Universal Ledger API menggunakan gRPC, aplikasi Python Anda memerlukan library klien yang dikompilasi dari definisi Protocol Buffer (.proto) layanan. Definisi ini menentukan layanan, metode, dan jenis pesan API.

Bagian ini menunjukkan cara mendownload file .proto ini dari repositori googleapis dan menggunakan grpcio-tools yang diinstal untuk membuat kode sumber Python yang diperlukan.

  1. Clone repositori GitHub googleapis tempat definisi Protocol Buffer untuk Google API dipublikasikan.

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

  2. Buat definisi Protocol Buffer dan binding gRPC untuk Universal Ledger API.

    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

    Tindakan ini akan membuat beberapa file di direktori 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

Memanggil Universal Ledger API

Terakhir, buat skrip Python untuk memanggil Universal Ledger API menggunakan library yang dihasilkan. Simpan kode berikut sebagai example_client/endpoints.py.

Dalam kode, ganti nilai placeholder berikut:

  • PROJECT_ID: Google Cloud Project ID Anda–misalnya, my-project.
  • REGION: region Google Cloud tempat endpoint Universal Ledger Anda berada–misalnya, 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())

Untuk menjalankan skrip, buka direktori example_client. Lingkungan virtual harus tetap aktif dari langkah-langkah penyiapan.

  1. Ubah ke direktori skrip:

    cd example_client

    Perintah shell Anda akan mengonfirmasi bahwa lingkungan virtual sudah aktif (misalnya, diawali dengan (example_client)).

  2. Jalankan skrip Python:

    python3 endpoints.py

Anda akan melihat output seperti:

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

Langkah berikutnya